• Reading the docs…
Start trading

API reference

Deposits and Exits

Build a deposit transaction for a wallet to sign and follow it to the Commit that credits it, then follow each committed Exit piece to its release.

Routes#

POST /v1/deposits/build#

Builds the deposit transaction: the source wallet’s tokens into one vault shard, with the sealed deposit note in its data. deposit calls it, and so does the Account page’s Deposit form through it. The note is the only part that names the account, and only the enclave opens it (The deposit queue).

The body is DepositBuildRequest. Returns TransactionBuild, an unsigned v0 transaction the API has already simulated. The build reads the asset’s state and the Ledger straight from the chain. Its compute budget instructions come first; for SOL it then creates the wallet’s wrapped SOL account when needed and wraps amount into it, and the deposit instruction comes last.

Sign transaction with the source wallet and send it before lastValidBlockHeight, through the RPC relay or the wallet, then follow its signature with GET /v1/deposits/{signature}.

Three bounds apply to the note, each where it is checked. The API takes note as base64 of 64 to 16,384 characters and answers VALIDATION_ERROR outside them. The built transaction must fit one packet with 128 bytes left for wallet guards, 1,104 bytes, or the build answers CHAIN_REFUSED. On chain, the program’s deposit instruction takes a note of 48 to 1,024 bytes and refuses any other with NoteTooLong, whoever built the transaction. A note from sealDepositNote is 209 bytes, 280 characters, inside all three.

Errors

  • UNSUPPORTED_MEDIA_TYPE: the body is not application/json.
  • VALIDATION_ERROR: source or asset is not an address, amount is not a positive 64-bit integer, note is not base64 or is outside 64 to 16,384 characters, shard is neither 0 nor 1, or the body carries another key.
  • ESCAPE_ACTIVE: the Escape is active, and deposits are closed.
  • ASSET_NOT_ADMITTED: the Pool has not admitted asset.
  • SIMULATION_FAILED: the transaction fails simulation, as it does when source cannot fund the amount and the fees; programError names the refusing program and its error when the logs do. Retryable.
  • CHAIN_REFUSED, at stage build: the transaction does not fit 1,104 bytes, as with a note far longer than a sealed one.
  • PROGRAM_UNAVAILABLE, at stage build: the Pool’s LedgerRoot account is not on chain.
  • RATE_LIMITED: more than 60 POST requests to /v1 in a minute from this client.

The sample seals the note by hand, which is what deposit does in one call.

TypeScript
import { addressBytes, b64, sealDepositNote, unb64 } from '@privium/sdk'

const config = await api.config()
const enclave = config.activeEnclave
const keys = privium.keys
const { items } = await api.markets({ q: 'SOL', quote: 'USDC' })

const note = await sealDepositNote(
  { authPublicKey: keys.authPublicKey, viewRoot: keys.viewSeed, escapePublicKey: keys.escapePublicKey, ownerSalt: keys.salt, replyPublicKey: keys.notePublicKey },
  { programId: addressBytes(config.programId), epoch: BigInt(enclave.keyEpoch), quoteHash: unb64(enclave.quoteHash), hpkePublicKey: unb64(enclave.hpkeKey) },
)

