Technical Documentation

Direct Asset Mapping

Every Lockbox maintains precise mappings between the tokenId and deposited assets using secure on-chain storage structures:

mapping(uint256 => uint256) internal _baggedETH;


mapping(uint256 => mapping(address => uint256)) internal _erc20Balances;
mapping(uint256 => address[]) internal _erc20TokenAddresses;
mapping(uint256 => mapping(address => bool)) internal _erc20Known;


struct BaggedNFT { address nftContract; uint256 nftTokenId; }
mapping(uint256 => bytes32[]) internal _nftKeys;
mapping(uint256 => mapping(bytes32 => BaggedNFT)) internal _nftData;
mapping(uint256 => mapping(bytes32 => bool)) internal _nftKnown;

These storage structures ensure that each asset is linked directly to a specific Lockbox token ID, creating a secure 1:1 relationship between your NFT and the assets it contains.

Maximum Precision Guarantees

function _depositETH(uint256 tokenId, uint256 amountETH) internal {
    if (amountETH == 0) return;
    _baggedETH[tokenId] += amountETH;
}

EIP-5192 Standard Implementation

The Lockx contract implements the EIP-5192 standard through the IERC5192 interface:

interface IERC5192 {
    /// Emitted exactly once when a token becomes locked (non-transferable).
    event Locked(uint256 tokenId);

    /// Emitted if a token ever becomes unlocked (not used, but must be declared for compliance).
    event Unlocked(uint256 tokenId);

    /// MUST always return true for every existing Lockbox.
    function locked(uint256 tokenId) external view returns (bool);
}

When a Lockbox is minted, it's immediately marked as locked and an EIP-5192 Locked event is emitted:

uint256 tokenId = _tokenIdCounter.current();
_tokenIdCounter.increment();

_safeMint(to, tokenId);
emit Locked(tokenId); 
initialize(tokenId, lockxPublicKey);

Transfer Prevention

The core of the soulbound mechanism is the overridden _transfer function, which prevents any transfers of Lockboxes:

/// Disable any transfer—soul‐bound enforcement.
function _transfer(address, address, uint256) internal pure override {
    revert TransfersDisabled();
}

This simple but powerful override ensures that no standard transfer function can move a Lockbox from its original owner's wallet. All transfer attempts will immediately revert with a TransfersDisabled error.

The contract also implements the required locked function, which confirms that a token is non-transferrable:

/**
 * @notice Always returns true for existing Lockboxes (soul‐bound).
 * @param tokenId The ID of the Lockbox.
 * @return Always true.
 * @dev Reverts if token does not exist.
 */
function locked(uint256 tokenId) external view override returns (bool) {
    if (!_exists(tokenId)) revert NonexistentToken();
    return true;
}

Interface Detection

To ensure applications can detect that Lockboxes implement the EIP-5192 soulbound standard, the contract includes the interface detection method:

function supportsInterface(bytes4 interfaceId)
    public view override(ERC721, ERC721Enumerable)
    returns (bool)
{
    if (interfaceId == 0xb45a3c0e) return true; 
    return super.supportsInterface(interfaceId);
}

This enables wallets, marketplaces, and other applications to detect and appropriately handle the soulbound nature of Lockboxes.

Supported Asset Types

All these asset types can be stored within a single Lockbox, creating a consolidated view of your digital assets in one place.

Batch Management

Lockx allows for efficient batch operations, enabling you to deposit or withdraw multiple assets in a single transaction. This significantly reduces gas costs and simplifies asset management.

Batch deposit operations

The batch deposit function allows simultaneous deposit of ETH, ERC20 tokens, and NFTs with a single transaction. Here's how the contract handles different asset types:

function batchDeposit(
    uint256 tokenId,
    uint256 amountETH,
    address[] calldata tokenAddresses,
    uint256[] calldata tokenAmounts,
    address[] calldata nftContracts,
    uint256[] calldata nftTokenIds,
    bytes32 referenceId
) external payable nonReentrant {
    _requireOwnsBag(tokenId);
    if (msg.value != amountETH) revert ETHMismatch();
    _batchDeposit(tokenId, amountETH, tokenAddresses, tokenAmounts, nftContracts, nftTokenIds, referenceId);
}


