• Reading the docs…
Start trading

Concepts

Intent

An Intent is a sealed order. The browser writes the order’s fields, signs them with the account’s auth key and encrypts the result to the Coprocessor’s attested key, so the order can be read only inside the enclave and never lands as a transaction of the trader’s.

What an Intent holds#

The whitepaper writes an Intent as i=(u,π,s,x,ℓ,τ,ν)i = (u, \pi, s, x, \ell, \tau, \nu). On the wire a trade Intent’s signed body is 73 bytes, little endian:

Field Symbol Bytes Holds
Account uu 32 The account’s auth public key: its stable identifier, never a wallet address. Inside the enclave it maps to a private account index that never moves.
Base, quote π=(a,q)\pi = (a, q) 4 + 4 The pair’s two assets by Registry index. Every token Jupiter routes pairs against SOL and against USDC.
Side ss 1 Buy (+1+1) or sell (−1-1).
Size xx 8 Base units of aa.
Limit ℓ\ell 8 The worst price the trader accepts, as a count of 10eπ10^{e_\pi} quote whole tokens per base whole token. The exponent eπe_\pi is fixed for the pair when it is admitted.
Expiry τ\tau 8 A slot. The Intent takes part only in Crossings whose cutoff is at or before it.
Nonce ν\nu 8 Unique to this Intent across every kind the account sends (Nonces and replay).

The body is followed by the auth key’s 64-byte Ed25519 signature and zero padding to 160 bytes, so every trade Intent is 208 bytes sealed. Every other kind travels in one 4,096-byte plaintext class, so its length never says which kind it is. The byte formats are fixed in the SDK’s WIRE.md and its test vectors.

Signed, then sealed#

Signed by the auth key. The auth key is an Ed25519 key the browser derives from the one wallet signature that opens the account (Your account and keys). It signs the body (an extended Intent’s under the prefix privium/extended-intent/v2), and the signature travels inside the ciphertext. Placing an order needs no wallet prompt, and no signature of the trader’s appears on chain.

Sealed with HPKE. The signed plaintext is encrypted with HPKE (RFC 9180) in base mode, suite DHKEM(X25519, HKDF-SHA256), HKDF-SHA256 and AES-256-GCM, to the enclave’s encryption key. The SDK reads that key from the Registry entry the attestation quote bound it to (Coprocessor). The HPKE info string ties each ciphertext to one deployment and one key epoch:

math
info=privium/intent/v2 ∥ idprog ∥ e ∥ H(quotee)\mathsf{info} = \texttt{privium/intent/v2} \,\|\, \mathsf{id}_{\mathrm{prog}} \,\|\, e \,\|\, \mathsf{H}(\mathsf{quote}_e)

where ee is the key epoch and quotee\mathsf{quote}_e the quote registered for it. A ciphertext made for another program or another epoch does not open. The ciphertext shows no pair, side, size or limit to anyone but the enclave, which rests on the Gap Diffie-Hellman assumption on X25519 and the security of AES-256-GCM (Theorem 3.3).

How it reaches the Coprocessor#

The app and the SDK send the sealed bytes to the API’s intake route, which relays them to the Coprocessor’s intake with nothing else: the request carries the enclave key epoch and the ciphertext, and no account, session or cookie (Intake). The enclave’s answer is sealed back to the account’s reply key and signed by the enclave’s signing key, and it returns as encrypted envelopes in the intake response and on the shared event stream, where only the account’s keys open it.

An Intent can also travel on chain, as the instruction data of a post_intent transaction from any fee payer; the program checks only its length and the indexer hands it to the enclave (Instructions). Both paths deliver the same bytes to the same checks.

What intake checks#

The enclave accepts an Intent only when every check passes, in this order:

  1. It opens under the current epoch’s HPKE key and info string.
  2. It parses, its account exists, and the signature verifies under that account’s auth key.
  3. Its expiry is still ahead, its size is above zero and its pair is admitted.
  4. Its nonce has not been consumed by the account.
  5. It is funded. The account’s unreserved balance must cover the worst case of the order: xx of the base for a sell, x⋅ℓ⋅(1+ϕ)x \cdot \ell \cdot (1+\phi) of the quote for a buy, rounded up to whole quote units, where ϕ\phi is the fee rate. That amount is then reserved.

