• Reading the docs…
Start trading

SDK

deposit

privium.deposit moves tokens from the wallet into a Pool vault shard, with a sealed note that names the account to the enclave alone. The Commit after the deposit lands credits the balance. It is the one transaction of the account’s that carries its wallet.

deposit.ts
const { items } = await privium.api.markets({ q: 'SOL', quote: 'USDC' })
const usdc = items[0].quote

const deposit = await privium.deposit({ asset: usdc.mint, amount: '250' })
if (deposit.signature) {
  const status = await privium.api.depositStatus(deposit.signature)
  console.log(status.state, status.crossing)
}

Parameters#

Parameter Type Meaning
asset string The mint to deposit, base58.
amount string A decimal amount in whole tokens, such as 25.5, with at most the asset's decimals.

What it does#

  1. Reads GET /v1/config for the active enclave key (The enclave key).
  2. Finds asset among the base and quote assets of the markets GET /v1/markets returns on its first page, for its decimals, and converts amount to base units.
  3. Draws a vault shard uniformly from the Pool’s vaultShards.
  4. Seals a deposit note to the enclave’s key under the privium/deposit-note/v1 info: the account’s auth public key, viewing root, escape public key, owner salt and reply key (The deposit queue).
  5. Has the API build the transaction with POST /v1/deposits/build: the wallet’s public key as source, the amount, the note and the shard.
  6. Hands the bytes to the wallet.
The wallet has state transaction signature
signAndSendTransaction sent the built bytes the sent transaction’s signature
signTransaction only built the signed bytes absent
neither built the unsigned bytes absent

Returns#

Field Type Meaning
state 'built' | 'sent' sent when the wallet sent the transaction; built when the caller sends transaction.
transaction Uint8Array The transaction's bytes: signed when the wallet signed them, unsigned when it has no transaction signing.
signature string (optional) The transaction signature, base58, when the wallet sent it.
shard number The vault shard the deposit pays into, drawn uniformly.
fixture boolean Whether the API built the bytes in fixture mode; those bytes never reach the wallet.

Send a built transaction through any RPC endpoint, the API’s relay included. Then follow its signature with privium.api.depositStatus(signature) (GET /v1/deposits/{signature}) through sent, landed and credited at Crossing k. From that Crossing on, readBalances returns the credited balance.

A deposit whose note the enclave cannot read as a valid note for its account (one that does not open under the enclave’s key, does not decode, or disagrees with the account’s registration) is never credited and never stops its Crossing: that Crossing’s Commit lists the amount as an Exit to the owner of the source token account, due at once, and once release_exit pays it the status reads refunded, with the payment in refundTransaction (The deposit queue). A deposit still uncredited when the Escape opens reads refunded too, once refund_deposit returns it.

Errors#

Code Stage Message
VALIDATION_ERROR validation Enter a nonnegative decimal amount.
VALIDATION_ERROR validation Amount has more precision than this asset.
PROGRAM_UNAVAILABLE read The enclave quote has not been indexed yet. Retry when its attestation is available.
CONFIGURATION_REQUIRED read The API changed its Pool program. Reconnect explicitly.
ASSET_UNSUPPORTED validation The asset is not routed.
  • The API’s refusals of the build, such as ESCAPE_ACTIVE or ASSET_NOT_ADMITTED, throw ApiClientError (POST /v1/deposits/build lists them).
  • The contract client checks the request body before sending it, so an amount of zero throws zod’s ZodError and no request is made.
  • An amount above 264−12^{64} - 1 base units throws a plain Error, Integer exceeds u64.
  • Whatever the wallet throws, a declined signature included, reaches the caller unchanged.