Sealed balances
What a sealed balance holds, how deposits and withdrawals move it, and the rules every action on it follows.
A sealed balance is what you hold in one market. It is an account of the program, at an address derived from the market and your wallet, so there is exactly one per trader per market. Its contents are ciphertext: the cluster computes on them and your reading key reads them. Every trade, liquidity change and deal you make in that market moves this balance and no token account of yours.
What a balance holds
| Field | Unit | Meaning |
|---|---|---|
base | base atoms | The market's base token you can trade, withdraw or supply to the pool. |
quote | quote atoms | The market's quote token, on the same terms. |
shares | pool shares | Your part of the market's pool. Told in Liquidity. |
receipt | seven values | The result of the last action that ran on this balance. Each new action replaces it. |
Amounts are in atoms: see Units. The receipt's fields are in Sealed orders, and shares in Liquidity.
The tokens themselves sit in the market's two vaults, pooled with everyone else's. The balance is your sealed claim on them.
Who can read it
The balance is sealed to one reading key: the key whose public half is given when the balance is opened. Every computation that changes the balance writes it back encrypted to that same key. The account also shows, in the clear, its market, its owner and whether a computation is in flight on it. The reading key tells how the key is derived, and What is sealed and what is seen lists what the chain shows.
import { HadalClient, deriveReadingKey } from '@hadal/sdk'
const hadal = new HadalClient({ connection, owner: wallet.publicKey, clusterOffset })
const key = await deriveReadingKey(wallet.signMessage)
const ledger = await hadal.balance(market, key)
if (ledger) {
const { base, quote, shares, receipt } = ledger
}balance returns null until the first deposit has landed. base, quote and shares are bigint values in atoms.
Before the first deposit
Opening a balance is one transaction (open_balance in the program, openBalance in the SDK). It creates the account, records the reading key's public half and marks the balance as fresh. A fresh balance holds nothing, and its first deposit starts it from zero.
Until that first deposit lands, these actions are refused with EmptyBalance: Withdraw, placing an order, Add liquidity, Remove liquidity, opening a deal and answering a deal.
Deposits
Deposit moves one token, base or quote, in one transaction. The amount is public and must be greater than zero.
The tokens move
The transaction transfers the amount from your token account to the market's vault for that token. From this moment the deposit is
pending.The computation adds them
The same transaction queues a computation that adds the amount to the sealed
baseorquote. Its receipt holds the amount credited.The balance is written
The callback writes the new sealed balance. The deposit has
landed.
The chain shows the wallet, the market, the token and the amount of every deposit. It does not show the balance the deposit was added to.
Withdrawals
Withdraw asks for an amount of one token back. The amount is public and must be greater than zero.
The transaction queues a computation that compares the request with the sealed balance:
paid = base >= requested_base and quote >= requested_quote- Paid. The amount is subtracted from the sealed balance and the callback transfers it from the vault to your token account.
- Refused. The balance does not cover the amount. Nothing is subtracted and no token moves.
The computation reveals that one answer, paid or refused, and nothing else about the balance. The receipt's ok holds the same answer. A withdrawal is all or nothing: it is never paid in part.
Only what is in base and quote can be withdrawn. Amounts locked by a resting order or an open deal, proceeds not yet collected and pool shares are outside them: see What is locked out of the balance.
One computation at a time
One computation runs on a balance at a time. An action that queues a computation on the balance marks it as in flight, and the callback clears the mark. These actions take the balance: Deposit, Withdraw, Add liquidity, Remove liquidity, Collect, Cancel on a resting order, Open deal, Answer, closing a deal, and the processing of one of your orders from the market's queue.
A transaction that reaches a balance while a computation is in flight on it fails with the program error Busy. Nothing in it takes effect, including a deposit's token transfer. Wait for the computation in flight to land, then send the action again:
const action = await hadal.deposit({ market, side: 'quote', amount })
// sign and send action.instructions with the wallet
await hadal.awaitComputation(action.computation!)
// the balance is free: the next action can be sentawaitComputation returns the signature of the callback. It throws when the cluster finished the computation and the program refused its output, in which case nothing changed, and when the computation does not finish within its timeout.
Placing an order queues no computation, so it is accepted while the balance is busy. The balance must be free when the order's turn in the queue comes: an order that reaches the head of the queue while another computation is in flight on its owner's balance is closed and returned unfilled, so that no order holds the queue. See Orders closed without a computation. Let a deposit land before placing the order that spends it.
Actions that also change the market's book (liquidity, Collect, Cancel, closing a deal) take the book in the same way and meet Busy when another computation is in flight on it.
Through the HTTP API a refused transaction has status failed and names the error: see GET /v1/transactions/:signature.
When a computation expires
A computation the cluster does not pick up within 180 slots expires and its action is void: the sealed balance is unchanged. The lifecycle is told in Arcium.
The balance stays marked as in flight until it is released. Once the release window in Limits has passed, anyone can send reclaim for the balance (reclaim in the SDK). It does two things:
- It clears the mark, so the balance accepts actions again. Sent earlier, it fails with
ComputationStillLive. Sent when nothing is in flight, it fails withNothingPending. - If the expired computation was a deposit, it transfers the deposited amount from the vault back to the owner's token account. The deposit is
refunded.
An expired withdrawal moved nothing, so there is nothing to refund: send Withdraw again. A computation that also took the market's book or a deal leaves that account marked too: releaseMarket and releaseDeal in the SDK free them on the same terms.
What is locked out of the balance
Some amounts leave base and quote while they are committed, and come back when the commitment ends.
| Held in | What is held | Returns to the balance |
|---|---|---|
A resting dark order | The quote a bid can still pay, fee included, or the base an ask can still deliver | On Cancel. |
A resting dark order | Proceeds of its crosses | On Collect or Cancel. |
An open deal | The maker's escrow and the deal's proceeds | When the deal is closed. |
The pool | Both tokens behind your shares | On Remove liquidity. |
A swap locks nothing: it settles into the balance inside the one computation that processes it. A pending order locks nothing either, because the balance is checked when the order is processed, not when it is placed. The amounts are in Sealed orders, Deals and Liquidity.