Acceptance consumes the nonce. The reservation keeps one account’s concurrent Intents from spending the same balance twice; what an Intent leaves unfilled at its expiry is released. An Intent that fails a check is dropped inside the enclave and nothing about it reaches the chain; the reason returns to the account alone, in its encrypted reply (Errors).

Market and limit#

A limit Intent carries the trader’s price. It crosses at the mid when the mid is at or better than its limit, and its remainder joins the Residual only when the limit clears the route’s worst admissible price. What it cannot fill rests across Crossings until its expiry, so one limit Intent can fill in parts over several Crossings.

A market Intent is the same object with a protective limit in place of a chosen one, so its reservation is finite and no fill passes that limit. The SDK sets it from the market’s mid mm and the trader’s maximum slippage ss, 300 bps (3%) unless the trader sets another, from β0=50\beta_0 = 50 bps to 1,000 bps:

math
ℓbuy=⌈m⋅10,000+s10,000⌉,ℓsell=⌊m⋅10,000−s10,000⌋\ell_{\text{buy}} = \left\lceil m \cdot \frac{10{,}000 + s}{10{,}000} \right\rceil, \qquad \ell_{\text{sell}} = \left\lfloor m \cdot \frac{10{,}000 - s}{10{,}000} \right\rfloor

with ss in basis points. Before it builds the Intent, the SDK reads the route bound β=max⁡(β0,Jupiter’s slippage for this size and side)\beta = \max(\beta_0, \text{Jupiter's slippage for this size and side}), which the API quotes for the order’s exact size and side. Without a bound for that size it builds no market Intent, and with β\beta above ss it builds none either, so a route never fills past the slippage the trader set. The Coprocessor routes the Residual within its own bound (Residual). A market Intent is refused while the mid fails any of the checks a pair crosses under (Clearing at the mid); a limit Intent stays accepted and rests until its pair crosses again. Every fill of either kind lands at a price no worse than its Intent’s limit (Crossing). Orders in the app are told in Orders.

Intent kinds#

Trades are one kind of Intent. Every kind is signed by the auth key, sealed to the enclave in the same way and checked by intake, and none lands on chain.

Kind Carries What the enclave does
Trade The fields above. Enters it in the next Crossing’s eligible set.
Cancel The nonce of a resting order of the same account. Burns that order’s nonce, so what remains of it never fills, and consumes its own.
Exit An asset, an amount and a destination: an address or a Ring deposit. Checks the balance and lists the amount in Commits as denominated pieces with a sampled delay (Exit).
Receipt request A span, the claims, a label, the quote asset and the cost basis. Recomputes the claims from the account’s entries, signs a Receipt and returns it in the encrypted reply.
Register The account’s keys in the deposit note’s format: the auth public key, the viewing root, the escape public key, the owner salt and the reply key. Checks that the note names the auth key that signed it, creates the account’s record under a private index, or confirms the keys match the record it holds, and replies that the account is registered.
Status Nothing more. Returns the account’s nonce watermark, its open orders and its pending Exit pieces, to the account alone.

These are the kinds the SDK sends. The Type reference gives every kind the wire defines, with its tag and exact bytes.

Nonces and replay#

A nonce is a 64-bit number: Unix milliseconds shifted left 20 bits, joined with 20 random bits. The SDK raises it to at least one above the last nonce it issued and one above the account’s watermark, so nonces from one account only rise, and two browser tabs draw independent low bits.

The enclave consumes a nonce when it accepts the Intent. It keeps, per account, a spent-through watermark and the set of accepted nonces above it whose orders are still open, so a limit order resting across Crossings stays valid while later Intents advance the watermark. An Intent whose nonce is at or below the watermark, or already in that set, is rejected. A cancel consumes its own fresh nonce and burns its target’s.

Two results follow (Lemma 4.2): every Intent is applied at most once, and no Intent is applied that its trader did not sign. A copy of an Intent replayed later, through intake or post_intent, is rejected, and a ciphertext sealed to an earlier key epoch does not open under the current one, since the info string names the epoch.