• Reading the docs…
Start trading

API reference

Roots and enclave keys

The two public records a Receipt is verified against: the Commit that stored a Ledger root, and the registration of the enclave key that signed. History and bundle readers check every diff’s root the same way.

Routes#

GET /v1/roots/{root}#

The Commit that stored a Ledger root. receipts.verify and the /r page check a Receipt’s ending root with it, and readBundle and readHistory check the root of every diff they scan (Ledger leaves and proofs).

A root is base64, so percent-encode it in the path: / as %2F, + as %2B and = as %3D. The client does this for you.

Parameter Type In Meaning
root Hash path The root in base64, percent-encoded in the path.

Returns Root.

A Receipt’s root checks out when the answer names the Receipt’s program and its ending Crossing, at a slot no later than the Receipt’s signed slot (Verifying at /r). The SDK then pins the answer to the chain itself: it reads commitTransaction through the RPC relay and checks the signed Commit it holds (Ledger leaves and proofs).

Errors

  • VALIDATION_ERROR: root is not base64 of 32 bytes.
  • ROOT_NOT_ON_CHAIN: no verified Commit stored this root. receipts.verify reads it as the state root-not-on-chain.
  • INDEXER_UNAVAILABLE: the indexer has not verified the latest Commit yet, or its root disagrees with the chain; retryable.
  • PROGRAM_UNAVAILABLE: the Pool is not indexed yet; retryable.
TypeScript
const crossing = await api.crossing('14')
const anchor = await api.root(crossing.root)
Response
{
  "root": "Jk27Uw3/D3fmCcqAmsv641H46pMqG2FGpeOSnsNYfBQ=",
  "crossing": "14",
  "slot": "470448430",
  "programId": "BH2ggvL6MxJ96zQhiuCdJDym84kN4RPpkf4bVJgZAVYe",
  "commitTransaction": "Zo8U9uFSRuPqv2RhKyacVXNchQSCxFBD6cw1AFu3gY96JXRxLz8arCCJXdBXo3ax2vqhVJJjwZGvvkk5yRSYvd8",
  "diffHash": "KJYqSOs5qDeLVjOQ8R+zhibckhSNRP5iovZ0U48vjYU="
}

GET /v1/enclaves/{key}#

An enclave key’s registration, current or past, by its signing key or by the address of its EnclaveKey account, the program address of enclave and the signing key. A Receipt’s attestationRef is that account address, and receipts.verify reads the registration by it, then checks that the key signed the Receipt and was admitted at its signed slot: validFromSlot at or before it, validUntilSlot null or after it. It also reads the EnclaveKey account through the RPC relay, which must be admitted and hold this answer’s signing key, HPKE key, measurement, epoch and slots (verifyEnclaveRegistration).

Parameter Type In Meaning
key Address path An enclave signing key, or the address of its EnclaveKey account.

Returns Enclave. For several registrations of one signing key, the answer is the one of the highest epoch.

Errors

  • VALIDATION_ERROR: key is not a base58 address of 32 bytes.
  • UNKNOWN_ENCLAVE_KEY: the Registry holds no registration of this signing key, or of the key whose EnclaveKey account sits at this address. receipts.verify reads it as the state unknown-enclave-key.
TypeScript
const config = await api.config()
const registration = await api.enclave(config.activeEnclave.signingKey)
Response
{
  "signingKey": "5FYR7WaPVYwsmUCQxmJoLrwG14cwLCsxsQvSt2FMDJhL",
  "hpkeKey": "/kV4H3CpJDM4boEAapb7E3r17uE5y63yd+pNtrcPxkY=",
  "keyEpoch": "2180",
  "measurement": "ZgsEmPKnF/77hCijP1VK9Ndu92n3honQagGmISlBu6c=",
  "platform": "mainnet-beta",
  "quoteHash": "/ltey38J838VqZUrrqaRSJibMbOQ6avYOQ4OLIKl97k=",
  "verifiedAtSlot": "470880162",
  "validFromSlot": "470880000",
  "validUntilSlot": "471096000"
}

Types#

Root#

Field Type Meaning
root Hash The root.
crossing U64 The Crossing whose Commit stored it.
slot U64 That Commit's slot.
programId Address The program that stored it.
commitTransaction Signature The Commit transaction's signature.
diffHash Hash The data-availability accumulator the Commit sealed; a diff's chunks must fold to it.