• Reading the docs…
Start trading

SDK

Mirrors

A leader puts a Receipt label on the board with a fee; a follower follows its pseudonym ψ with an allocation and caps. When the leader’s order enters a Crossing, the enclave places each follower’s mirror order in the same Crossing, at the leader’s pair, side and limit, and each mirror fill pays the leader its fee inside the Ledger. Neither side learns the other’s account, and the board shows only the label, its fee and the Receipts its leader publishes (The board).

Lead a label#

lead.ts
const psi = privium.labelPseudonym('alpha')
const label = await privium.lead({ label: 'alpha', feeBps: 50 })
console.log(label.psi === psi, label.feeBps)

privium.lead signs a lead Intent with the account’s auth key, carrying the label (at most 512 bytes) and the fee in basis points (at most 100), seals it to the enclave and submits it. The enclave makes the label’s pseudonym, ψ=HMAC(viewing root,receipt-id ∥ label)\psi = \mathrm{HMAC}(\text{viewing root}, \texttt{receipt-id} \,\|\, \text{label}), the same pseudonym the label’s Receipts carry (Receipt), followable at that fee, and answers with a statement it signs. lead posts the statement to POST /v1/labels/{psi} and returns the label as the board now holds it. Leading the same label again sets a new fee. privium.labelPseudonym(label) gives ψ in the caller’s process, from the viewing root, with no request.

Parameter Type Meaning
label string The Receipt label to put on the board, at most 512 bytes.
feeBps number The leader fee each mirror fill pays, 0 to 100 bps.
Code Stage Message
OUT_OF_SCOPE validation A trade key cannot {action}. It trades, cancels and reads balances and fills.
INTAKE_UNAVAILABLE send The lead is sealed and the intake is unreachable.
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.

LeadResult#

The reply the enclave signs, which lead posts for you.

Field Type Meaning
kind "lead" lead.
psi Address The label's pseudonym ψ.
label string The label.
feeBps integer The leader fee in basis points, at most 100.
statement string The JSON statement the enclave signed: program, psi, label, feeBps and slot.
signature Base64 The enclave's Ed25519 signature over privium/lead/v1 ‖ statement, base64.

Publish Receipts#

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

declare const request: ReceiptRequest
const { receipt } = await privium.receipt({ ...request, label: 'alpha' })
if (receipt) await privium.publishReceipt(receipt)

A Receipt made under the label carries its ψ (receipt). privium.publishReceipt posts it to POST /v1/labels/{psi}/receipts, which checks that an admitted enclave signed it and stores it under the label. Followers read the board’s Receipts and verify each one in their own browser.

Parameter Type Meaning
receipt Receipt A signed Receipt made under a label on the board.
Code Stage Message
OUT_OF_SCOPE validation A trade key cannot {action}. It trades, cancels and reads balances and fills.

Follow a label#

follow.ts
const { items } = await privium.api.labels()
await privium.follow({ psi: items[0].psi, allocationBps: 1000, maxPerTradeUsd: '250', stopAtUsd: '2000' })
const follows = await privium.follows()

privium.follow signs a follow Intent with the account’s auth key, carrying ψ, the allocation in basis points of the account’s equity (1 to 10,000), the most one mirror may spend in USD and, optionally, the equity in USD below which following stops. The enclave refuses a label that is not on the board, the account’s own label, and a fifth follow (OUT_OF_SCOPE). The follow keeps the fee the label had when it was set, or a lower one the leader sets later: a leader can lower its fee for followers, never raise it. privium.unfollow(psi) ends it; privium.follows() lists the account’s follows from the enclave.

Parameter Type Meaning
psi string The label's pseudonym ψ, base58.
allocationBps number The share of the account's equity that mirrors, 1 to 10,000 bps.
maxPerTradeUsd string The most one mirror may spend, a decimal USD amount.
stopAtUsd string (optional) The equity in USD below which following stops; no floor when absent.
Code Stage Message
VALIDATION_ERROR validation Enter a nonnegative decimal amount.
VALIDATION_ERROR validation Amount has more precision than this asset.
OUT_OF_SCOPE validation A trade key cannot {action}. It trades, cancels and reads balances and fills.
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.

When a Crossing begins, each new order of the leader gets a mirror order for each follower, at the leader’s pair, side, limit and expiry, with equity valued in USD at the Crossing’s mids:

Size of the mirror
A buy the leader’s size × the follower’s equity × the allocation ÷ the leader’s equity
A sell the follower’s holding of the base × the share of the leader’s holding the leader sells
Every mirror at most maxPerTradeUsd at the leader’s limit; together, at most half the pair’s venue cap where it has one, scaled down alike

A mirror below the base’s denomination unit, or one the follower cannot fund, is not placed. A follower whose equity is below stopAtUsd stops following and is told with a follow result in state stopped. Mirror orders carry nonces at or above 2632^{63}, so they never take one of the follower’s own, and fill by the same rules as every order in the Crossing: a leader and its followers on one side get the same crossed fraction and the same routed price.

Each mirror fill pays the leader its fee on the fill’s quote notional, in the quote asset, beside the protocol fee, credited to the leader’s account in the same Commit. The follower’s order result carries mirrorOf, the label, and leaderFee; its fill entry carries mirrorOf, and its one fee entry holds both fees, described protocol and leader fee. The leader’s history holds one leader-fee entry per asset per Crossing. A Receipt states the leader’s side with the followerFeesReceived and followerNotional claims, and a follower’s leader fees count in its fees claim (ReceiptClaim).

Every mirror call is the owner’s: a trade-key instance throws OUT_OF_SCOPE (Privium inside a terminal or bot).

FollowState#

Field Type Meaning
kind "follow" follow.
state "active", "stopped" active while mirroring; stopped once unfollowed or once the account's equity fell below its floor.
psi Address The label's pseudonym ψ.
label string or null The label's name; null on the answer to an unfollow.
allocationBps integer or null The share of the account's equity that mirrors the leader, in basis points.
maxPerTradeUsd U64 or null The most one mirror may spend, in micro-USD.
stopAtUsd U64 or null The equity floor below which following stops, in micro-USD; null or 0 for none.
feeBps integer or null The leader fee this follow pays, in basis points: the fee when it was set, or a lower one the leader set since.

Follow#

The follow Intent’s payload, as encodeFollow writes it: psi32, allocationBps u16, maxPerTrade u64 and stopAt u64, in micro-USD with 0 for no floor.

Field Type Meaning
psi Uint8Array The label's pseudonym, 32 bytes.
allocationBps number The share of equity that mirrors, 1 to 10,000 bps.
maxPerTrade bigint The most one mirror may spend, in micro-USD.
stopAt bigint The equity floor in micro-USD; 0 for none.