Trusset Protocol - Infrastructure for Asset Tokenization

The Commodity Orderbook suite consists of a single deployable contract (CommodityCustody) with external dependencies on commodity tokens, USDC, a LiquidationRouter, and optionally a lending market. This page covers the contract’s architecture, state layout, and complete function reference.

Architecture

CommodityCustody maintains an internal ledger of user balances using a keccak256(user, token) key scheme. Deposits move tokens from the user into the contract and credit the internal balance. Withdrawals debit the internal balance and transfer tokens out. Trade settlements move balances between users internally without any on-chain token transfer. All tokens - commodity tokens and USDC alike - are registered and treated uniformly via addSupportedToken. There is no compliance classification flag. Commodity tokens enforce their own compliance (KYC, whitelist/blacklist, frozen accounts, pause state) inside their transfer() and transferFrom() implementations. If the custody contract or user fails a compliance check, the commodity token reverts the transfer directly.

                      +--------------------+
                      |  CommodityCustody  |
                      |  (this contract)   |
                      +--------+-----------+
                               |
          +--------------------+--------------------+
          |                    |                    |
+---------v----------+ +------v--------+  +--------v---------+
| CommodityToken     | |    USDC       |  | LiquidationRouter|
| (self-enforcing    | |   (IERC20)    |  |   (external)     |
|  compliance)       | +---------------+  +--------+---------+
+---------+----------+                             |
          |                                +-------v---------+
+---------v----------+                     |  LendingMarket  |
| IdentityRegistry   |                     | (ILendingMarket)|
|   (indirect)       |                     +-----------------+
+--------------------+

The IdentityRegistry is never called directly by CommodityCustody. It is referenced indirectly through the commodity token’s transfer validation when KYC is required on that token.

Compliance Model Difference from StockCustody

StockCustody performs pre-transfer compliance checks via ISecurityToken.canTransfer() and classifies tokens as compliance-checked or standard. CommodityCustody does not - commodity tokens enforce compliance inside their own transfer() and transferFrom() implementations. The custody contract has no complianceChecked flag and no checkTransferability function. If a compliance check fails, the commodity token reverts the transfer with its own error codes, not CommodityCustody errors.

CommodityCustody

UUPS-upgradeable custody contract with internal ledger, trade settlement, liquidation handling, and emergency controls.

Initialization

function initialize(
    address _admin,              // Contract administrator (cannot be zero)
    address _operator,           // Settlement operator (zero defaults to admin)
    address _liquidationRouter,  // Liquidation router address (cannot be zero)
    address _usdc                // USDC token address (cannot be zero)
) external initializer

The initializer sets up the admin, operator, liquidation router, and USDC address. If _operator is address(0), it defaults to the admin address.

State Variables

Variable	Type	Description
`admin`	`address`	Contract administrator
`pendingAdmin`	`address`	Pending admin during two-step transfer
`settlementOperator`	`address`	Operator authorized for settlements
`liquidationRouter`	`address`	External router for liquidation flows
`usdc`	`address`	USDC settlement token address
`withdrawalsPaused`	`bool`	Global withdrawal pause flag
`pendingLiquidationCount`	`uint256`	Count of unsettled liquidations
`_balances`	`mapping(bytes32 => uint256)`	Total balance per user-token pair
`_lockedBalances`	`mapping(bytes32 => uint256)`	Locked balance per user-token pair
`_processedSettlements`	`mapping(bytes32 => bool)`	Deduplication for settlement IDs
`_supportedTokens`	`mapping(address => bool)`	Registered token whitelist
`_frozenUsers`	`mapping(address => bool)`	Per-user withdrawal freeze
`liquidations`	`mapping(uint256 => LiquidationInfo)`	Liquidation records

Access Control

Show Modifier definitions

Modifier	Allows
`onlyAdmin`	`admin` only
`onlyOperator`	`settlementOperator` or `admin`
`onlyLiquidationRouter`	`liquidationRouter` only
`tokenSupported(token)`	Reverts if token is not registered

Admin Management

Admin transfer is a two-step process to prevent accidental transfer to an incorrect address.

function transferAdmin(address newAdmin) external onlyAdmin
function acceptAdmin() external  // only callable by pendingAdmin

function updateOperator(address newOperator) external onlyAdmin

Token Configuration

function addSupportedToken(address token) external onlyAdmin
function removeSupportedToken(address token) external onlyAdmin

Both commodity tokens and settlement tokens (USDC) are registered the same way. There is no compliance classification - commodity tokens enforce their own compliance in transfer() and transferFrom(). Removing a token from the supported list does not lock user funds. Users can still withdraw unsupported tokens. New deposits and trade settlements for the removed token are blocked.

Deposit and Withdrawal

function deposit(address token, uint256 amount) external nonReentrant tokenSupported(token)

Transfers tokens from the caller into custody via transferFrom. For commodity tokens, the token itself enforces KYC, whitelist/blacklist, frozen, and pause checks during the transfer. If any check fails, the commodity token reverts with its own error codes. The caller must have approved the custody contract for the deposit amount.

function withdraw(address token, uint256 amount) external nonReentrant