const build = await api.buildDeposit({
  source: wallet.publicKey,
  asset: items[0].base.mint,
  amount: '25000000',
  note: b64(note),
  shard: crypto.getRandomValues(new Uint32Array(1))[0] % config.params.vaultShards,
})
Response
{
  "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQAJDSyzQNnSgcA0B2Q8mvkerFvp9iyVVHDSkqmu9LZXnMQVL+lNhn+wNuna4zBlrUonU8za3Z5jEptw+CXd4J9bdhGfeEZhKijPuT5athoaw+6Zj3xJiG0cCieFtbtMdSuYreHfh4Dc0ujIP8cmKajyxN1xlQXr5Nha8dmv/hBB63qSAwZGb+UhFzL/7K26csOb57yM5bvF9xJrLEObOkAAAACMlyWPTiSJ8bs9ECkUjg2DC1oTmdr/EIQEjnvY2+n4WQabiFf+q4GE+2h/Y0YYwDXaxDncGus7VZig8AAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAG3fbh12Whk9nL4UbO63msHLSF7V9bN5E6jPWFfv8AqZiwEQ612l2vEwI2+1WqedBdAjf7na6rmQ7zXTAG+1AjP8sjlP2zWHQ8LW8D7uX/xu8I3Y6GSBixiuDOKlliIm/FlWnmEY4AXBDXp1ViWvqG0j1+xIb2FUUaECTgH8dddZBhbh9UOO1hfDAgF5itVQjVsf0gH46FrWDbk9108MqFt1wuaMD99hQo0GXF882miKCfcVjbWEWiPl31N/HqFwUGBAAFAmPEAAAEAAkDAAAAAAAAAAAFBgABAAYHCAEBBwIAAQwCAAAAQHh9AQAAAAAIAQEBEQkKAAoLAgYBAwgMCeYB8iPGiVLh8rYBQHh9AQAAAADRAAAAfaPh+2R2c/7jksJq5ATO3xEmwMqUlT0vHP43xWtGxSA143Xpm8HxCZ93xjJk8Wj5vNRpiGfa/ll23tYgTO/qQQ/e61X6MWAsYrbDv1jmcgMy8hhrBAZhwQOlBlZwK+RQWunOKDjevl0vuPzU0C5b6ee5t8W00UfvkR6jR9ppVpLjYSRhHa2EvPgPlWuqgOEevcG4jay57QK5KqcTkwECLNxgcsNLrmGHEkNrLJSM1Th2JQRBlnmPs9LxUp2ISHr7JmcmLyJD4f7S7zogdlfrxTwA",
  "lastValidBlockHeight": "1510",
  "fixture": false
}

GET /v1/deposits/{signature}#

A deposit’s public progress by its transaction signature: sent, landed in its shard’s deposit queue, credited at a Crossing, or refunded to its source. A deposit whose note does not open is returned by a committed refund Exit to the source token account’s owner and reads refunded once that Exit is released; during an Escape, refund_deposit returns a deposit no Commit credited. The Deposit form polls it after the wallet sends, and stops at credited or refunded. A signature the indexer has not recorded is looked up on chain at each call: one the chain holds without error answers landed, and one it has not seen answers sent.

Parameter Type In Meaning
signature Signature path The deposit transaction's signature.

Returns DepositStatus.

Errors

  • VALIDATION_ERROR: signature is not a base58 signature of 64 bytes.
TypeScript
const { items } = await api.markets({ q: 'SOL', quote: 'USDC' })
const sent = await privium.deposit({ asset: items[0].base.mint, amount: '0.025' })
if (sent.signature) {
  const status = await api.depositStatus(sent.signature)
}

The capture is a deposit the Commit of Crossing 5 credited.

Response
{
  "signature": "2ATVH8ZXWso1aBWPcK9wDmprTiJvxbGnYuwdgQSsHnHKCDvDck87iouXhQxuHsVXoJqHih44JhDPWmMFAuS5RrTf",
  "state": "credited",
  "slot": "470448227",
  "crossing": "5",
  "refundTransaction": null
}

GET /v1/exits/{crossing}/{index}#

One committed Exit piece’s public release progress, by the Crossing whose exits root lists it and its position there. An account learns its pieces’ coordinates only from its own sealed status and Exit replies; watchExits then reads each piece here and checks that mint, recipient and amount equal the signed piece (Exit). The record names no account.

A piece enters an exits root only at the Crossing whose opening slot has reached the piece’s sampled release slot; until then its amount stays reserved in the account, and the account’s own status shows it scheduled. The route serves the piece once that Commit is verified and the piece’s Merkle path checks out against its exits root, so every piece it serves is already releasable: release_exit pays it, and state turns released with the transaction.

