receipts.verify checks a Receipt from public records alone, with no account and no wallet: the enclave key’s registration and the Commit of the span’s last Crossing, each pinned to its account or transaction on chain. It runs the checks the /r page runs and returns the outcome as a state, never as an error.
const result = await privium.receipts.verify(location.hash)
if (result.state === 'verified') console.log(result.receipt.body.label)
else console.log(result.state, result.reason)
Two forms#
receipts.verify(value, data), exported from@privium/sdkasreceiptsand asverifyReceipt, reads the two records from thedatait is given.privium.receipts.verify(value)on a connected instance reads them frompublicDatawhenconnectwas given one, and otherwise fromreceiptPublicDataover the instance’s client.
Parameters#
| Parameter | Type | Meaning |
|---|---|---|
value |
Receipt | Uint8Array | string |
The Receipt: decoded, as its bytes, or as a /r link's fragment. |
data |
ReceiptPublicData |
Where the enclave key's registration and the root are read. |
The checks#
In this order; the first that fails sets the state (Verifying at /r):
| State | When | Reason |
|---|---|---|
malformed |
The value does not decode as a Receipt, or does not encode back to the same bytes. | The Receipt bytes are malformed. |
unknown-enclave-key |
getEnclave(attestationRef) gives no record, a record of another signing key, or one whose validity interval does not contain signedSlot. |
The signing key was not admitted at the signed slot. |
signature-invalid |
The signature does not verify under enclaveKey over privium/receipt/v1 and the body, by strict Ed25519. |
The enclave signature is invalid. |
root-not-on-chain |
getRoot(root) gives no record, or one whose Crossing is not to, whose program is not the Receipt's, or whose slot is after signedSlot. |
The ending root is not accepted at this Crossing. |
verified |
Every check above passed. |
Returns#
ReceiptVerification#
When every check passes:
| Field | Type | Meaning |
|---|---|---|
state |
'verified' |
verified: every check passed. |
receipt |
Receipt |
The decoded Receipt. |
Otherwise:
| Field | Type | Meaning |
|---|---|---|
state |
'unknown-enclave-key' | 'signature-invalid' | 'root-not-on-chain' | 'malformed' |
The check that failed: malformed, unknown-enclave-key, signature-invalid or root-not-on-chain. |
reason |
string |
A sentence naming the failed check. |
verifyReceipt throws only what the data lookups throw. A Receipt that is not well formed, signed by an unadmitted key or anchored to an unaccepted root comes back as its state.
Public records#
receiptPublicData(api, options) gives the two lookups over an API, each taking the API’s record only once the chain confirms it through the API’s RPC relay. An instance uses it unless connect was given publicData, and a reader with no account passes it to receipts.verify:
import { receiptPublicData, receipts } from '@privium/sdk'
const data = await receiptPublicData('https://api.privium.io')
const result = await receipts.verify(location.hash, data)
| Parameter | Type | Meaning |
|---|---|---|
api |
PriviumApi | string |
A contract client, or the API's base URL. |
options |
{ programId: string; fixture?: boolean } (optional) |
The program id the records must name, and fixture; read from GET /v1/config when absent. |
| Lookup | Reads | Then checks |
|---|---|---|
getEnclave(attestationRef) |
GET /v1/enclaves/{key} with the Receipt’s attestationRef |
The record against its EnclaveKey account, with verifyEnclaveRegistration. |
getRoot(root) |
GET /v1/roots/{root} |
That the record names the configured program and the same root, then the record against its Commit transaction, with verifyChainRoot. |
A lookup gives null, which receipts.verify reads as its failing state, when the API answers UNKNOWN_ENCLAVE_KEY for an enclave or ROOT_NOT_ON_CHAIN or NOT_FOUND for a root, or when its chain check fails. Any other failure throws.
ReceiptPublicData#
| Field | Type | Meaning |
|---|---|---|
getEnclave |
(attestationRef: string) => Promise<{ signingKey: string; validFromSlot: string; validUntilSlot: string | null } | null> |
Looks up the registration of the enclave key a Receipt names; null when there is none. |
getRoot |
(root: Uint8Array) => Promise<{ crossing: string; slot: string; programId: string } | null> |
Looks up a committed root by its 32 bytes; null when no Commit accepted it. |
An independent verifier implements it over its own reading of the chain.
verifyEnclaveRegistration#
Checks an Enclave record against the chain. It reads the EnclaveKey account at the program address of enclave and the record’s signing key with getAccountInfo at confirmed, and requires an account the program owns, of at least 297 bytes, with the EnclaveKey discriminator, in stage 2 (admitted), whose signing key, HPKE key, measurement, epoch, valid_from and valid_until equal the record’s, a validUntilSlot of null matching a valid_until of (EnclaveKey). Anything else throws a plain Error, UNKNOWN_ENCLAVE_KEY.
| Parameter | Type | Meaning |
|---|---|---|
api |
PriviumApi |
The contract client whose RPC relay is read. |
programId |
string |
The program that must own the EnclaveKey account. |
enclave |
Awaited<ReturnType< PriviumApi ['enclave']>> |
The Enclave record of GET /v1/enclaves/{key}. |
fixture |
boolean (optional) |
true returns at once, for an API in fixture mode; false when absent. |
verifyActiveEnclave#
Checks that an enclave key may take new secrets now. It reads the Registry account at the program address of registry with getAccountInfo at confirmed, and requires an account the program owns, of exactly 920 bytes, with the Registry discriminator and a key_count of at most 4. Among the filled key slots, the one whose signing_key is the record’s must be admitted, with the record’s epoch and hpke_key, and the slot the answer was read at must fall from its valid_from up to, not including, its valid_until (RegisteredKey). Anything else throws a plain Error, UNKNOWN_ENCLAVE_KEY. An instance runs it before sealing an Intent or a deposit note to the active key (The enclave key); a reply or a Receipt signed under a key needs only verifyEnclaveRegistration.
| Parameter | Type | Meaning |
|---|---|---|
api |
PriviumApi |
The contract client whose RPC relay is read. |
programId |
string |
The program that must own the Registry account. |
enclave |
Awaited<ReturnType< PriviumApi ['enclave']>> |
The Enclave record of the key, as GET /v1/config serves it in activeEnclave. |
fixture |
boolean (optional) |
true returns at once, for an API in fixture mode; false when absent. |
verifyChainRoot#
Checks a Root record against the chain. It reads commitTransaction with getTransaction at confirmed and requires a transaction that succeeded at the record’s slot, under that signature, holding the program’s commit instruction for the record’s Crossing right after an Ed25519 signature-verify instruction whose message, under privium/commit/v1 and the program id, names the same Crossing, root and diff hash with a valid signature. Anything else throws a plain Error, ROOT_NOT_ON_CHAIN. readBundle pins every diff’s root with it, each record once per client.
| Parameter | Type | Meaning |
|---|---|---|
api |
PriviumApi |
The contract client whose RPC relay is read. |
anchor |
Awaited<ReturnType< PriviumApi ['root']>> |
The Root record of GET /v1/roots/{root}. |
fixture |
boolean (optional) |
true returns at once, for an API in fixture mode; false when absent. |
readLedgerRoot#
Reads the root the program holds now. It reads the LedgerRoot account at the program address of ledger with getAccountInfo at confirmed, and requires an account the program owns, of at least 128 bytes, with the LedgerRoot discriminator. It returns the last committed Crossing at byte 8, the slot of its Commit at 16, whether escape_from_slot at 24 is set, and the root at 32. Anything else throws a plain Error, ROOT_NOT_ON_CHAIN. readBalances checks every balance snapshot against it.
import { readLedgerRoot } from '@privium/sdk'
const { root, crossing, escape } = await readLedgerRoot(privium.api, privium.config.programId)
console.log(escape ? 'Frozen at' : 'Committed', root, 'at Crossing', crossing)
| Parameter | Type | Meaning |
|---|---|---|
api |
PriviumApi |
A contract client; the account is read through its RPC relay. |
programId |
string |
The Pool program, which must own the account. |
| Field | Type | Meaning |
|---|---|---|
root |
string |
The committed Ledger root, base64. |
crossing |
string |
The Crossing whose Commit wrote it. |
slot |
string |
The slot of that Commit. |
escape |
boolean |
true once trigger_escape has run: the root is the frozen one. |
The relay’s own refusals throw ApiClientError from each of these checks.
receiptLink#
receiptLink(receipt, origin) is the Receipt’s link: origin, without a trailing slash, then /r# and the Receipt’s bytes in base64url. receipt returns it already built.
| Parameter | Type | Meaning |
|---|---|---|
receipt |
Receipt |
The Receipt. |
origin |
string |
The site origin, such as https://privium.io; a trailing slash is dropped. |
Presenting a Receipt#
The holder key in a Receipt lets its holder show the Receipt is theirs to present. The holder signs a verifier’s fresh nonce with the seed the label gives under the viewing root, and the verifier checks it against holderKey:
import { receiptHolderSeed, sign, utf8, verifySignature, type Receipt } from '@privium/sdk'
declare const receipt: Receipt
const nonce = utf8(crypto.randomUUID())
const answer = sign(nonce, receiptHolderSeed(privium.keys.viewSeed, receipt.body.label))
const presented = verifySignature(answer, nonce, receipt.body.holderKey)