function _batchDeposit(
    uint256 tokenId,
    uint256 amountETH,
    address[] calldata tokenAddresses,
    uint256[] calldata tokenAmounts,
    address[] calldata nftContracts,
    uint256[] calldata nftTokenIds,
    bytes32 referenceId
) internal {
    if (tokenAddresses.length != tokenAmounts.length || nftContracts.length != nftTokenIds.length) revert MismatchedInputs();
    if (amountETH > 0) _baggedETHs[tokenId].ethAmount += amountETH;

    
    for (uint256 i; i < tokenAddresses.length; ) {
        _depositERC20(tokenId, tokenAddresses[i], tokenAmounts[i], referenceId);
        unchecked { ++i; }
}

    
    for (uint256 i; i < nftContracts.length; ) {
        _depositERC721(tokenId, nftContracts[i], nftTokenIds[i], referenceId);
        unchecked { ++i; }
    }
}

The batch deposit process intelligently verifies all inputs and then processes each asset type using the appropriate deposit method. Notice the use of unchecked blocks for gas optimization in the loops.

Batch withdrawal operations

Similarly, the batch unbag function enables withdraw multiple assets in a single transaction, with just one signature verification. This is especially valuable for efficient portfolio management:

function batchUnbag(
    uint256 tokenId,
    bytes32 messageHash,
    bytes memory signature,
    uint256 amountETH,
    address[] calldata tokenAddresses,
    uint256[] calldata tokenAmounts,
    address[] calldata nftContracts,
    uint256[] calldata nftTokenIds,
    address recipient,
    bytes32 referenceId,
    uint256 signatureExpiry
) external nonReentrant {
    
    _requireOwnsBag(tokenId);
    if (block.timestamp > signatureExpiry) revert SignatureExpired();
    if (recipient == address(0)) revert ZeroAddress();
    
    
    bytes memory data = abi.encode(
    tokenId, amountETH, tokenAddresses, tokenAmounts, 
    nftContracts, nftTokenIds, recipient, referenceId, 
    msg.sender, signatureExpiry
);
verifySignature(tokenId, messageHash, signature, address(0), OperationType.BATCH_UNBAG, data);


if (amountETH > 0) {
        if (_baggedETHs[tokenId].ethAmount < amountETH) revert InsufficientETH();
    _baggedETHs[tokenId].ethAmount -= amountETH;
    (bool success, ) = payable(recipient).call{value: amountETH}("");
        if (!success) revert ETHTransferFailed();
}

    
    
    
    
    
    
    emit Unbagged(tokenId, referenceId);
}

Key benefits of batch operations

The multi-asset batch operations provide several important advantages:

• Gas efficiency: Batch operations significantly reduce total gas costs compared to individual transactions
• Simplified management: Deposit or withdraw multiple assets with a single transaction
• Unified security: All operations are protected by the same signature verification process
• Asset diversity: Handle ETH, any ERC20 token, and any ERC721 NFT simultaneously
• Portfolio rebalancing: Easily adjust your Secured assets in a single transaction
• Optimized loops: Uses unchecked blocks for gas optimization in loops with array bounds guarantees

Defense Against Common Wallet Attacks

Smart Contract Security Measures

function unbagETH(
    uint256 tokenId,
    bytes32 messageHash,
    bytes memory signature,
    uint256 amount,
    address recipient,
    bool burnToken,
    bytes32 referenceId
) public nonReentrant {
    
}

function verifySignature(
    uint256 tokenId,
    bytes32 messageHash,
    bytes memory signature,
    address newLockxPublicKey,
    OperationType opType,
    bytes memory data
) internal {
    
    tokenData.nonce++;
    
}

