Skip to main content

Source proofs, delivery, and evidence

The payer generates a source proof locally when spending ordinary private Note inputs. The receiver can verify the output's published recognition without learning those inputs. Keep this workflow separate from payment execution: delivering or retrying source evidence never sends a payment.

Freeze the operation before proving​

  1. Verify input ownership and Protocol spend state through your wallet's ordinary flow. If your relay requires recognized inputs, select from that set without hiding other received assets.
  2. Prepare the operation and settle the final service quote. Freeze its calldata, ordered ordinary Note inputs, outputs, and public funding statement.
  3. Generate the Core transaction proof and the independent source proof for the same operation. Authenticate source roots and build membership paths locally where possible.
  4. Deliver the source evidence, obtain the required preflight/tracking result, and persist it before handing payment to the broadcaster.
  5. Send the payment through the separately authorized wallet/relay flow, then observe recognition for that exact operation.

Source proofs do not enter the main contract calldata. A changed service fee can change the public operation statement and invalidate its source-proof binding. Rebuild against the final statement before broadcasting; do not reprice an already submitted payment during evidence recovery.

Local proving needs compatible SDK/prover code and independently authenticated provenance artifacts, manifest, verification keys, and prover resources. Provision native tools/CRS or the supported browser backend for your chosen runtime. The Provenance service is a verifier and offers no witness-generation or remote-proving endpoint. Check actual runtime support and resource requirements before promising browser or mobile proving to users.

What the proof binds​

A bundle uses format: "invisi-provenance-proof-v1", target: "evm", the authenticated circuitId and manifestSha256, eleven publicInputs, hex proof bytes, and rootCertificates. The public-input order is:

chain_id, protocol_address, token_address, chain_generation,
source_count, sources_digest, input_count,
operation_digest_hi, operation_digest_lo, input_digest, binding

All eleven values are canonical BN254 field words. The operation digest binds the canonical settlement statement; the input digest binds the ordered active Note nullifiers. Root certificates bind recognized membership to the same scope and generation. Use the SDK's canonical codec and authenticated manifest rather than hashing arbitrary JSON or choosing a verification key supplied by a server response.

The independent source circuit capacities are K10, K20, K40, K80, K120, K160, and K190. Select the smallest capacity covering the actual ordinary private Note input count, separately from the main circuit's capacity. Five inputs and ten outputs use K10 for source proving. No ordinary private inputs means no source membership proof.

For inputs spanning physical recognition trees, supply one covering certificate per tree in strictly increasing treeId order. All certificates must share the scope and current generation; their list must match source_count and sources_digest. A physical tree rotation does not itself change generation. Source roots do not prove input spendability; the Protocol's nullifier rules still apply.

Never transmit openings, input commitments paired with spend information, nonces, seeds, private/view keys, IPNs, membership witnesses, or decrypted balances to the service. Public proof inputs bind nullifiers and membership through digests, while the actual input openings and paths remain local.

Deliver evidence over HTTP​

These examples require the shell, curl, jq, and authenticated PROVENANCE_RPC configured in HTTP integration. First create candidate.json using your SDK's frozen final settlement calldata and genuine proof sidecars. Here, final means the transaction fields are fixed; it does not mean the transaction has reached chain finality. The following is a partial structure requiring a genuine proof and complete certificates:

{
"data": "0x<canonical settlement calldata>",
"proofSidecars": [
{
"operationIndex": "0",
"proofBundle": {
"format": "invisi-provenance-proof-v1",
"circuitId": "<ID from the authenticated manifest>",
"manifestSha256": "<authenticated 64-character SHA-256>",
"target": "evm",
"publicInputs": ["<exactly eleven canonical field words>"],
"proof": "0x<locally generated proof bytes>",
"rootCertificates": ["<complete authenticated certificate objects>"]
}
}
]
}

Each sidecar's index identifies its settlement member; at most five unique, in-range sidecars are accepted. A sidecar for a member without private Note inputs is invalid. The entire JSON request must fit the 256 KiB budget, even if the proof itself fits its decoded 64 KiB budget.

With a real candidate.json, pre-send evaluation is:

