• Reading the docs…
Start trading

SDK

receipt

privium.receipt asks the enclave for a Receipt: a signed statement of the account’s results over a span of Crossings, under a pseudonym that names no wallet. The request names each claim and its form, and the enclave computes every figure itself. It is an Intent signed by the auth key, so it takes no wallet prompt, and nothing about it reaches the chain. Anyone verifies the Receipt with receipts.verify.

receipt.ts
import type { ReceiptRequest } from '@privium/sdk'

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

const request: ReceiptRequest = {
  from: 1000n,
  to: 2000n,
  label: 'weekly',
  quoteMint: items[0].quote.mint,
  costBasis: 'fifo',
  claims: [
    { kind: 'realizedPnl', mode: 'atLeast', threshold: 10_000n * 10n ** 6n },
    { kind: 'fills', mode: 'exact' },
    { kind: 'fees', mode: 'exact' },
  ],
}
const { receipt, link } = await privium.receipt(request)

Parameters#

Parameter Type Meaning
request ReceiptRequest The span, claims, label and quote asset.

ReceiptRequest#

Field Type Meaning
from bigint The first Crossing of the span.
to bigint The last Crossing of the span, at or after from.
claims ReceiptRequestClaim [] The claims to state, each kind at most once.
label string The label to publish under; it fixes the pseudonym and the holder key.
quoteMint string The quote asset the claims are measured in, base58.
costBasis 'average' | 'fifo' (optional) average, the default, or fifo.

costBasis sets how a sell’s cost is measured: average cost, the default, or first in, first out with fifo. The Receipt records it.

ReceiptRequestClaim#

A request claim names what to state and in which form, never a figure. In exact mode the enclave computes the figure and writes it into the Receipt it signs. In atLeast mode it signs only when its figure reaches threshold, and the Receipt carries the threshold, never the figure. Fees are always exact, and an assets claim states the count of assets traded, with their mints when includeMints is true (Claims). The rules each figure is computed by, under either cost basis, are in How results are computed.

Exact, for realized PnL, return on capital, volume, fill count or ending equity:

Field Type Meaning
kind 'realizedPnl' | 'return' | 'volume' | 'fills' | 'equity' The claim: realized PnL, return on capital, volume, fill count or ending equity.
mode 'exact' exact: the enclave computes the figure, and the Receipt states it.

At least a threshold, for the same five:

Field Type Meaning
kind 'realizedPnl' | 'return' | 'volume' | 'fills' | 'equity' The claim: realized PnL, return on capital, volume, fill count or ending equity.
mode 'atLeast' atLeast: the Receipt states only that the figure reaches threshold.
threshold bigint The value the figure must reach, in its claim's unit: base units of quoteMint for realizedPnl (signed 128-bit), volume and equity (128-bit), basis points for return (signed 64-bit), a count for fills (32-bit).

Fees paid:

Field Type Meaning
kind 'fees' Fees paid.
mode 'exact' exact: fees paid are always stated as the enclave's figure.

Assets traded:

Field Type Meaning
kind 'assets' The assets traded.
mode 'exact' exact: the enclave takes the assets from the account's fills in the span.
includeMints boolean true states the mints traded and their count; false states the count alone.

What it does#

  1. Registers the account with the enclave before the instance’s first Intent (The one signature).
  2. Encodes the request: span, claims, label, quote mint and cost basis, each claim as its kind’s tag and its form (ExtendedIntent).
  3. Reads GET /v1/config for the active enclave key, then carries the encoded request as the payload of a receipt Intent with a fresh nonce, signs it under privium/extended-intent/v2, pads it to 4,096 bytes and seals it to that key.
  4. Submits it with POST /v1/intake. The enclave replays the account’s history, checks the span’s ending root, computes each claim’s figure, checks every threshold against its figure, and signs the Receipt with the exact figures written in.
  5. Takes the signed Receipt from the reply, decodes it and builds its link: the connected origin, /r and the Receipt’s bytes in base64url in the fragment.

Returns#

Field Type Meaning
submission Submission The receipt Intent's submission.
receipt Receipt (optional) The signed Receipt, when the enclave's reply carried one.
link string (optional) The /r link, with the Receipt in its fragment.

receipt and link are absent when the reply holds no Receipt, as when intake was unreachable and the submission is unsent. Retry it and read the Receipt from its results:

receipt-retry.ts
import { decodeReceipt, receiptLink, unb64, type ReceiptRequest } from '@privium/sdk'

declare const request: ReceiptRequest

