> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Contracts

> Contract architecture, state management, access control, and function reference for StockCustody.

The Stock Orderbook suite consists of a single deployable contract (`StockCustody`) with external dependencies on `StockToken`, USDC, a `LiquidationRouter`, and optionally a lending market. This page covers the contract's architecture, state layout, and complete function reference.

## Architecture

`StockCustody` 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.

For compliance-checked tokens (security tokens), the contract calls `ISecurityToken.canTransfer` on deposit and withdrawal. Internal transfers during trade settlement skip this check entirely - compliance validation is the matching engine's responsibility.

```
                      +------------------+
                      |   StockCustody   |
                      |  (this contract) |
                      +--------+---------+
                               |
          +--------------------+--------------------+
          |                    |                    |
+---------v--------+  +-------v--------+  +--------v---------+
|   StockToken     |  |     USDC       |  | LiquidationRouter|
| (ISecurityToken) |  |    (IERC20)    |  |   (external)     |
+--------+---------+  +----------------+  +--------+---------+
         |                                         |
+--------v---------+                     +---------v---------+
| IdentityRegistry |                     |   LendingMarket   |
|   (indirect)     |                     | (ILendingMarket)  |
+------------------+                     +-------------------+
```

The IdentityRegistry is never called directly by StockCustody. It is referenced indirectly through StockToken's `canTransfer` validation during deposit and withdrawal of compliance-checked tokens.

## StockCustody

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

### Initialization

```solidity theme={null}
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                |
| `_complianceChecked`      | `mapping(address => bool)`            | Tokens requiring `canTransfer` validation |
| `_frozenUsers`            | `mapping(address => bool)`            | Per-user withdrawal freeze                |
| `liquidations`            | `mapping(uint256 => LiquidationInfo)` | Liquidation records                       |

### Access Control

<Expandable title="Modifier definitions">
  | Modifier                | Allows                             |
  | ----------------------- | ---------------------------------- |
  | `onlyAdmin`             | `admin` only                       |
  | `onlyOperator`          | `settlementOperator` or `admin`    |
  | `onlyLiquidationRouter` | `liquidationRouter` only           |
  | `tokenSupported(token)` | Reverts if token is not registered |
</Expandable>

### Admin Management

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

```solidity theme={null}
function transferAdmin(address newAdmin) external onlyAdmin
function acceptAdmin() external  // only callable by pendingAdmin
```

```solidity theme={null}
function updateOperator(address newOperator) external onlyAdmin
```

### Token Configuration

```solidity theme={null}
function addSupportedToken(address token, bool complianceChecked) external onlyAdmin
function removeSupportedToken(address token) external onlyAdmin
```

The `complianceChecked` flag determines whether the token requires `ISecurityToken.canTransfer` validation on deposit and withdrawal. Set to `true` for security tokens, `false` for USDC and other standard ERC-20s.

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

```solidity theme={null}
function deposit(address token, uint256 amount) external nonReentrant tokenSupported(token)
```

Transfers tokens from the caller into custody. For compliance-checked tokens, validates `canTransfer(caller, custody, amount)` before transfer. The caller must have approved the custody contract for the deposit amount.

```solidity theme={null}
function withdraw(address token, uint256 amount) external nonReentrant
```

Withdraws available (unlocked) tokens from custody. Blocked if the user is frozen or withdrawals are globally paused. For compliance-checked tokens, validates `canTransfer(custody, caller, amount)`. Allows withdrawal of unsupported tokens to prevent fund lockout after token removal.

```solidity theme={null}
function checkTransferability(
    address token, address from, address to, uint256 amount
) public view returns (bool canDo, uint8 code, string memory reason)
```

Pre-checks whether a compliance-checked token transfer would succeed. Returns success for non-compliance-checked tokens. Use this off-chain before deposit or withdrawal to avoid wasted gas.

### Balance Locking

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

```solidity theme={null}
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.

```solidity theme={null}
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

```solidity theme={null}
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. Both parties must have sufficient locked balances. The `settlementId` must be unique - reuse reverts with `SettlementAlreadyProcessed`.

```solidity theme={null}
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.

<Warning>
  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](/licenses/stock-orderbook/integration) for compiler configuration.
</Warning>

```solidity theme={null}
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

```solidity theme={null}
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

```solidity theme={null}
function settleLiquidation(
    uint256 liquidationId, uint256 usdcReceived, address tokenRecipient
) external onlyOperator nonReentrant
```

Settles after the operator sells tokens through an external venue. Stock tokens transfer to `tokenRecipient`. 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 - off-chain systems must reconcile via events.

#### Internal Buyer Settlement

```solidity theme={null}
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. 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

```solidity theme={null}
function freezeUser(address user) external onlyOperator
function unfreezeUser(address user) external onlyOperator
```

Per-user withdrawal freeze. 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.

```solidity theme={null}
function pauseWithdrawals() external onlyAdmin
function unpauseWithdrawals() external onlyAdmin
```

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

### Stock Split Reconciliation

```solidity theme={null}
function reconcileAfterSplit(
    address token, address[] calldata users,
    uint256 numerator, uint256 denominator
) external onlyAdmin
```

Adjusts internal balances after a stock token split. Both total balances and locked balances are multiplied by `numerator / denominator` using floor division. The liquidation pool balance for the token is also adjusted. Dust from rounding stays unallocated in the contract's ERC-20 balance.

Only forward splits are accepted (`numerator` must exceed `denominator`).

### 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                                                                  |
| `isComplianceChecked(token)`          | Whether a token requires compliance validation                                                 |
| `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, complianceChecked                                        | 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          |
| `BalanceReconciled`        | user, token, oldBalance, newBalance                                        | Balance adjusted after stock split |

### 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 or empty                       |
| `TransferFailed`                   | ERC-20 transfer returned false                              |
| `TokenNotSupported`                | Token not registered via `addSupportedToken`                |
| `TransferRestricted(code, reason)` | Security token `canTransfer` rejected                       |
| `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                 |

***

## ILendingMarket

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

```solidity theme={null}
interface ILendingMarket {
    function receiveLiquidationProceeds(uint256 liquidationId, uint256 amount) external;
}
```

Called by `StockCustody` 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.