Skip to main content

Integrate the Provenance API

Use the machine API for source requirements, recognition roots, proof delivery, and private confirmation tracking. Use Explorer REST for public display and search. Both require the trust configuration before a result becomes an accepted source claim.

Prepare the connection​

The shell examples require Bash or zsh, curl, and jq. Obtain the service origin and chain ID from your operator's authenticated deployment information. These commands contact that deployment when you run them; no hosted endpoint or chain is assumed. Set PROVENANCE_ORIGIN to its HTTPS origin with no trailing slash, and CHAIN_ID to a canonical positive decimal chain ID.

: "${PROVENANCE_ORIGIN:?Set the authenticated Provenance HTTPS origin}"
: "${CHAIN_ID:?Set the configured decimal chain ID}"
PROVENANCE_RPC="${PROVENANCE_ORIGIN}/v1/chains/${CHAIN_ID}"
curl --fail-with-body --silent --show-error "${PROVENANCE_ORIGIN}/v1"

Discovery returns apiVersion and a chains array containing chainId, protocolVersion, and rpcPath. A configured scope is not a health or approval assertion. This API supports one configured Protocol per chain route; compare each response's scope.protocolAddress with your expected deployment.

Read compatibility, rules, and state​

Each request is one identified JSON-RPC 2.0 object. Parameters are positional: params: [{}] supplies a single empty query object. The following three requests are separate calls, not a batch:

for rpc_method in provenance_getVersion provenance_getRules provenance_getStatus; do
jq -n --arg method "$rpc_method" \
'{jsonrpc:"2.0",id:1,method:$method,params:[{}]}' |
curl --fail-with-body --silent --show-error "$PROVENANCE_RPC" \
-H 'Content-Type: application/json' --data-binary @-
done

getVersion reports apiVersion: "v1", protocolVersion: "1", proof format, and public-input count. Its serviceVersion is a wire-contract label, not a binary release tag. getRules returns the single rule configuration, required sources, and signing history; there is no caller-selected policy parameter. getStatus includes the generation, published checkpoint progress, and worker availability. A root appears only after publication.

With external rules, source declarations include adapter, capability, authentication, coverage, and maximum age. coverage and applicable rejectFlags are JSON-encoded array strings. getStatus.sources records process-local availability observations; another replica may have different observations. Never replace a per-operation funding verdict with a healthy-source indicator.

Query an ordinary Note​

Set NOTE_COMMITMENT to an actual public ordinary Note commitment, a nonzero canonical BN254 field element encoded as 0x and 64 hex digits. Do not use a seed, opening, or any secret that happens to have the same length.

: "${NOTE_COMMITMENT:?Set the public ordinary Note commitment}"
jq -n --arg commitment "$NOTE_COMMITMENT" \
'{jsonrpc:"2.0",id:2,method:"provenance_getNoteRecognition",
params:[{commitment:$commitment}]}' |
curl --fail-with-body --silent --show-error "$PROVENANCE_RPC" \
-H 'Content-Type: application/json' --data-binary @-

An absent record returns found: false with recognitionState: "not_found". A found record can still be pending. A recognized reply includes the Note and its root certificate. Authenticate that certificate and its chain context; recognition alone is not an ownership or spent-status query.

For a known transaction, use provenance_getTransactionRecognition with {txHash, limit} and continue with the returned opaque cursor. For one exact operation, use provenance_getOperationRecognition with blockHash, txHash, and decimal-string operationIndex. All hashes must be complete 32-byte hex values. Pending indexing can return INDEX_PENDING; do not translate it into rejection or an empty history.

Query roots and build local membership​

jq -n '{jsonrpc:"2.0",id:3,method:"provenance_getRoots",
params:[{limit:50}]}' |
curl --fail-with-body --silent --show-error "$PROVENANCE_RPC" \
-H 'Content-Type: application/json' --data-binary @-

getRoots returns certificate items, a publication snapshot, and pagination fields. A machine rootId is generation:sequence, scoped by the chain route and issuer. It is different from an Explorer scoped root ID. Fetch a specific root with provenance_getRoot and {rootId}; its allowedForNewProof also checks the primary-chain anchor. A roots-list flag alone is insufficient for a particular certificate.

Fetch leaves with provenance_getLeaves and {rootId, fromIndex:"0", limit:200}. Continue with returned nextIndex until the selected certificate's leaf count is reached, verifying progress and rebuilding the root locally. Keep every page bound to the same certificate. Alternatively, provenance_getMembership accepts {rootId, commitment}; this reveals interest in that commitment to the service. Local leaf synchronization avoids a per-input query at spending time.

getRoots cursor mode cannot be combined with after, generation, or treeId. Keep filters and snapshot context stable; an empty filtered page can still have a continuation. Generation changes require a refresh. Tree positions in this recognition tree are independent of Protocol Note-tree positions.

Transport and error handling​

ContractIntegration requirement
Request bodyAt most 256 KiB including JSON, hex, and certificates; proof bytes separately at most 64 KiB decoded
EnvelopeExactly jsonrpc, id, method, params; non-null string or integer ID; no batches or notifications
QueryOne method-specific object; no unknown keys, duplicates, generic policy selectors, or URL query strings
IntegersDecimal strings for chain IDs, heights, generations, amounts, indices, and timestamps; limit accepts an integer number or decimal string, 1–200
Browser accessSame-origin or exact operator-configured CORS origin; no wildcard or built-in credential CORS
AuthenticationNo built-in Bearer-auth mechanism; follow the operator's edge-access requirements

Inspect HTTP status first, then the JSON-RPC envelope. curl --fail-with-body detects HTTP errors but does not detect an HTTP-200 JSON-RPC error. A successfully decoded result may itself contain broadcastDecision: "deny" or "unavailable".

For example, the following is an error even though the HTTP status is 200:

{"jsonrpc":"2.0","id":3,"error":{"code":-32025,"message":"Recognition root is unknown","data":{"code":"ROOT_UNKNOWN"}}}

Handle INDEX_PENDING, FINALITY_PENDING, WORKER_UNAVAILABLE, and provider outages with bounded retry and refreshed state. Honor Retry-After and error.data.retryAfter where supplied. Default per-process peer-IP quotas are 120 read requests/minute and 12 proof/evaluation requests/minute; edge policy can be stricter. Scope mismatch, manifest mismatch, invalid proofs, changed generation, and idempotency conflict require correcting context or evidence. Error numbers are service-specific; do not reuse another service's numeric mappings.

Public Explorer data​

Explorer routes under /api/v1 return direct JSON objects, not JSON-RPC envelopes. GET /api/v1/notes/{commitment} displays public Note data; transaction detail is /api/v1/transactions/{txHash}. Collections accept documented scope filters and opaque pagination, with default limit 20 and maximum 200. Global results retain their chain and Protocol provenance.

Search uses only POST /api/v1/search with {query: publicIdentifier}. Do not put a search term in a URL. A public address or hash is searchable; an arbitrary 32-byte secret cannot be distinguished reliably from a public hash. Explorer does not expose private tracking tasks, prove balances, associate a nullifier with a spent Note, or decrypt ordinary private outputs.