Sai Teller

Sai can refer to the broader system. In this document, Sai means the Sai Wasm contracts on Sai L1, Nibiru.

A Teller Deposit lets Sai recognize funds deposited on a supported source chain and make their equity available for trading before settlement. A Direct Deposit uses Sai USDC the user already holds on Sai L1. Its collateral arrives with the deposit call.

Definitions

The terms below distinguish the source-chain funds, the credit Sai grants before settlement, and the Sai USDC collateral that arrives at settlement. Sai USDC¹ is backed by USDC held in the Base hub, which connects supported source chains to Sai L1, Nibiru.

Read the deposit and allocation examples after these definitions to see how settlement status and equity location change independently. The later implementation sections trace the contract calls and storage.

Term	Definition
Teller Deposit	An individually tracked source-chain deposit accepted through Teller. Sai identifies it by a route ID and source deposit index. It keeps that identity when it settles.
Direct Deposit	A deposit into Sai using Sai USDC already held on Sai L1, Nibiru. The collateral arrives with the deposit call, so Sai immediately increases the user’s backed deposit balance.
Teller Deposit Credit	Sai accepting verified source-deposit evidence and granting tradable, nonwithdrawable equity against that Teller Deposit. The credit call supplies no collateral and does not mint Sai USDC.
Unsettled Teller Deposit	A Teller Deposit for which Sai has granted Teller Deposit Credit but has not yet applied its backing collateral. The source transaction may already be confirmed.
Settled Teller Deposit	The same Teller Deposit after Sai has received and applied its backing collateral. Its equity may remain in an open position.
Settlement	The operation that applies delivered collateral to back an existing Teller Deposit Credit. Settlement requires the original principal. It does not grant a second credit or close positions.
Source-chain USDC	Circle-issued USDC on supported source chains, including Base.
Sai USDC	The ERC20 token on Nibiru representing USDC locked in the Teller system’s Base vault. The FunToken mapping converts between the ERC20 representation and the corresponding bank denomination used by Sai’s Wasm contracts.
Principal	The original amount contributed by a Teller Deposit. Trading does not change the amount settlement must deliver.
Equity	The value attributable to a Teller Deposit as fees, profit, loss, and position changes affect it. Equity can be idle or allocated to positions.
Idle equity	Equity available to fund a position. Unsettled idle equity cannot be withdrawn. After settlement, remaining idle equity joins the user’s backed deposit balance.
Allocation	An accounting link recording how much of a position’s equity is attributable to one Teller Deposit. It records a deposit key and an equity amount. It is not another token or user balance.
Deposit balance	The user’s combined backed, idle funds inside Sai. Open-position equity and unsettled Teller equity are separate.
Deferred effect	A recorded fee or transfer obligation whose application waits for the source Teller Deposit’s backing collateral. Settlement applies the recorded accounting changes and emits the deferred transfer messages.
Attestor	A signer that verifies source evidence and signs a statement Sai can check against the route’s authorized signer set.
Operator	An account authorized to submit Teller Deposit Credit or settlement transactions for a route. The contract owner may also submit them. Operator authority does not replace the attestor signatures required for Teller Deposit Credit.
Route	A source identity comprising a chain ID, Teller contract address, and source USDC address. Route configuration includes attestors, limits, and pause state.

Teller Deposit Credit is separate from Sai’s USDC trading-credit program, a funded-capital feature with its own restrictions. Both use the configured USDC collateral index, but their balances and accounting differ.

Sai USDC backing and Teller settlement

The Teller system holds backing USDC in a vault on Base. The bridge mints Sai USDC on Nibiru against that backing. Users can hold Sai USDC in a wallet, transfer it, or deposit it into Sai. Moving existing Sai USDC into Sai does not create more token supply.

Teller Deposit Credit does not mint Sai USDC. It records tradable equity against verified source evidence. Settlement later delivers and applies the corresponding Sai USDC bank collateral to Sai. Global token backing and settlement of one deposit in Sai are separate accounting concerns.

Trade mode sends funds into Sai. Bridge mode sends Sai USDC to the user’s wallet. A user who later deposits that wallet balance into Sai makes a Direct Deposit, even if they originally obtained the Sai USDC through Teller.

One deposit changes status. Its equity can move.

Alice’s Teller Deposit has an original principal of 300 USDC. She uses 200 of its equity in position X and leaves 100 idle. Settlement supplies the original 300. The 100 joins her backed deposit balance, and the 200 stays in the open position as backed equity.

Property	Question it answers	Values
Settlement status	Has Sai applied this deposit’s backing collateral?	Unsettled or settled
Equity location	How is the user using this equity?	Idle or allocated to positions

These properties are independent. A Teller Deposit keeps its identity through settlement. It does not split into separate settled and unsettled deposits.

This example ignores fees, profit, loss, and other funding sources. Amounts use USDC units. Settlement delivers the corresponding Sai USDC bank collateral.

Alice's Teller Deposit has 300 USDC of principal, with 100 idle and 200 in position X. Settlement backs both portions and leaves position X open.

Once Sai grants Teller Deposit Credit, the unsettled equity can fund trading. Withdrawal of that equity waits until settlement has applied its backing collateral.

