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 notapplication/json.VALIDATION_ERROR:sourceorassetis not an address,amountis not a positive 64-bit integer,noteis not base64 or is outside 64 to 16,384 characters,shardis 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 admittedasset.SIMULATION_FAILED: the transaction fails simulation, as it does whensourcecannot fund the amount and the fees;programErrornames the refusing program and its error when the logs do. Retryable.CHAIN_REFUSED, at stagebuild: the transaction does not fit 1,104 bytes, as with a note far longer than a sealed one.PROGRAM_UNAVAILABLE, at stagebuild: the Pool’sLedgerRootaccount is not on chain.RATE_LIMITED: more than 60POSTrequests to/v1in a minute from this client.
The sample seals the note by hand, which is what deposit does in one call.
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,
})
curl -X POST https://api.privium.io/v1/deposits/build \
-H 'Content-Type: application/json' \
-d '{"source":"41VULHU9PnckT2ATUcYjNGkMfAYMbZTqTBE3BGq16vck","asset":"So11111111111111111111111111111111111111112","amount":"25000000","note":"faPh+2R2c/7jksJq5ATO3xEmwMqUlT0vHP43xWtGxSA143Xpm8HxCZ93xjJk8Wj5vNRpiGfa/ll23tYgTO/qQQ/e61X6MWAsYrbDv1jmcgMy8hhrBAZhwQOlBlZwK+RQWunOKDjevl0vuPzU0C5b6ee5t8W00UfvkR6jR9ppVpLjYSRhHa2EvPgPlWuqgOEevcG4jay57QK5KqcTkwECLNxgcsNLrmGHEkNrLJSM1Th2JQRBlnmPs9LxUp2ISHr7JmcmLyJD4f7S7zogdlfrxTw=","shard":1}'
{
"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:signatureis not a base58 signature of 64 bytes.
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)
}
curl https://api.privium.io/v1/deposits/2ATVH8ZXWso1aBWPcK9wDmprTiJvxbGnYuwdgQSsHnHKCDvDck87iouXhQxuHsVXoJqHih44JhDPWmMFAuS5RrTf
The capture is a deposit the Commit of Crossing 5 credited.
{
"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:crossingorindexis not an unsigned integer, orindexis 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.
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)
}
curl https://api.privium.io/v1/exits/17/0
The capture is a released piece of 0.02 SOL, at position 0 of Crossing 17’s exits root, its first listing.
{
"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. |