Withdraws available (unlocked) tokens from custody via transfer. The commodity token enforces compliance during the transfer. Blocked if the user is frozen in custody or withdrawals are globally paused. Allows withdrawal of unsupported tokens to prevent fund lockout after token removal.

There is no checkTransferability pre-check function on CommodityCustody. Commodity token compliance failures surface as reverts from the token contract itself during deposit or withdraw. Integrate with the commodity token’s compliance view functions directly (e.g., check whitelist status, KYC verification, frozen state) before submitting deposit or withdrawal transactions.

Balance Locking

The operator locks user balances when orders are matched, before settlement.

function lockBalance(address user, address token, uint256 amount, bytes32 lockId)
    external onlyOperator tokenSupported(token)

Locks amount from the user’s available balance (total minus already locked). Reverts with InsufficientBalance if available balance is insufficient.

function unlockBalance(address user, address token, uint256 amount, bytes32 lockId)
    external onlyOperator tokenSupported(token)

Unlocks previously locked tokens. Reverts with InsufficientLockedBalance if the locked balance is less than amount.

Trade Settlement

function settleTrade(
    bytes32 settlementId,
    address maker, address taker,
    address baseToken, address quoteToken,
    uint256 baseAmount, uint256 quoteAmount,
    bool makerIsBuyer
) external onlyOperator nonReentrant

Atomically transfers locked base tokens from seller to buyer and locked quote tokens from buyer to seller. These are internal ledger movements only - no on-chain token transfers occur. Both parties must have sufficient locked balances. The settlementId must be unique - reuse reverts with SettlementAlreadyProcessed.

function batchSettleTrades(
    bytes32 batchId,
    bytes32[] calldata settlementIds,
    address[] calldata makers,
    address[] calldata takers,
    address[] calldata baseTokens,
    address[] calldata quoteTokens,
    uint256[] calldata baseAmounts,
    uint256[] calldata quoteAmounts,
    bool[] calldata makerIsBuyers
) external onlyOperator nonReentrant

Settles multiple trades in one transaction. Skips already-processed settlement IDs. Includes a gas guard that stops processing if remaining gas drops below 80,000 per iteration. Emits BatchSettled(batchId, settledCount, totalSubmitted) so callers can detect partial completion.

The batchSettleTrades function takes 9 calldata array parameters, which exceeds the legacy compilation pipeline’s stack limit. The Solidity compiler must use viaIR: true. See Integration for compiler configuration.

function settlePriorityTrade(
    bytes32 settlementId,
    address liquidatedUser, address buyer,
    address baseToken, address quoteToken,
    uint256 baseAmount, uint256 quoteAmount
) external onlyOperator nonReentrant

Priority settlement for liquidated positions. The liquidated user’s tokens must be locked first. Use freezeUser() before locking to prevent withdrawal front-running between the lock and settlement steps. Emits both PrioritySettlement and TradeSettled.

Liquidation

Receiving Collateral

function receiveLiquidatedCollateral(
    address token, uint256 amount, uint256 debtOwed,
    address borrower, address lendingMarket, uint256 liquidationId
) external onlyLiquidationRouter nonReentrant

Called by the liquidation router to deliver seized collateral into custody. Tokens are pulled from the router (which must have approved the custody contract) and credited to an internal liquidation pool keyed to address(this).

External Sale Settlement

function settleLiquidation(
    uint256 liquidationId, uint256 usdcReceived, address tokenRecipient
) external onlyOperator nonReentrant

Settles after the operator sells tokens through an external venue. Commodity tokens transfer to tokenRecipient - the commodity token enforces its own compliance during this transfer. USDC is pulled from the operator and sent to the liquidation router. The lending market receives a receiveLiquidationProceeds callback. If the callback reverts, settlement still completes.

Internal Buyer Settlement

function settleLiquidationWithBuyer(
    uint256 liquidationId, address buyer,
    uint256 tokenAmount, uint256 usdcAmount
) external onlyOperator nonReentrant

Matches liquidation tokens with a buyer who has USDC in custody. Tokens move from the liquidation pool to the buyer’s custody balance (internal ledger operation, no on-chain token transfer). USDC is deducted from the buyer’s internal balance and transferred on-chain to the router. Supports partial fills - the liquidation remains open until the full amount is matched. The lending market is notified via callback.

Emergency Controls

function freezeUser(address user) external onlyOperator
function unfreezeUser(address user) external onlyOperator

Per-user withdrawal freeze at the custody level. Used to prevent front-running during liquidation or for compliance holds. Does not affect the user’s ability to have their balances settled by the operator. Independent of the commodity token’s own freeze mechanism.

function pauseWithdrawals() external onlyAdmin
function unpauseWithdrawals() external onlyAdmin

Global withdrawal circuit breaker. Blocks all withdrawals for all users.

View Functions

Function	Returns
`getBalance(user, token)`	Total balance (locked + available)
`getLockedBalance(user, token)`	Locked balance
`getAvailableBalance(user, token)`	Available balance (total minus locked)
`isSettlementProcessed(settlementId)`	Whether a settlement ID has been used
`isTokenSupported(token)`	Whether a token is registered
`isUserFrozen(user)`	Whether a user’s withdrawals are frozen
`getLiquidation(liquidationId)`	Full liquidation record (token, amount, debtOwed, borrower, lendingMarket, timestamp, settled)

