A policy holds an account to the controls a fund or desk keeps: a freeze, the pairs it may trade, the most it may hold of an asset, the addresses it may Exit to, a co-signer above a size, and an auditor who reads every entry. The enclave enforces it on every Intent inside the Crossing, and nothing on chain marks which accounts hold one (Policy walks the Account panel).
Set a policy#
import { auditorKeys } from '@privium/sdk'
declare const treasury: string, cosignerKey: string
const auditor = auditorKeys()
await privium.policy.set({
pairs: [{ base: 'So11111111111111111111111111111111111111112', quote: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' }],
limits: [{ asset: 'So11111111111111111111111111111111111111112', max: 500_000_000_000n }],
exitAllowlist: [treasury],
cosign: { key: cosignerKey, aboveUsd: '50000' },
auditor: auditor.publicKey,
loosenAfterSlots: 432_000n,
})
const { policy, pending } = await privium.policy.get()
privium.policy.set signs a policy Intent with the account’s auth key, seals it to the enclave and submits it. Every control is optional and off when left out; a policy with every control off clears it. Assets are named by mint and must be in the market catalogue, or the call throws ASSET_UNSUPPORTED before anything is sent; a mint the Pool has not admitted is refused by intake with ASSET_NOT_ADMITTED. Every policy Intent seals to the same 4,096-byte class as every extended Intent. privium.policy.get reads the policy in force and any pending loosening from the enclave’s status for the account.
| Control | What the enclave does |
|---|---|
frozen |
Refuses every trade and every Exit (policy-frozen). |
pairs |
Refuses a trade on any pair not listed (policy-instrument). At most 8 pairs. |
limits |
Refuses a buy that would take the account’s holding of the base past max, in base units, counting what its open and held buys would add (policy-limit). At most 8 assets. |
exitAllowlist |
Refuses an Exit to any address not on the list (policy-allowlist). The policy keeps only the list’s Merkle root, exitRoot; pass exitRoot instead to set a root built elsewhere. A list holds up to 65,536 addresses. |
screening |
Refuses every Exit except to an address on the allowlist; with no allowlist, every Exit (policy-allowlist). |
cosign |
Holds any order whose notional at its limit is above aboveUsd until the co-signer key signs it (Co-signed orders). |
auditor |
Seals every entry of the account, and every action the policy refuses, to the auditor’s key as well (The auditor’s trail). |
loosenAfterSlots |
The slots any later loosening of this policy waits before it takes effect. |
A refused trade comes back as an order result in state rejected with its reason; a refused Exit as an Exit result in state refused with its reason. Both reasons read the same in the app and in privium.watchEvents.
Tightening and loosening#
A change that holds the account at least as tightly in every control takes effect at once: freeze or screening switched on, the same auditor or one where there was none, the same allowlist or one where there was none, the same co-signer at the same or a lower threshold, a subset of the pairs, a limit kept or lowered for every limited asset, and a delay kept or raised. Any other change is a loosening. It waits loosenAfterSlots of the policy in force, comes back with the policy result in state pending, and shows as pending with its effectiveSlot in policy.get. Until that slot the policy in force keeps applying, so a stolen auth key cannot lift its own limits at once.
PolicyInput#
| Field | Type | Meaning |
|---|---|---|
frozen |
boolean (optional) |
Refuse every trade and every Exit. |
screening |
boolean (optional) |
Refuse every Exit except to an address on the allowlist. |
auditor |
string (optional) |
The auditor's public key from auditorKeys, base58. |
exitRoot |
string (optional) |
An allowlist root built elsewhere, base58; exitAllowlist wins when both are given. |
exitAllowlist |
string[] (optional) |
The addresses an Exit may go to, up to 65,536; the policy keeps only their root. |
cosign |
object (optional) |
The co-signer and the threshold above which orders are held for it. |
cosign.key |
string |
The co-signer's Ed25519 public key, base58. |
cosign.aboveUsd |
string |
The threshold, a decimal USD amount, against an order's notional at its limit. |
loosenAfterSlots |
bigint (optional) |
The slots a later loosening waits; 0 when absent. |
pairs |
object[] (optional) |
The pairs the account may trade, by mint; every pair when absent. At most 8. |
pairs[].base |
string |
The base mint. |
pairs[].quote |
string |
The quote mint. |
limits |
object[] (optional) |
The most the account may hold of an asset, by mint. At most 8. |
limits[].asset |
string |
The mint. |
limits[].max |
bigint | string |
The most, in the asset's base units. |
PolicyResult#
| Field | Type | Meaning |
|---|---|---|
kind |
"policy" |
policy. |
state |
"active", "pending" |
active when the change took effect at once, a tightening; pending when it is a loosening waiting for its slot. |
policy |
PolicyView or null |
The policy in force after the change; null when none is. |
pending |
PendingPolicy or null |
The loosening waiting for its slot; null when none waits. |
PolicyView#
| Field | Type | Meaning |
|---|---|---|
frozen |
boolean |
Every trade and every Exit is refused (policy-frozen). |
screening |
boolean |
Every Exit is refused except to an address on the allowlist (policy-allowlist). |
auditor |
Address or null |
The auditor's X25519 public key, base58, to which every entry and every refused action is also sealed; null for none. |
exitRoot |
Address or null |
The Merkle root of the addresses an Exit may go to; null for no allowlist. |
cosigner |
Address or null |
The Ed25519 key that releases a held order; null for none. |
cosignAboveUsd |
U64 or null |
The notional above which an order is held for the co-signer, in micro-USD at the order's limit; null for none. |
loosenAfterSlots |
U64 |
The slots a loosening of this policy waits before it takes effect. |
pairs |
object[] |
The pairs the account may trade; empty for every pair. |
pairs[].base |
Address |
The base mint. |
pairs[].quote |
Address |
The quote mint. |
limits |
object[] |
The most the account may hold of an asset, counting its open and held buys; empty for none. |
limits[].asset |
Address |
The mint. |
limits[].max |
U64 |
The most, in the asset's base units. |
PendingPolicy#
| Field | Type | Meaning |
|---|---|---|
policy |
PolicyView |
The policy that takes effect at effectiveSlot. |
effectiveSlot |
U64 |
The slot from which it is in force: the slot it was set plus the delay of the policy in force then. |
Policy#
The policy Intent’s payload, as encodePolicy writes it, POLICY_LENGTH (275) bytes: flags u8, auditor32, exitRoot32, cosigner32, cosignAbove u64 and delay u64, then the pair count and eight (base u32, quote u32) slots, then the limit count and eight (asset u32, max u64) slots, unused slots zero.
| Field | Type | Meaning |
|---|---|---|
flags |
number |
POLICY_FLAGS bits. |
auditor |
Uint8Array |
The auditor's key, 32 bytes; zero for none. |
exitRoot |
Uint8Array |
The allowlist root, 32 bytes; zero for none. |
cosigner |
Uint8Array |
The co-signer's key, 32 bytes; zero for none. |
cosignAbove |
bigint |
The co-sign threshold in micro-USD; 0 exactly when there is no co-signer. |
delay |
bigint |
The slots a loosening waits. |
pairs |
([number, number])[] |
The allowed pairs as (base, quote) Registry indexes, at most 8. |
limits |
([number, bigint])[] |
The limits as (asset Registry index, most in base units), at most 8. |
Exits under an allowlist#
declare const allowlist: string[]
await privium.exit({ asset: 'So11111111111111111111111111111111111111112', amount: '2', destination: allowlist[0], allowlist })
An Exit from an account with an allowlist passes the whole list as allowlist. The SDK builds the destination’s Merkle path to the root the policy holds and seals it in the Exit Intent; the enclave checks the path against exitRoot. A leaf is and a node hashes its two children in byte order under privium/exit-allow/node/v1, so a path needs no positions. A refused Exit comes back as an Exit result in state refused with its reason, and nothing of it is scheduled. A destination the list does not hold throws VALIDATION_ERROR before anything is sent. allowlistRoot(addresses) gives the root a list makes, for a policy set with exitRoot.
Co-signed orders#
import { cosign } from '@privium/sdk'
declare const orderId: string
declare const cosigner: { signMessage(message: Uint8Array): Promise<Uint8Array> }
const { programId } = await privium.api.config()
const signature = await cosign({ orderId, programId, signMessage: cosigner.signMessage })
await privium.release({ orderId, signature })
An order whose notional at its limit, valued in USD, is above the policy’s cosignAboveUsd is accepted and reserved but held: its order result reads state held with the reason cosign-required, and it enters no Crossing. The co-signer signs privium/cosign/v1 ‖ program id ‖ order id with the key the policy names; cosign builds that message and returns the signature in base58, from any wallet or key that signs bytes. The owner’s privium.release sends it in a co-sign Intent. The enclave checks the signature against the co-signer in force, that the order is still held and unexpired, and that the account still funds it, then moves the order to waiting for the next Crossing. A held order is cancelled like any other (cancel).
| Parameter | Type | Meaning |
|---|---|---|
orderId |
string |
The held order id, from its order result. |
signature |
string |
The co-signer's signature from cosign, base58. |
| Code | Stage | Message |
|---|---|---|
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. |
The enclave’s refusals of a release come back from intake as ApiClientError, at stage send:
| Code | HTTP | When |
|---|---|---|
ORDER_NOT_CANCELLABLE |
409 | The order id names no order of this account held for a co-signer. |
OUT_OF_SCOPE |
409 | The policy in force names no co-signer. |
SIGNATURE_INVALID |
422 | The signature is not the co-signer’s over this program and order. |
ORDER_EXPIRED |
409 | The held order’s expiry has passed. |
INSUFFICIENT_BALANCE |
422 | The account no longer holds what the order reserves. |
The auditor’s trail#
import { readAuditTrail } from '@privium/sdk'
declare const auditorSecret: string
let cursor: string | undefined
do {
const page = await readAuditTrail({ api: 'https://api.privium.io', auditorSecret, cursor })
for (const e of page.entries) console.log(e.account, e.crossing, e.entry)
cursor = page.hasMore ? page.cursor : undefined
} while (cursor)
auditorKeys() makes an X25519 key pair: the policy names publicKey as its auditor, and the auditor keeps secret. Every Commit’s Ledger diff carries two entry slots for each entry it writes: the owner’s, and a second slot that the enclave seals to the account’s auditor or fills with bytes of the same length when the account has none. Every second slot has the same size, so the count and size of a Commit’s entries mark no account.
readAuditTrail reads the trail from public data alone, with no account key: it pages through GET /v1/ledger/diffs, checks each diff against its Commit’s root on chain, and opens every second slot it can with the auditor’s secret, skipping the slots sealed to other auditors and the filler. Each entry carries the account, the Crossing and the entry: a history entry, as the owner’s history holds it, or a refused action, { kind: 'refused', slot, reply }, carrying the reply the account received. A refused action has no owner entry; its owner slot is filler. fromCrossing and toCrossing bound the range.
AuditEntry#
| Field | Type | Meaning |
|---|---|---|
account |
string |
The audited account's auth key, base58. |
crossing |
string |
The Crossing whose Commit carries the entry. |
index |
number |
The entry's slot in that Commit's diff, always odd. |
entry |
Record<string, unknown> |
A history entry as the owner's history holds it, or a refused action: kind refused, slot and the reply the account received. |