Skip to main content

Provenance: recognition and trust

Provenance lets a wallet, DApp, or service check whether ordinary Notes belong to a configured issuer's recognized source set. It screens actual public funding, verifies client-generated source proofs, and publishes signed checkpoints of an off-chain recognition tree. A valid source proof establishes membership under that issuer's rules, scoped to a chain and Core instance. It does not establish ownership, identity, legal compliance, risk-free funds, or a guarantee that a recipient can spend.

Use HTTP integration to discover and query a service, then follow the proof and evidence workflow for local proving, delivery, verification, and recovery.

Three independent decisions​

DecisionAuthority and meaning
Protocol executionContracts enforce spending authorization, value conservation, and nullifiers. Protocol RPC reports indexed chain facts.
Source recognitionProvenance checks the configured sources and required input proofs, independently authenticates finalized chain facts, and publishes recognition.
Relay admissionA Broadcaster decides whether to accept a request, including its source requirements, quote, simulation, and broadcast policy.

broadcastDecision: "allow" is a short-lived preflight decision. It does not mean a transaction was sent, included, finalized, or recognized. A source-proof job marked valid also does not establish final recognition. Wait for the original operation to become recognized with a published checkpoint.

Source recognition happens off-chain and does not change the Protocol's spending rules. A source rejection does not freeze the on-chain asset, revoke an already broadcast transaction, or create an automatic refund. A different relay cannot manufacture recognition under the same issuer's rules.

Which operations need which evidence?​

OperationRequired source evidenceRecognized object
Shield or transact with public funding and no ordinary Note inputsActual public payer, token, and received principal; required source checksOrdinary Note outputs
Private transact without public fundingLocal proof that every ordinary Note input belongs to the recognized setAll ordinary Note outputs; a withdrawal can also have an operation-recognition record
Transact mixing public funding and ordinary Note inputsBoth public-source checks and the private-input source proofAll outputs after both conditions pass
Credit drawEach actual payer's gross debit and source checksThe single ordinary Note output
Credit create, update, revokeNo ordinary Note input-source proofNo recognition-tree leaf for the Credit state

Credit states represent debit authority, not funded ordinary Notes. Fees are public accounting and do not gain a complete private source proof from this workflow. Aggregate members have independent operation locators and proofs; one recognized member does not establish recognition for the whole transaction. Direct token donations without a legitimate Note output do not create recognized leaves.

Establish trust before accepting a result​

A Merkle root commits to a set. Its signature authenticates an issuer's claim about that set; it cannot prove the external supplier's risk judgment is true. Provision these inputs through your independently trusted deployment and release process:

  • Expected network identity, chainId, Core instance address, and deployed code identity.
  • Provenance issuer providerId, initial Ed25519 signing public key, accepted signing-key history, and signed rotations.
  • Accepted screening rules, required external source identities, capabilities, chain coverage, thresholds where applicable, and freshness limits.
  • The independent provenance proof manifest SHA-256 and authenticated artifacts, verification keys, and compatible local prover resources.

The issuer's providerId and its signing keys are distinct from the external screening providers. Check common response identity fields (scope, chainGeneration, providerId, signingKeyId, manifestSha256) against your trust configuration. getRules exposes rules and key history for comparison; accepting whatever public key the same unknown endpoint returns does not establish trust. Discovery and version strings are compatibility metadata.

Validate root signatures and signed rotations with the specified canonical encoding, then check scope, generation, published status, and canonical finalized block anchor. A historical certificate can remain usable without a recent issue time. Your current chain and generation context must still be fresh enough to detect invalidation.

Understand the source policy​

The service consumes configured external sources; it does not investigate addresses, maintain a blacklist, or publish a list. Required providers use an all-required rule: every required source must allow every applicable public funding source. rejected means an explicit refusal; unavailable means missing coverage, no conclusion, expiry, or a technical/trust failure. Neither permits recognition. Provider availability does not imply a favorable verdict.

Address-list matching checks an address against a particular dataset. It does not establish upstream tracing or the complete history of funds. Even an adapter labeled transaction-risk may assess payer-address exposure rather than this exact transaction, token, or amount. Inspect the declared capability and coverage before describing the result to your users.

Source revisions and assessment times belong to the evidence. A fetch timestamp does not establish when upstream learned a fact. Adapter support does not establish that an operator has the required credentials, coverage, or commercial authorization. Confirm that the selected source data is still maintained and read the deployed service's authenticated declarations. Do not assume a default vendor set or treat discontinued data as a current risk assessment.

Finality and continuity​

Formal recognition requires the primary chain's native finalized block and canonical block-hash checks. There is no confirmation-depth or elapsed-time fallback. A chain can appear in discovery and have visible execution while recognition waits for supported, available native finality. FINALITY_UNSUPPORTED, FINALITY_UNAVAILABLE, and FINALITY_INCONSISTENT need distinct handling.

After publication, recognition for funds that remain canonical is not revoked merely because a risk list changes later. A reorganization corrects chain facts and can advance chainGeneration; old-generation roots stop authorizing new proofs. Private descendants may need new source proofs under rebuilt recognition trees. The original payer's retained local inputs can be essential; a recipient's output Note alone cannot guarantee recovery.

Recognition-tree membership is independent of the Protocol Note tree and does not prove that a Note is unspent. Preserve the distinction in balances and UI: received/on-chain assets, recognized sources, and relay-ready inputs are separate properties.