• Reading the docs…
Start trading

SDK

Policy and audit

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#

policy.ts
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#

exit.ts
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 H(privium/exit-allow/leaf/v1 ∥ address)\mathsf{H}(\texttt{privium/exit-allow/leaf/v1} \,\|\, \text{address}) 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#

cosign.ts
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#

audit.ts
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.