• Reading the docs…
Start trading

Concepts

Receipt

A Receipt is a statement of one account’s trading results over a span of Crossings, computed and signed inside the Coprocessor’s enclave under a pseudonym that names no wallet. Anyone checks it against public chain data, at /r or with receipts.verify.

What a Receipt carries#

Field What it is
Pseudonym ψ\psi F(vku,"receipt-id" ∥ label)\mathsf{F}(vk_u, \texttt{"receipt-id"} \,\Vert\, \mathit{label}), from the account’s viewing root and the label. One label gives one pseudonym, so Receipts under it build one track record; a fresh label gives a Receipt that stands alone.
Label The name the trader publishes under, up to 512 bytes.
Span [k0,k1][k_0, k_1] The first and last Crossing the claims cover, both included.
Ledger root ρ(k1)\rho^{(k_1)} The root the Commit of Crossing k1k_1 accepted.
Claims Σ\Sigma The results stated, each kind at most once (next section).
Quote asset qq The admitted asset every value is counted in.
Cost basis Average cost or first in, first out (FIFO).
Holder key pkψ\mathit{pk}_\psi The Ed25519 public key of the seed F(vku,"receipt-key" ∥ label)\mathsf{F}(vk_u, \texttt{"receipt-key"} \,\Vert\, \mathit{label}). Its holder shows the Receipt is theirs to present.
Enclave key pkCpk_C The key that signed.
Attestation reference The address of the EnclaveKey account that registers pkCpk_C in the Registry.
Signed slot sRs_R The slot at which the enclave signed.
Version and program Version 1 and the Pool’s program id.

The signature σC\sigma_C is Ed25519 under pkCpk_C over the prefix privium/receipt/v1 and the Borsh-encoded body. A Commit signs under a different prefix, so neither signature passes as the other. A Receipt link carries the body and signature in base64url after /r# (ReceiptBody).

Claims#

Claim Unit Forms
Realized PnL atoms of qq, signed exact, or at least θ\theta
Return on capital basis points, signed exact, or at least θ\theta
Volume atoms of qq exact, or at least θ\theta
Fill count fills exact, or at least θ\theta
Fees paid atoms of qq exact
Ending equity atoms of qq exact, or at least θ\theta
Assets traded mints the count, with or without the list of mints

The request names each claim and its form. An exact claim names no value: the enclave computes the figure and writes it into the Receipt it signs. An at-least claim carries the trader’s threshold θ\theta; the enclave signs it only when its figure is at or above θ\theta, and the Receipt carries θ\theta, never the figure. An assets claim states the assets traded in the span: their count, and the mints when it lists them. A threshold that does not hold refuses the Receipt, with that claim named in the refusal.

How results are computed#

The rules are fixed in the measured enclave code. For every committed Crossing the enclave keeps an accounting frame in its private checkpoint, which is encrypted under the Ledger data key, bound to the last committed root and kept off the public diff (Ledger). A frame holds the mids posted for that Crossing, its deposit credits, each fill’s base and quote amounts and fee, and the Exits its Commit lists. A Receipt replays the account’s frames from Crossing 1 through k1k_1, so positions and cost basis always run from the account’s first deposit. Realized PnL, volume, fees, the fill count and the assets traded count only Crossings k0k_0 through k1k_1.

Positions and the value of a fill#

The quote asset qq is held as cash. Every other asset the account holds is a position with a cost basis in qq: one running total under average cost, a queue of lots under FIFO.

A fill’s crossed and routed parts are one fill. Its base size xx is the crossed plus the routed base, and its quote amount yy the crossed quote, at the mid, plus the routed quote, at the Residual’s executed price. Its value in qq is