An allocation connects a position to a Teller Deposit

A position can use equity from several Teller Deposits. Sai keeps a separate allocation for each source deposit to follow fees, collateral releases, and settlement for its share.

Here, deposit A contributes 300 and deposit B contributes 100 to a position with 400 USDC of equity. B also has 100 left idle. When only A settles, the position contains 300 backed equity and 100 unsettled equity. B’s idle 100 remains unsettled.

Both Teller Deposits are unsettled when the position is funded. Only A subsequently settles. The position remains open. This example ignores fees and profit or loss.

The allocation can remain after settlement as the position’s funding attribution. Fees and position changes can adjust its equity amount. Backed idle funds aggregate in the user’s deposit balance, so Sai does not retain a separate idle balance for every settled Teller Deposit.

Trading against unsettled equity can incur a fee or require a vault transfer before backing arrives. A deferred effect records that obligation. Settlement applies the recorded fee changes and emits the deferred transfer messages.

Teller Deposit Credit and settlement use separate calls

Attestors sign source evidence. An authorized operator submits it to request Teller Deposit Credit. Later, delivered collateral backs the same deposit. The user can trade between these calls.

Teller Deposit Credit accepts signed evidence without attached bank coins. Settlement supplies and applies collateral to the same deposit. Opening a position is a separate trading action.

CreditTellerDeposit
  → contract::execute
  → exec_credit_deposit

FundTradeMint + bank coins
  → contract::execute
  → exec_fund_trade_mint
  → settle_confirmed_range

SettleTellerBatch + bank coins
  → contract::execute
  → exec_settle_batch
  → settle_confirmed_range

Message FundTradeMint requires the configured bridge. Message SettleTellerBatch requires a route operator or the owner and can fund a contiguous deposit range. Both require the full original principal. Settlement follows the credit indices within each route.

The word Mint in the bridge message name does not mean that the Sai Wasm contract mints Sai USDC or opens a position. Its handler accounts for the incoming bank collateral.

How Sai routes incoming bridge funds

The mint-funding handler checks the CCTP deposit lookup first. This prevents incoming collateral from bypassing an existing Teller Deposit Credit.

CCTP lookup	Source-chain route	Result
Known deposit	Must match that deposit’s route	Validate its identity and settle it. Failed checks reject the call.
No known deposit	Route exists	Reject with `TellerDepositNotCredited`. Retry after Teller Deposit Credit is recorded.
No known deposit	No route	Apply immediate backed deposit accounting for the supplied user.

A known CCTP ID stays on the settlement path even if its route was removed. Route validation then fails. It cannot fall back to granting another backed balance.

The last branch uses the same internal deposit function as a Direct Deposit. It describes a bridge-funded code path, while Direct Deposit in this guide names the user flow that starts with Sai USDC already held on Sai L1.

Deposit identity and user balance use different keys

A route identifies a source chain, Teller contract, and source USDC contract. Each credited Teller Deposit has an index within that route. User equity totals combine deposits across eligible routes.

Identifier	Meaning
Route ID	Hash of the source chain ID, Teller address, and source USDC address.
Teller Deposit key	Pair of `route_id` and `deposit_idx`. Deposit indices start at 1 within each route.
Source deposit ID	Binds the route, deposit index, source sender, and original amount.
CCTP deposit ID	Links arriving bridge funds to an existing Teller Deposit Credit. It is part of the signed evidence.
User queue sequence	Orders the user’s credited deposits across routes. Starts at 0, independently of source deposit indices.

User balances use user-only keys. Deposit structs retain their collateral field, and settlement still validates the collateral and exact attached funds.

Map USER_TELLER_STATE stores one TellerUserState per user. Its fields unsettled_idle and unsettled_in_trades track the two equity locations. Fields next_deposit_sequence and deposit_cursor track queue progress. Queue entries stay in the separate map USER_TELLER_DEPOSIT_QUEUE, so Sai can read and remove them individually without rewriting the whole queue. Checked accounting helpers update the latest user state within each operation.

Function teller_usdc_collateral loads configuration item TRADING_CREDIT_COLLATERAL_IDX, also used by the USDC trading-credit program. Teller balances therefore need only a user key. The queue uses a user and sequence key. This is a configured collateral index, not a universal numeric constant across chains. Other-collateral trading and queries cannot spend or expose this Teller equity.

The namespaces use the literal prefix teller/, including teller/route_cfgs and teller/deposits. Migration 11 renames legacy namespaces, removes redundant collateral indices from user keys, and combines the four legacy user scalars into TellerUserState.

The retained Rust type name TellerTradeLotAllocation uses Lot for a Teller Deposit. This guide calls the accounting link an allocation.

Sources and boundaries

Sai Keeper Teller architecture explains the Base vault, Sai USDC, Trade and Bridge modes, and the bridge components.
Sai Teller contract code defines the accounting and storage names used here.

The configured bridge also has authority to call message DebitDepositToBridge, which debits a specified user’s backed idle balance and sends it to the bridge. The bridge must enforce user authorization for that withdrawal flow.

Sai USDC is also sometimes called Nibiru USDC. ↩