Events

Event	Parameters	When Emitted
`Deposited`	user, token, amount, newBalance	User deposits tokens
`Withdrawn`	user, token, amount	User withdraws tokens
`BalanceLocked`	user, token, amount, lockId	Operator locks balance
`BalanceUnlocked`	user, token, amount, lockId	Operator unlocks balance
`TradeSettled`	settlementId, maker, taker, baseToken, quoteToken, baseAmount, quoteAmount	Trade settlement completes
`BatchSettled`	batchId, settledCount, totalSubmitted	Batch settlement completes
`PrioritySettlement`	settlementId, liquidatedUser, token	Priority liquidation trade settled
`LiquidationReceived`	liquidationId, token, amount, debtOwed, borrower, lendingMarket	Collateral received from router
`LiquidationSettled`	liquidationId, usdcReceived, tokenRecipient	External liquidation sale settled
`LiquidationSoldToBuyer`	liquidationId, buyer, tokenAmount, usdcAmount, fullyFilled	Internal buyer fills liquidation
`OperatorUpdated`	oldOperator, newOperator	Operator address changed
`TokenSupported`	token, supported	Token added or removed
`LiquidationRouterUpdated`	oldRouter, newRouter	Router address changed
`UsdcAddressUpdated`	oldUsdc, newUsdc	USDC address changed
`AdminTransferInitiated`	currentAdmin, pendingAdmin	Admin transfer started
`AdminTransferCompleted`	oldAdmin, newAdmin	Admin transfer accepted
`UserFrozen`	user, operator	User withdrawals frozen
`UserUnfrozen`	user, operator	User withdrawals unfrozen
`WithdrawalsPaused`	operator	Global withdrawal pause
`WithdrawalsUnpaused`	operator	Global withdrawal unpause

Errors

Error	Trigger
`Unauthorized`	Caller lacks required role
`InsufficientBalance`	Available balance less than requested amount
`InsufficientLockedBalance`	Locked balance less than transfer/unlock amount
`ZeroAmount`	Amount parameter is 0
`ZeroAddress`	Address parameter is `address(0)`
`SettlementAlreadyProcessed`	Settlement ID reused
`InvalidSettlement`	Batch array lengths mismatch
`TransferFailed`	ERC-20 transfer returned false
`TokenNotSupported`	Token not registered via `addSupportedToken`
`LiquidationNotFound`	Liquidation ID does not exist
`LiquidationAlreadySettled`	Liquidation already fully settled
`LiquidationAmountExceeded`	Requested token amount exceeds remaining liquidation amount
`BuyerInsufficientUsdc`	Buyer’s USDC custody balance too low
`UserIsFrozen`	Frozen user attempts withdrawal
`WithdrawalsArePaused`	Withdrawal attempted during global pause
`InvalidBatchSize`	Batch settlement called with empty array
`AdminTransferNotPending`	`acceptAdmin` called by non-pending address

Commodity token compliance failures (KYC, whitelist, blacklist, frozen, paused) cause the token’s own transfer or transferFrom call to revert with the commodity token’s error codes, not CommodityCustody errors. Your integration layer must handle both error sources when processing deposits and withdrawals.

ILendingMarket

Callback interface that lending market contracts must implement to receive liquidation settlement notifications.

interface ILendingMarket {
    function receiveLiquidationProceeds(uint256 liquidationId, uint256 amount) external;
}

Called by CommodityCustody when a liquidation is settled (both settleLiquidation and settleLiquidationWithBuyer). If the callback reverts, settlement still completes. Off-chain systems must reconcile via LiquidationSettled or LiquidationSoldToBuyer events.

Overview

Commodity Token License

Stock Token License

Stock Orderbook License

Commodity Orderbook License

Contracts

Architecture

Compliance Model Difference from StockCustody

CommodityCustody

Initialization

State Variables

Access Control

Admin Management

Token Configuration

Deposit and Withdrawal

Balance Locking

Trade Settlement

Liquidation

Receiving Collateral

External Sale Settlement

Internal Buyer Settlement

Emergency Controls

View Functions

Events

Errors

ILendingMarket

​Architecture

​Compliance Model Difference from StockCustody

​CommodityCustody

​Initialization

​State Variables

​Access Control

​Admin Management

​Token Configuration

​Deposit and Withdrawal

​Balance Locking

​Trade Settlement

​Liquidation

​Receiving Collateral

​External Sale Settlement

​Internal Buyer Settlement

​Emergency Controls

​View Functions

​Events

​Errors

​ILendingMarket

Architecture

Compliance Model Difference from StockCustody

CommodityCustody

Initialization

State Variables

Access Control

Admin Management

Token Configuration

Deposit and Withdrawal

Balance Locking

Trade Settlement

Liquidation

Receiving Collateral

External Sale Settlement

Internal Buyer Settlement

Emergency Controls

View Functions

Events

Errors

ILendingMarket