math
V={ywhen the pair’s quote asset is qxwhen the pair’s base asset is qy mquote→qotherwiseV = \begin{cases} y & \text{when the pair's quote asset is } q \\ x & \text{when the pair's base asset is } q \\ y \, m_{\mathrm{quote} \to q} & \text{otherwise} \end{cases}

with mm the mark at that Crossing. Each fill gives one asset and gets the other. Giving an asset other than qq takes the quantity given out of its position at its cost basis BB and realizes V−BV - B. Getting an asset other than qq adds the quantity got at cost VV. A fill in a pair where neither side is qq therefore realizes PnL on the asset it spends.

The cost basis of a quantity xgx_g taken out of a position of QQ units:

  • Average cost. B=C xg/QB = C\,x_g / Q for the position’s total cost CC; the rest keeps its average. Within one Crossing, the fills that acquire a pair’s traded asset (its base, or its quote asset when the base is qq) apply before the fills that dispose of it, then by order id, so a Crossing’s buys enter the average before its sells draw on it.
  • FIFO. The quantity leaves the oldest lots first, each at its own cost in proportion to the units taken. A Crossing’s fills apply in the order the engine executed them.

Fees#

A fill’s fee ff is paid in the pair’s quote asset (Fees). Its value F=f mquote→qF = f\, m_{\mathrm{quote} \to q} comes off realized PnL and adds to fees paid. When the pair’s quote asset is not qq, the fee’s units leave that position at their cost basis and realize nothing.

Deposits, Exits and the mark#

  • A deposit applies at the start of the Crossing that credits it, before that Crossing’s fills. An asset other than qq enters its position at its value at that Crossing’s mark, so PnL counts from the moment the asset entered.
  • An Exit applies after the fills of the Crossing whose Commit lists it in its exits root (Exit). The quantity leaves its position at cost basis and realizes nothing.
  • The mark ma→qm_{a \to q} at a Crossing comes from the mids posted for it: the a/qa/q mid, the inverse of the q/aq/a mid, or, through USDC, the ratio of the two assets’ USDC marks. A value the frame holds no mark for refuses the Receipt.
  • Equity at any point is the qq balance plus every other balance at the Crossing’s mark. Ending equity is the equity after Crossing k1k_1‘s Exits.

Volume, fill count and assets#

Volume is ∑V\sum V over the span’s fills, crossed and routed alike. The fill count is the number of fills, and a fill with both a crossed and a routed part counts once. Assets traded are the mints of each fill’s base asset, or of its quote asset when the base is qq, listed in byte order.

Return on capital#

The return is time-weighted. Capital opens at the account’s equity at the start of Crossing k0k_0. Each deposit in the span closes a sub-span just before it is credited, each Exit just after its Crossing’s fills, and the end of Crossing k1k_1 closes the last. With Eqj−\mathrm{Eq}^{-}_{j} the equity that closes sub-span jj and Eqj−1+\mathrm{Eq}^{+}_{j-1} the equity it opened with, just after the previous flow,

math
1+rTW=∏j=1MEqj−Eqj−1+1 + r_{\mathrm{TW}} = \prod_{j=1}^{M} \frac{\mathrm{Eq}^{-}_{j}}{\mathrm{Eq}^{+}_{j-1}}

A sub-span that opens at zero equity contributes a factor of 1, so an account that starts empty takes its first deposit as its capital. A flow changes only the equity the next sub-span opens with, which cancels within that sub-span’s factor, so the return holds whatever the size of the deposits and Exits.

Rounding#

Every intermediate value is an exact ratio of integers. Only the final figures are cut, toward zero: realized PnL, volume, fees and equity to whole atoms of qq, the return to whole basis points.

Making a Receipt#

The trader sends a receipt Intent carrying the request (span, claims, label, quote mint and cost basis), signed by the account’s auth key and sealed to the enclave’s key like any Intent, so it takes no wallet prompt. The enclave signs once it has checked that:

  1. the request is well formed: k0≤k1k_0 \le k_1, a label of at most 512 bytes and each claim kind at most once;
  2. the account’s frames, replayed through the current Crossing, reproduce its committed balances, so the history holds every entry;
  3. it holds the anchor for k1k_1, the root and slot of the Commit that accepted that Crossing, and its signing slot is no earlier than that Commit;
  4. the quote mint is an admitted asset and every mark the replay needs is in its frame;
  5. every at-least claim’s figure reaches its threshold.

It writes each exact claim’s figure into the Receipt and returns the Receipt in its sealed reply. A refused request comes back as an intake error with no Receipt (POST /v1/intake). No transaction is sent, and nothing about the request reaches the chain.

Verifying at /r#

receipts.verify in the SDK runs four checks with public data and no account of its own, and /r runs the same function in the reader’s browser:

  1. Decode. The bytes parse as a version 1 Receipt whose paired claims each set exactly one form. Otherwise it is malformed.
  2. Enclave key. The enclave record the attestation reference names holds pkCpk_C, and sRs_R falls in its validity interval: at or after its first slot and, when the record has an end, before it. Otherwise the key is unknown.
  3. Signature. σC\sigma_C verifies under pkCpk_C over the prefix and the body. Otherwise the signature is invalid.
  4. Root. The root record for ρ(k1)\rho^{(k_1)} names Crossing k1k_1 and the Receipt’s program, and its Commit landed no later than sRs_R. Otherwise the root is not on chain.

With the SDK’s default public data (ReceiptPublicData), both records come from Roots and enclave keys and are pinned to Solana before they count, through the API’s RPC relay. The EnclaveKey account at the address derived from pkCpk_C must be owned by the program, registered, and agree on the signing key, HPKE key, measurement, key epoch and validity interval. The root’s Commit transaction must have succeeded at its recorded slot with a commit instruction for k1k_1 directly after an Ed25519 verification of a valid signature over the Commit message naming the program, k1k_1, ρ(k1)\rho^{(k_1)} and the diff digest.

To show a Receipt is theirs to present, the holder signs a verifier’s fresh nonce with the holder seed, and the verifier checks it under pkψ\mathit{pk}_\psi (Presenting a Receipt).

A Receipt that passes states true claims about the entries committed under ρ(k1)\rho^{(k_1)} for the account behind ψ\psi. That rests on what every Commit rests on: Ed25519, the integrity of the enclave whose measurement the Registry records (Attestation and reproducible builds), and the program’s checks on every accepted root. Receipts under different labels carry unrelated pseudonyms and holder keys, since the viewing root stays with the trader and the enclave, so they link to each other only through what their claims say.