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#
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, , 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#
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#
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 , 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. |