Hadal
Start trading
  • OverviewStart
  • QuickstartStart
  • What is sealed and what is seenStart
  • Sealed balancesConcepts
  • Sealed ordersConcepts
  • The book and the pool's midConcepts
  • DealsConcepts
  • SoundingsConcepts
Guides

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.

  1. 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.

  2. Unlock

    If the panel's button reads Unlock, press it and sign the message.

  3. 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.

  4. 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.

OutcomeMeaning
ResolvesThe callback landed. It resolves with the callback's transaction signature, and the program's accounts hold the result.
Throws: was refusedThe cluster finished the computation and the program refused its output. The action is void and nothing changed.
Throws: did not finalizeThe 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

  1. 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.

  2. 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.

  3. 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

StateWhat it means and what to do
PendingThe tokens are in the vault and the computation has not finished. Wait: it lands or it expires.
LandedThe amount is in your sealed balance. You can trade it, add it to the pool or withdraw it.
RefundedThe 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.

  1. Switch the panel to Withdraw

    On Portfolio, set Direction to Withdraw. If the panel's button reads Unlock, unlock first.

  2. Choose market, token and amount

    The Amount field shows your Sealed balance of the chosen token, and Max fills it in.

  3. 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

StateWhat it means and what to do
PendingThe computation that checks the balance has not finished. Nothing has moved yet.
PaidThe tokens moved from the vault to your wallet and left your sealed balance.
RefusedThe 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

ErrorRaised when
BusyAnother computation is in flight on the balance. Wait for its callback.
InvalidAmountThe amount is zero.
EmptyBalanceA withdrawal from a balance that has never been written: nothing has landed in it yet.
ComputationStillLivereclaim before the release window has passed.
NothingPendingreclaim 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.

PanelShows
Sealed balancesOne 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 withdrawalsOne 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 / WithdrawThe 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.

Next