function unbagETH(
    uint256 tokenId,
    bytes32 messageHash,
    bytes memory signature,
    uint256 amount,
    address recipient,
    bool burnToken,
    bytes32 referenceId
) public nonReentrant {
    if (ownerOf(tokenId) != msg.sender) revert NotOwner();
    
    
    bytes memory data = abi.encode(amount, recipient, burnToken, referenceId);
    verifySignature(tokenId, messageHash, signature, address(0), OperationType.UNBAG_ETH, data);
    
    
}

How Key Fraction Technology Works

1. User Authentication: You sign a unique message that includes a random "message key fraction" generated for your session.

2. Server-Side Key Fraction: Lockx generates a random key fraction that's encrypted and stored securely in Google Cloud KMS (Key Management Service). This is protected by Hardware Security Modules (HSM) with FIPS level 3 compliance for enterprise-grade security.

3. Ephemeral Key Derivation: When needed, your signature is combined with the server-side key fraction to deterministically derive the public/private key pair through a cryptographic hash function. This creates a unique, one-time-use signing key that exists only for the duration of the specific operation.

4. Expiring Signatures: All generated signatures have a short lifespan and include operation-specific data that prevents them from being reused for other purposes. This time-bound approach provides enhanced security by limiting the window of opportunity for potential attacks.

5. Immediate Cleanup: After the operation is completed, the derived private key is immediately removed from memory. Keys must be rederived for every operation, ensuring no persistent key material exists that could be compromised.

Key Export & Recovery

Lockx provides you with the encrypted key fraction during setup, which you can securely store as a backup. This fraction is essential for key recovery and export:

2FA Protection

Lockx implements robust 2FA (Two-Factor Authentication) protection using the same trustless key derivation approach:

Using Self custody mode

To use Self custody mode for signing transactions, follow these steps:

1. Copy the JSON provided to you during your unbagging authentication process into Remix
2. Verify the parameters are correct
3. Sign into Remix with your secondary signer
4. Right click the file holding the JSON and click sign
5. Copy the signature provided in the terminal to the frontend modal
6. Click submit signature

DOMAIN:
  name: "Lockx"
  version: "3"
  chainId: 1
  verifyingContract: 0x1234...5678

TYPE: Operation
  tokenId: uint256
  nonce: uint256
  opType: uint8
  dataHash: bytes32

VALUE:
  tokenId: 123
  nonce: 45
  opType: 1
  dataHash: [automatically generated from the parameters below]

OPERATION DATA (1):
  signatureExpiry: 1688654321 (expires: in 15 minutes)
  amount: 1000000000000000000 wei
  recipient: 0xabcd...ef01

What is EIP-712?

EIP-712 is an Ethereum Improvement Proposal that defines a standard for signing typed structured data. It improves upon simple message signing by:

• Providing human-readable data in signing interfaces
• Enabling structured data with types
• Preventing signature replay across different domains
• Ensuring consistent hashing across implementations

Implementation in Lockx

In our contracts, EIP-712 is implemented through OpenZeppelin's EIP712 contract:

bytes32 private constant OPERATION_TYPEHASH =
    keccak256("Operation(uint256 tokenId,uint256 nonce,uint8 opType,bytes32 dataHash)");

constructor(address erc721Address)
    EIP712("Lockx", "1")
{
    _erc721 = ERC721(erc721Address);
}

When a user initiates an operation like withdraw assets, the frontend will:

1. Construct the typed data according to EIP-712 specification
2. Request the user to sign this data with their wallet
3. Submit the signature along with the operation parameters to the contract
4. The contract will verify the signature before executing the operation

Benefits of verified contracts

• Full transparency of contract code
• Direct interaction with contract functions
• Ability to verify transaction details
• Independence from Lockx frontend
• Permanent access to your assets

Interacting with Lockx contracts on Etherscan

[bagETH]: 1000000000000000000
[erc20Tokens]: [
  [0]: {
    tokenAddress: 0x6B175474E89094C44Da98b954EedeAC495271d0F,
    balance: 50000000000000000000
  }
]
[nfts]: [
  [0]: {
    nftContract: 0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D,
    nftTokenId: 1234
  }
]