Deposit and withdraw
How tokens enter and leave a sealed balance, every state a deposit or a withdrawal can land in, and where the app shows each one.
A deposit moves tokens from your wallet into a market's vault and adds the amount to your sealed balance in that market. A withdrawal does the reverse. These two are the public edges of a position: the chain sees each one with its amount, and nothing in between. What a sealed balance is, is told in Sealed balances.
The SDK samples on this page assume a HadalClient named hadal, its connection, the wallet's keypair payer, the market address and the reading key key, set up as in the Quickstart. Amounts are in atoms: see Units.
Unlock
Unlocking derives your reading key from one wallet signature over a fixed message. It is not a transaction: nothing moves and nothing is paid. The key opens your balance in a market, seals your orders and reads everything sealed to you. A wallet has one reading key, the same in the app and in a script.
Press Unlock in the bar, on the order ticket, on the Deposit and Withdraw panel, or in any panel that shows Locked, and sign the message. If you decline, the app shows Still locked and nothing has changed. Lock on Portfolio puts the key away again.
The app asks for Unlock before a deposit as well as before a withdrawal: while the wallet is locked, the panel's button is Unlock.
The derivation and the message are told in The reading key.
The first use of a market
Your sealed balance in a market lives in one account, at the address derived from the market and your wallet. It is created once, before the first deposit, and it records the public half of your reading key: the cluster seals the balance to that key from then on.
Creating it is one transaction that your wallet signs and pays for. The account is 322 bytes, and the wallet pays its rent-exempt minimum in SOL. It queues no computation.
The first Deposit in a market opens the balance for you. The deposit form shows the row First use of this market: Opens your balance when it will, and your wallet asks for two signatures: one opens the balance, one makes the deposit.
Deposit
You deposit either of the market's two tokens, one token per deposit, from your wallet's associated token account for that token.
Open the Deposit panel
Go to Portfolio. The panel at the side opens on Deposit. The Deposit button on an order ticket with an empty balance leads to the same panel with the market chosen.
Unlock
If the panel's button reads Unlock, press it and sign the message.
Choose market, token and amount
Pick the Market, then the Token (the market's base or quote), and enter the Amount. The panel states what will happen: Moves: Wallet to the market's vault and The chain sees: This deposit and its amount.
Press Deposit and sign
The panel follows the deposit through its stages: Sealing in your wallet, Waiting for your signature, The cluster is computing, Done. When it lands, the app confirms Deposit landed and the amount is in your sealed balance.
What awaitComputation tells you
hadal.awaitComputation(computation, timeoutMs) ends in one of three ways, for a deposit, a withdrawal and every other call that queues a computation.
| Outcome | Meaning |
|---|---|
Resolves | The callback landed. It resolves with the callback's transaction signature, and the program's accounts hold the result. |
Throws: was refused | The cluster finished the computation and the program refused its output. The action is void and nothing changed. |
Throws: did not finalize | The computation did not finish within timeoutMs, 120 seconds unless you pass another. It may still land, or it has expired: read the account, and see the refund below. |
The call is described in the SDK reference.
What moves, and when
The transaction
Your signed transaction moves the tokens from your wallet to the market's vault at once, and queues a computation that will add the amount to your sealed balance. The chain shows the deposit, its token and its amount.
The computation
The cluster adds the amount to your balance without opening it. Until its callback arrives the deposit is pending: the tokens are in the vault and not yet in the balance.
The callback
The callback writes your new sealed balance. The deposit has landed. Its receipt holds the amount credited: see Read your receipts.
One computation at a time on a balance
While a deposit or a withdrawal is pending, your balance is held by its computation. Until the callback lands:
- Another deposit, a withdrawal, a collect, a cancel of a resting order, a liquidity change or a deal on the same balance is refused with the program error
Busy. Wait for the callback, then send it. - An order of yours that reaches the head of the market's queue is closed without being computed, so that it does not hold the queue. Nothing moves and it has no receipt: see Orders closed without a computation. Let a transfer land before you place an order.
States of a deposit
| State | What it means and what to do |
|---|---|
Pending | The tokens are in the vault and the computation has not finished. Wait: it lands or it expires. |
Landed | The amount is in your sealed balance. You can trade it, add it to the pool or withdraw it. |
Refunded | The computation expired and the tokens went back to your wallet. Deposit again. |
Refund of an expired deposit
A computation the cluster does not take up within 180 slots expires. The deposit's tokens are then still in the vault and your sealed balance has not changed. The reclaim instruction sends them back: it frees the balance for new computations and pays the waiting amount from the vault to your token account. Why a computation expires is told in Arcium and the trust model.
reclaim can be sent by anyone, for any balance, once the balance's release window has passed. The window is counted from the slot the computation was queued in: its length is in Computation expiry and release. The refund is paid only to a token account owned by the balance's owner, whoever sends it.
The Deposit panel says it before you sign: If the computation expires, the deposit is refunded to your wallet. A deposit that did not land is listed as Refunded under Deposits and withdrawals, and the panel shows the reason under Failed.
Withdraw
A withdrawal asks for an amount of one token back. The computation checks, sealed, that your balance covers it. If it does, the callback pays the tokens from the vault to your wallet in the same transaction. If it does not, the request is refused and nothing moves. The chain sees the request with its amount and whether it was paid, and learns nothing else about the balance.
You can withdraw what is in the sealed balance. Size locked in a resting order, the escrow of an open deal and liquidity shares are not in it until you cancel, collect or remove them.
Switch the panel to Withdraw
On Portfolio, set Direction to Withdraw. If the panel's button reads Unlock, unlock first.
Choose market, token and amount
The Amount field shows your Sealed balance of the chosen token, and Max fills it in.
Press Withdraw and sign
The panel follows the request through Waiting for your signature and The cluster is computing. It ends in Withdrawal paid, with the tokens in your wallet, or in Withdrawal refused: the sealed balance does not cover the amount, and nothing moved.
States of a withdrawal
| State | What it means and what to do |
|---|---|
Pending | The computation that checks the balance has not finished. Nothing has moved yet. |
Paid | The tokens moved from the vault to your wallet and left your sealed balance. |
Refused | The sealed balance does not cover the amount. Nothing moved and the balance is unchanged. Read the balance and ask for an amount it holds. |
A withdrawal whose computation expires has moved nothing. The balance stays held by that computation until reclaim frees it, exactly as for a deposit, and then you ask again.
Program errors on these calls
| Error | Raised when |
|---|---|
Busy | Another computation is in flight on the balance. Wait for its callback. |
InvalidAmount | The amount is zero. |
EmptyBalance | A withdrawal from a balance that has never been written: nothing has landed in it yet. |
ComputationStillLive | reclaim before the release window has passed. |
NothingPending | reclaim on a balance with no computation in flight. |
Every program error with its code is in the program reference.
Where each state shows in the app
Everything on this page is on Portfolio.
| Panel | Shows |
|---|---|
Sealed balances | One row per market you have a balance in: base, quote, liquidity shares and what the shares are worth. Locked, the figures show as sealed and the panel says to unlock. |
Deposits and withdrawals | One row per transfer made from this browser, with its time (UTC), kind, market, amount and status: Pending, Landed or Refunded for a deposit, Pending, Paid or Refused for a withdrawal. |
Deposit / Withdraw | The form, and the stages of the transfer you just sent. |
The same records are served by the HTTP API, the transfers in the clear and the balances as ciphertext: see GET /v1/wallets/:wallet/transfers and GET /v1/wallets/:wallet/balances.