A piece still unpaid is listed again in the exits root of the Crossing 60 after its last listing, before the earlier root leaves the 64 that LedgerRoot keeps (From request to release). Each listing is served at its own coordinates and carries the piece’s first ones as originCrossing and originIndex, which name the piece and its one payment: once paid, every listing reads released with the same transaction. The account’s status names the latest listing.

Parameter Type In Meaning
crossing U64 path The Crossing whose exits root lists the piece.
index U64 path The piece's position in that exits root, 0 to 4,294,967,295.

Returns PublicExit.

Errors

  • VALIDATION_ERROR: crossing or index is not an unsigned integer, or index is above 4,294,967,295.
  • NOT_FOUND: no committed piece sits at these coordinates, or the Commit that lists it is not yet verified.
  • INDEXER_UNAVAILABLE: the indexer has not verified the latest Commit yet, or its root disagrees with the chain; retryable.
  • PROGRAM_UNAVAILABLE: the Pool is not indexed yet; retryable.
TypeScript
import type { AccountStatus } from '@privium/sdk/contract'

// A pending piece from the account's opened status reply.
declare const piece: AccountStatus['pendingExits'][number]

if (piece.crossing !== null && piece.index !== null) {
  const release = await api.exit(piece.crossing, piece.index)
  if (release.state === 'released') console.log(release.transaction)
}

The capture is a released piece of 0.02 SOL, at position 0 of Crossing 17’s exits root, its first listing.

Response
{
  "originCrossing": "17",
  "originIndex": 0,
  "crossing": "17",
  "index": 0,
  "mint": "So11111111111111111111111111111111111111112",
  "recipient": "73gTMxBikWDzt1zXTHUxkg6UHExC87UXRWtUEAKSkn4o",
  "amount": "20000000",
  "releaseSlot": "470448466",
  "state": "released",
  "transaction": "65Uk9mvwVgwiAsNusc44oK7cx9CDQSoBiU1fh8PK1in9p1v9qfo9o2hTn1oMsK2iacuWc5j4mMLaWNcNZEh4X6U"
}

Types#

DepositBuildRequest#

Field Type Meaning
source Address The wallet that signs and pays; the tokens leave its token account.
asset Address The mint to deposit. It must be admitted.
amount PositiveU64 The amount in the asset's base units.
note string The deposit note sealed to the enclave's key, base64, 64 to 16,384 characters. It names the account to credit, and only the enclave opens it.
shard integer The vault shard to deposit into, drawn uniformly at random.

TransactionBuild#

Field Type Meaning
transaction Base64 The unsigned transaction, base64.
lastValidBlockHeight U64 The last block height its blockhash is valid at. Build again after it.
fixture boolean true when the bytes come from fixtures: they are no Solana transaction and no wallet signs them.

DepositStatus#

Field Type Meaning
signature Signature The deposit transaction's signature.
state "sent", "landed", "credited", "refunded" sent until the chain holds it without error, landed once it does (in its shard's deposit queue), credited once a Commit credits it, refunded once it is paid back: by its committed refund Exit when its note does not open, or during an Escape.
slot U64 or null The slot the chain holds it at; null while the chain has not seen it.
crossing U64 or null The Crossing that credited it; null until credited.
refundTransaction Signature or null The transaction that paid the refund back; null unless refunded.

PublicExit#

Field Type Meaning
originCrossing U64 The Crossing whose exits root first listed the piece: the first to open at or after its release slot. Every later listing keeps it.
originIndex integer The piece's position in that first exits root. With originCrossing, it names the piece and its one payment across listings.
crossing U64 The Crossing whose exits root holds this listing of the piece: originCrossing, or a later Crossing that listed the unpaid piece again.
index integer The piece's position in that exits root.
mint Address The asset's mint.
recipient Address The destination the piece pays.
amount PositiveU64 The piece's amount in base units: the asset's denominationUnit times a power of two.
releaseSlot U64 The slot its sampled delay ends at, no later than the slot of the Commit that first lists it.
state "committed", "released" committed once a Commit lists it, releasable from then on; released once release_exit has paid it, on every listing.
transaction Signature or null The release_exit transaction's signature, the same on every listing; null until released.