jq '{jsonrpc:"2.0",id:10,method:"provenance_evaluateTransaction",params:[.]}' \
candidate.json |
curl --fail-with-body --silent --show-error "$PROVENANCE_RPC" \
-H 'Content-Type: application/json' --data-binary @-

Inspect broadcastDecision, recognitionState, inputProofStatus, reasons, and validity times. An allowed private-input candidate must include durable tracking. Its operationDigest must match your frozen operation. Multi-member results place tracking under individual operations. Preflight validity is 30 seconds; inclusion and final recognition remain outstanding.

For source delivery before or after an independently sent payment, call provenance_submitSourceProof with the same query shape:

jq '{jsonrpc:"2.0",id:11,method:"provenance_submitSourceProof",params:[.]}' \
candidate.json |
curl --fail-with-body --silent --show-error "$PROVENANCE_RPC" \
-H 'Content-Type: application/json' --data-binary @-

This permits historical calldata matching only when payment settled within its original deadline. Repeated delivery can reuse tracking. No transaction hash notification is required on this path: the worker independently matches canonical finalized execution. Neither endpoint signs, sends, or resends the payment. Pure external-funding operations proceed through normal ingestion without a private tracking task.

Observe completion and recover safely​

Poll provenance_getTracking with {trackingId}. The ID is 48 lowercase hex characters without 0x; keep it private. Statuses are pending_confirmation, pending_source, recognized, expired, superseded, and stale_generation. A matched locator must equal the original payment's blockHash, txHash, and operationIndex. Then query that operation's recognition and verify its published checkpoint. A proof job's valid status alone is insufficient.

If an HTTP response is lost, reconcile the original transaction and existing task before doing more work. Pending source checks do not justify another payment. Expiry is based on complete, independently finalized history, not merely a local timer or a lagging index. Superseded and stale-generation tasks cannot simply be reopened with the old evidence.

For explicit machine recovery, provenance_submitProof accepts an already indexed operation locator, proofBundle, and idempotencyKey. Persist the exact request before submission. A lost response should be retried with the same body and key; changing the body under the same key returns IDEMPOTENCY_CONFLICT. Poll provenance_getProofJob using its returned jobId: queued, verifying, valid, invalid, retryable_error, or stale_generation. An invalid proof does not blacklist the Note. New generation or changed proof content requires freshly bound evidence and a suitable new key.

Retain verifiable evidence​

Keep in your applicationPurpose and privacy
Expected scope, issuer/key trust history, rules, manifest pin, generationReconstruct the trust context used to accept a claim
Frozen original calldata/hash, operation digest, ordered nullifiers, final quote and signed submission recordReconcile the exact payment and prevent accidental resends; protect as wallet operational data
Proof bundle, certificates, local delivery mode, tracking ID; recovery request/key and job ID when applicableResume delivery without inventing another operation; keep private machine identifiers out of Explorer and logs
Mined locator, final operation-recognition result, checkpoint certificate and necessary leaf/path evidenceVerify the published result against the intended operation and chain
Provider decision, adapter/capability, coverage, data/source version, assessment/expiry times and available evidence referencesExplain the precise public-source claim; evidence references are digests, not supplier reports
Original input openings and reconstruction material, encrypted locally under wallet-controlled accessRegenerate private proofs after a generation change; never upload as recovery data

A signature certificate contains issuer/key IDs, scope, generation, root sequence, physical tree ID, leaf count/root, confirmed block number/hash, decision-log hash, previous-checkpoint hash, issue time, and signature. Verify its canonical signature and anchor, then recompute your Note's membership from authenticated leaf/path evidence. Retain the certificate used for that check rather than assuming a later mutable view is equivalent.

Operation funding assessment history is bounded to 200 returned entries and reports truncation. Older finalized records can omit newer evidence fields. Do not treat one response as a complete archive or assume the service retains every pending candidate forever. Unreferenced terminal preflight verification caches are pruned after 24 hours; adopted proof evidence and published recognition history remain auditable. Confirm the operator's retention and export arrangements if your application needs a longer independent audit trail.

After a reorganization, first reconcile the original payment on the canonical chain, refresh generation and roots, and regenerate source evidence locally when required. Preserve old signed history for audit while refusing it for new proofs. A receiver with only the output cannot generally regenerate the payer's historical private-input proof.