CommodityCustody, a contract that holds both commodity tokens (physical-backed ERC-20s representing gold, silver, and other commodities via the Commodity Token License) and standard ERC-20 settlement assets (USDC) in a unified internal ledger. Users deposit tokens into custody before placing orders. The off-chain matching engine locks balances when orders match, then settles atomically on-chain. Liquidation from connected lending markets is handled through a dedicated router, supporting both internal buyer matching and external sale paths.
Licensees also receive access to Trusset’s off-chain orderbook matching engine and RWA price feeds through the Issuer App, enabling a complete trading infrastructure without building matching logic from scratch.
What’s Included
The license ships one deployable contract with external interface dependencies:| Contract | Purpose |
|---|---|
CommodityCustody | UUPS-upgradeable custody with deposit/withdraw, balance locking, trade settlement (single, batch, priority), liquidation handling, and emergency controls |
ILendingMarket | Callback interface for lending market liquidation settlement |
CommodityCustody interacts with externally deployed contracts: CommodityTokenUpgradeable instances (which enforce their own transfer compliance), USDC (or another ERC-20) for settlement, and a LiquidationRouter that bridges between lending markets and custody.
Key Capabilities
Hybrid orderbook settlement. Users deposit tokens into custody, the off-chain matching engine pairs orders and locks balances, then the operator settles trades atomically on-chain. Internal transfers between custody accounts are purely ledger operations that bypass on-chain compliance - the matching engine validates compliance before matching. Single trades, batch settlements (with gas-aware processing), and priority liquidation trades are all supported. Token-enforced compliance. Unlike the Stock Orderbook where the custody contract explicitly callscanTransfer, CommodityCustody delegates all compliance to the commodity token itself. Commodity tokens enforce KYC checks, whitelist/blacklist restrictions, account freezing, and pause state inside their own transfer() and transferFrom() implementations. If any check fails during deposit or withdrawal, the commodity token reverts the transfer directly.
Liquidation integration. Two settlement paths handle liquidated collateral from connected lending markets. Internal buyer matching moves tokens within custody and routes USDC to the lending market via the router. External sale handles off-custody sales where the operator provides USDC proceeds. Both paths notify the lending market through receiveLiquidationProceeds callbacks. Partial fills are supported for internal buyer liquidations.
Emergency controls. Per-user withdrawal freezes prevent front-running during liquidation. A global withdrawal pause acts as a circuit breaker. These are independent of the commodity token’s own freeze and pause mechanisms, providing a third layer of protection at the custody level.
Role Architecture
The contract uses a three-role model:| Role | Assigned to | Responsibilities |
|---|---|---|
| Admin | Deploying institution (multi-sig) | Token registration, router/USDC configuration, withdrawal pause, upgrade authorization, operator management, two-step admin transfer |
| Operator | Matching engine / settlement service | Lock/unlock balances, settle trades (single, batch, priority), settle liquidations, freeze/unfreeze users |
| Liquidation Router | External router contract | Deliver seized collateral via receiveLiquidatedCollateral |
transferAdmin then acceptAdmin) to prevent accidental transfer to an incorrect address.
Compliance Model
Trade settlements within custody do not validate on-chain compliance. Compliance is enforced at the deposit and withdrawal boundaries by the commodity token itself - not by the custody contract. The off-chain matching engine is responsible for validating that both counterparties are eligible before matching orders. Under MiCA, the deploying institution’s matching engine carries the obligation of ensuring beneficial ownership transfers at settlement time are compliant. This delegation model means CommodityCustody treats all tokens as standard ERC-20s internally. The commodity token’stransfer() and transferFrom() implementations are the enforcement boundary. If a commodity token issuer changes the transfer restriction mode (e.g., from NONE to WHITELIST) without whitelisting the custody contract, all deposits and withdrawals for that token will break. Monitor the commodity token’s TransferRestrictionModeUpdated event to stay ahead of configuration changes.