let { submission, receipt } = await privium.receipt(request)
if (!receipt && submission.state === 'unsent') {
  await submission.retry()
  const reply = submission.results.find((result) => result.kind === 'receipt')
  if (reply?.kind === 'receipt') receipt = decodeReceipt(unb64(reply.bytes))
}
if (receipt) console.log(receiptLink(receipt, 'https://privium.io'))

Receipt#

Field Type Meaning
body ReceiptBody The signed body.
signature Uint8Array The enclave's Ed25519 signature over privium/receipt/v1 and the encoded body, 64 bytes.

ReceiptBody#

Field Type Meaning
version 1 The body format: 1.
programId string The program, base58.
pseudonym Uint8Array HMAC of the viewing root over receipt-id and the label, 32 bytes: one label, one pseudonym.
from bigint The first Crossing of the span.
to bigint The last Crossing of the span, whose Commit accepted root.
root Uint8Array The Ledger root committed at Crossing to, 32 bytes.
claims ReceiptClaim [] The claims stated.
holderKey Uint8Array The holder's Ed25519 public key, derived from the viewing root and the label.
enclaveKey Uint8Array The enclave's signing key, 32 bytes.
attestationRef string The address of the signing key's EnclaveKey account, base58: the program address of enclave and the key.
signedSlot bigint The slot the enclave signed at.
label string The label chosen at request, UTF-8; a Receipt decodes with a label of at most 512 bytes.
quoteMint string The quote asset the claims are measured in, base58.
costBasis 'average' | 'fifo' average or fifo: how a sell's cost is measured.

ReceiptClaim#

A claim as the signed Receipt states it, in the order the request named them. An exact request claim comes back with exact set to the enclave’s figure and atLeast null; an atLeast one with atLeast set to its threshold and exact null.

Realized PnL:

Field Type Meaning
kind 'realizedPnl' The claim.
exact bigint | null The enclave's figure for realized PnL over the span, in base units of quoteMint, signed 128-bit; null for an at-least claim.
atLeast bigint | null The request's threshold, which the figure reaches, in the unit of exact; null for an exact claim.

Return on capital:

Field Type Meaning
kind 'return' The claim.
exact bigint | null The enclave's figure for time-weighted return on capital over the span, in basis points, signed 64-bit; null for an at-least claim.
atLeast bigint | null The request's threshold, which the figure reaches, in the unit of exact; null for an exact claim.

Volume:

Field Type Meaning
kind 'volume' The claim.
exact bigint | null The enclave's figure for traded notional, in base units of quoteMint; null for an at-least claim.
atLeast bigint | null The request's threshold, which the figure reaches, in the unit of exact; null for an exact claim.

Fill count:

Field Type Meaning
kind 'fills' The claim.
exact bigint | null The enclave's count of fills, 32-bit; null for an at-least claim.
atLeast bigint | null The request's threshold, which the figure reaches, in the unit of exact; null for an exact claim.

Fees paid:

Field Type Meaning
kind 'fees' The claim.
exact bigint The enclave's figure for fees paid, in base units of quoteMint. A fees claim is always exact.

Ending equity:

Field Type Meaning
kind 'equity' The claim.
exact bigint | null The enclave's figure for ending equity, in base units of quoteMint; null for an at-least claim.
atLeast bigint | null The request's threshold, which the figure reaches, in the unit of exact; null for an exact claim.

Assets traded:

Field Type Meaning
kind 'assets' The claim.
mints string[] | null The mints traded, base58, in byte order; null when the request set includeMints to false.
count number The number of assets traded.

Errors#

Code Stage Message
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.
DECRYPTION_FAILED read This envelope cannot be opened by this account.
INTAKE_UNAVAILABLE send The account registration is sealed and the intake is unreachable.
  • The request’s encoding (step 2) throws a plain Error before the receipt Intent is sealed: Invalid Receipt span or claims when from is after to, a kind appears twice or the request holds more than 100 claims; Integer exceeds u32 or Integer exceeds u128 for a fill count, volume or equity threshold outside its width, and Signed integer overflow for a realized PnL or return threshold outside its own; Expected 32 bytes or a base58 error for a mint that is not an address. A label long enough to carry the request past the Intent’s 4,096 bytes throws Extended intent too large while it is signed (step 3). An instance that had not registered has sent its register Intent by then (step 1).
  • Intake’s errors other than INTAKE_UNAVAILABLE throw ApiClientError (POST /v1/intake). An at-least claim whose figure falls short of its threshold is refused with RECEIPT_CLAIM_FALSE, HTTP 422, its fieldErrors.claims naming the claim’s kind. A request the enclave cannot compute, such as one ending at a Crossing not yet committed, one in a quote mint the Pool does not carry, one with no mark for its quote mint, or one with a label over 512 bytes, is refused with VALIDATION_ERROR. Neither leaves anything to retry (Refusals).