@clearproof/content 0.5.0

package/content/explainers/pilot-proof-public-signals.md

@@ -0,0 +1,80 @@
+---
+id: UP-EX-002
+title: The pilot proof's eight public signals — what they show and what they hide
+date: 2026-09-16
+publishAfter: 2026-09-16T00:00:00Z
+sourceCommit: caa15cb49a3d9da8f0978dcfaebf5bf958161b67
+claimRefs:
+  - README.md
+  - specs/pilot-transfer-v3.md
+  - packages/content/content/topics/security.md
+  - packages/content/content/topics/circuits.md
+status: approved
+summary: A Clearproof pilot proof publishes exactly eight public signals. Reading them is the fastest way to understand what a verifier learns without the encrypted envelope — and what it still cannot conclude.
+canonical: /explainers/pilot-proof-public-signals
+templateVersion: explainer-v1
+---
+
+Every Groth16 proof publishes a fixed array of public signals. In a Travel Rule
+system those signals are metadata that any verifier — and anyone who sees the
+proof — can read. So before evaluating any privacy claim, it is worth reading
+the actual array. Clearproof's current pilot profile, `pilot-transfer-v3`, has
+exactly eight. The
+[public statement](https://github.com/repfigit/clearproof/blob/main/specs/pilot-transfer-v3.md)
+in the repository lists them in mandatory order:
+
+| Index | Signal |
+| --- | --- |
+| 0 | `projection_commitment` |
+| 1 | `authorized_issuer_root` |
+| 2 | `sanctions_root` |
+| 3 | `authorization_nullifier` |
+| 4 | `evaluated_at` |
+| 5 | `proof_expires_at` |
+| 6 | `domain_chain_id` |
+| 7 | `domain_registry` |
+
+## What a verifier learns from these alone
+
+The three root signals (`authorized_issuer_root`, `sanctions_root`) and the
+timestamp pair (`evaluated_at`, `proof_expires_at`) say which sanctions tree,
+issuer set and validity window the proof was built against. The domain pair
+(`domain_chain_id`, `domain_registry`) pins the exact chain and registry
+deployment the proof is bound to, which is what stops a proof made for one
+deployment being replayed against another.
+
+Two signals deserve closer reading. `projection_commitment` is a Poseidon hash
+over the 48-field canonical transfer projection, the exact credential
+commitment and the issuance root — it reveals nothing about the fields, but it
+does mean the verifier must independently reconstruct the expected commitment
+from its own authenticated records before the proof means anything.
+`authorization_nullifier` is deliberately unlinkable-by-design across
+contexts: it prevents the same holder authorization being consumed twice
+without identifying the holder.
+
+## What is deliberately not public
+
+The v3 profile carries **no public amount tier and no SAR advisory flag**. The
+[README](https://github.com/repfigit/clearproof/blob/main/README.md) is
+explicit about this, and about the contrast: the older 16-signal
+`compliance.circom` demo profile publishes amount-tier and SAR metadata among
+its sixteen values. The README warns never to select artifacts by signal count
+alone and never to reinterpret legacy proofs as current pilot authorization —
+a real risk, because both profiles have passing tests and committed manifests.
+
+## The boundary that matters more than the signal list
+
+The security documentation states the boundary directly: public signals expose
+metadata, and omitting a named field from a bridge payload does not conceal
+information that remains in the public-signal array. A valid proof establishes
+its encoded statement — nothing more. Proof verification alone neither
+authenticates the verifier's reconstructed records nor establishes current
+roots, revocation, policy compliance or legal compliance. Current circuits and
+contracts have not completed an independent audit, and generated proving keys
+are explicitly unapproved development artifacts.
+
+If you are evaluating the system, the signal array is where to start: it tells
+you exactly what every observer learns, before any encrypted envelope is even
+opened. The full statement, including the private 48-field projection and the
+subcircuit binding, is in
+[specs/pilot-transfer-v3.md](https://github.com/repfigit/clearproof/blob/main/specs/pilot-transfer-v3.md).

package/content/explainers/portable-evidence-review.md

@@ -0,0 +1,103 @@
+---
+id: UP-EX-006
+title: Portable evidence review — taking the receipt out of the operator's hands
+date: 2026-09-28
+publishAfter: 2026-09-28T00:00:00Z
+sourceCommit: 61d6b1f2d133ce32796efa015cdac34c06b266b0
+claimRefs:
+  - README.md
+  - docs/operations/local-pilot-acceptance.md
+  - src/services/evidence_export.py
+  - src/prover/history_cli.py
+  - src/prover/history.py
+  - src/chain/audit_mirror.py
+status: approved
+summary: Clearproof's retained evidence is exported as a recipient-encrypted HPKE bundle and reviewed offline by a process that disables its own networking, with every pin supplied by the reviewer rather than the exported bundle. This explainer walks through that path and the three outcomes it can report.
+canonical: /explainers/portable-evidence-review
+templateVersion: explainer-v1
+---
+
+An export feature can be cosmetic: a button that hands you a file the
+operator's servers must interpret. The question worth asking of any compliance
+system is whether retained evidence can be carried to a reviewer and checked
+without the operator in the loop. In Clearproof's current source, that path
+exists end to end, and its trust placement is the interesting part: the
+reviewer, not the export, decides what counts as evidence.
+
+## The export is encrypted to a recipient, not to the operator
+
+The local pilot's acceptance run retains a `history.encrypted.json` file —
+described in [the acceptance guide](https://github.com/repfigit/clearproof/blob/main/docs/operations/local-pilot-acceptance.md)
+as the "recipient-encrypted historical evidence export." In source, the export
+service (`src/services/evidence_export.py`) builds the bundle only for a
+principal holding both `evidence:export` and `evidence:decrypt` roles, only
+while the configured recipient's approval window is open, and only against a
+pinned authorization receipt whose identity digests, transfer and context
+digests must match across the receipt, the proof and the evidence manifest.
+Every referenced record is re-read and compared byte-for-byte against its
+pinned SHA-256, up to a hard limit of 80 records.
+
+The bundle is then sealed with [HPKE (RFC
+9180)](https://github.com/repfigit/clearproof/blob/main/src/sar/hpke_envelope.py)
+to the recipient's X25519 public key, with the export binding — tenant,
+receipt, reviewer, key id, export time — bound as associated data. The
+operator cannot later open this file; only the holder of the reviewer key can.
+And the private half of that key is never captured in reports: the acceptance
+guide states plainly that it stays in `pilot/private/` and must not be
+published.
+
+## The reviewer supplies the pins; the bundle never does
+
+`src/prover/history.py` says it in one line: "Pins and verifier come from the
+reviewer, never from the exported bundle." The offline CLI (`src/prover/history_cli.py`)
+takes the encrypted bundle, a separately configured reviewer trust file, and an
+explicit list of trusted inputs — the artifact directory, the pinned snarkjs
+runtime bundle, the Node executable, and the review clock. `open_evidence_bundle`
+decrypts with the recipient's private key and immediately qualifies itself: the
+docstring notes decryption "does not validate historical compliance or sender
+identity." Decryption is a door, not a verdict.
+
+The integrity pass that follows binds everything together: the receipt, proof
+and manifest digests must agree, the retained proof must hash to its pinned
+digest, the nullifier and expiry signals must match the receipt, and the
+captured configuration — artifact manifest, verification key, asset registry,
+valuation approval, root pins — must match both its recorded digests and the
+artifacts the reviewer chose to trust. If a pinned record is missing entirely,
+the result is `indeterminate` with `missing_evidence`, not a best-effort pass.
+
+## What the offline review can conclude
+
+`inspect_history_bundle` reports one of three outcomes, each with named
+reasons: `supported`, `indeterminate`, or `contradicted`. Six independent
+authorities stand between decryption and a `supported` verdict — statement
+reconstruction at the claimed authorization time, policy replay from pinned
+fact records, the signed decision attestation, historical non-revocation
+status, independent timing evidence, and the information authority's signed
+approval. Any authority the reviewer has not configured leaves the outcome
+`indeterminate` with the specific gap named (`decision_authority_unverified`,
+`historical_revocation_evidence_missing`, and so on). A mismatch — wrong
+signals, invalid pairing, bad decision or information signature — is
+`contradicted`.
+
+That vocabulary is the design's honesty made mechanical: the reviewer cannot
+get a clean bill of health by skipping checks, because each skipped check is
+visible in the output as a named gap.
+
+## The mirror, and what none of this establishes
+
+Alongside on-chain events, `src/chain/audit_mirror.py` writes an append-only
+JSON Lines audit mirror — for regulatory examination, offline access during
+chain downtime, and context not stored on-chain — where every record carries
+the SHA-256 of the previous record, forming a tamper-evident hash chain that
+`verify_integrity` can re-check. Each writer derives the predecessor from the
+file while holding the lock through fsync; no cached tail is trusted.
+
+The boundaries stay explicit. This is a local source-checkout workflow with
+synthetic fixtures — the acceptance guide warns that a copied trust file is
+not an independently approved production trust configuration, that changing
+the review clock "asks a different historical trust question," and that the
+M0–M5 acceptance is complete only for the local scope. Live provider access,
+customer validation and production assurance remain follow-on gates. What the
+source does establish is the shape: evidence that travels encrypted to a named
+reviewer, with trust placed in the reviewer's pins rather than the operator's
+say-so.

package/content/explainers/usd-cents-without-a-price-feed.md

@@ -0,0 +1,106 @@
+---
+id: UP-EX-005
+title: USD cents without a price feed — how the pilot proof handles valuation
+date: 2026-09-22
+publishAfter: 2026-09-22T00:00:00Z
+sourceCommit: dfda3eab85b9ab2e664826e05ee455e4c0cdad1c
+claimRefs:
+  - docs/adr/0007-scoped-valuation-approvals.md
+  - src/protocol/valuation_approval.py
+  - src/prover/pilot_valuation.py
+  - src/protocol/transfer.py
+status: approved
+summary: The pilot circuit proves exact USD-cent arithmetic over a quoted price, but no oracle tells it what the price is. Reading the scoped valuation approval design shows where pricing trust actually lives — and why a proof of arithmetic is not a proof of price.
+canonical: /explainers/usd-cents-without-a-price-feed
+templateVersion: explainer-v1
+---
+
+Travel Rule compliance turns a transfer of tokens into a question about money:
+how much is this worth in USD, and does it cross a reporting threshold? That
+question hides a hard dependency. Somewhere, something must assert a price. In
+Clearproof's current source, that "something" is not an oracle inside the
+circuit — it is a signed approval checked outside it, and the source is explicit
+that its truthfulness remains an assumption. This explainer walks through how a
+USD valuation enters the pilot proof, what the circuit proves about it, and what
+it deliberately does not.
+
+## The quote is a rational number, not a feed
+
+The pilot transfer record carries a `Valuation` (`clearproof-valuation-v1`,
+defined in
+[src/protocol/transfer.py](https://github.com/repfigit/clearproof/blob/main/src/protocol/transfer.py)):
+a rational USD-cents-per-base-unit price as an exact 128-bit numerator over
+denominator, an asset ID, observation and expiry times, a source ID and a
+SHA-256 digest of the source evidence. The comment in the source says the ratio
+must be reduced and that no stablecoin peg is assumed. Nothing in the record
+claims the price is current, best, or even true — it claims only what was
+observed, from which source, with which evidence digest, over which interval.
+
+## The circuit proves arithmetic, not price
+
+Inside the composed pilot circuit, the valuation sub-problem is pure integer
+arithmetic (`src/prover/pilot_valuation.py`): multiply the transfer amount by
+the numerator, divide by the denominator, and constrain both the USD-cent
+quotient and the remainder. The remainder is constrained so the quotient is the
+exact floor of the division — not an approximation the prover can nudge. The
+reduced ratio itself participates in the private projection, so a proof made
+with one price cannot be re-verified against a different one.
+
+But no Circom constraint makes the numerator or denominator equal to a market
+price. The circuit proves: "given these inputs, the USD cents figure follows."
+It cannot prove: "these inputs are what the market said."
+
+## The approval layer: signatures, not oracles
+
+Commit 2a3dbc7 introduced the
+[`ValuationApproval`](https://github.com/repfigit/clearproof/blob/main/src/protocol/valuation_approval.py)
+layer. An authority signs the complete valuation — the quote, tenant, asset
+catalog digest, signing time and key ID — under a dedicated Ed25519 domain
+(`clearproof/valuation-approval/v1`, with a separate key domain for
+`clearproof/valuation-key/v1`). The approval binds the quote's full validity
+interval: an approval must be signed while the quote is live, and freshly
+signing an old observation cannot reset its age.
+
+Operator configuration pins each public key to a tenant, a catalog digest,
+exact chain-qualified assets, exact source IDs and a key validity interval.
+Verification checks the quote against the trusted catalog, tenant, signing
+time, expiry, key interval, source and asset scope, and the signature itself.
+
+[ADR 0007](https://github.com/repfigit/clearproof/blob/main/docs/adr/0007-scoped-valuation-approvals.md)
+is explicit about the boundary: "The signing authority must validate the source
+evidence and correct asset/base unit interpretation before signing... The
+authority's pricing truthfulness is an explicit trust assumption. No stablecoin
+peg is inferred. This approves a scoped quote within configured bounds, not
+necessarily the latest quote, a business policy, legal compliance or
+settlement."
+
+## Why the signature is checked outside the circuit
+
+The Ed25519 signature verification happens in the application layer, not
+inside the Circom circuit. ADR 0007 says this directly: "Ed25519 signatures are
+verified outside the circuit; they are not claimed to be ZK-verified." Inside
+the circuit, the signed quote's operands feed the projection; the application
+verifier independently re-validates the quote using its authenticated tenant
+and actual clock before accepting the projection.
+
+This split matters for evaluation. A proof says the arithmetic is right for the
+bound quote. The approval says an operator-chosen authority endorsed the quote.
+Neither says the quote reflects any market. That three-way split — arithmetic,
+endorsement, truth — is the honest description of the pilot's pricing boundary.
+
+## What this means for an evaluator
+
+If you evaluate a system that claims ZK Travel Rule compliance, ask where the
+price comes from. A useful checklist, grounded in this source:
+
+- Is the quote an exact rational with evidence digest and validity interval, or
+  a floating-point number that could silently lose precision?
+- Who signs the approval, and what are they trusted to know?
+- Is the signature verified in-circuit, or is that verification honestly
+  described as application-layer?
+- Does the documentation claim the circuit proves price truth, or does it
+  state, as ADR 0007 does, that pricing truthfulness is a trust assumption?
+
+Clearproof's current source takes the fourth position, and states it. That
+statement is not a weakness in the design — it is the design making its trust
+boundary visible instead of hiding it inside a proof that cannot carry it.

package/content/explainers/verify-independently.md

@@ -0,0 +1,106 @@
+---
+id: UP-EX-004
+title: Verifying a Clearproof proof without trusting Clearproof
+date: 2026-09-21
+publishAfter: 2026-09-21T00:00:00Z
+sourceCommit: cd63c3a06b978b5401ff9641260882c96fa31037
+claimRefs:
+  - packages/proof/src/verifier.ts
+  - packages/proof/src/thresholds.ts
+  - packages/contracts/contracts/ComplianceRegistry.sol
+  - README.md
+status: approved
+summary: Clearproof's TypeScript SDK ships no baked-in proving or verification keys, and the CLI's verify command takes a proof file plus any verification key you point it at. This explainer walks through what an independent verifier can check — and the one signal block that a pairing check alone would let a prover abuse.
+canonical: /explainers/verify-independently
+templateVersion: explainer-v1
+---
+
+*Scope: this explainer walks through the SDK's `verifyProof` path for the
+legacy 16-signal demo profile. Current `pilot-transfer-v3` proofs publish eight
+values with no tier thresholds or review flag, and are checked by the pilot's
+authorization service; see [the eight public signals](/explainers/pilot-proof-public-signals).*
+
+A fair question for any compliance tool: do you have to trust the vendor to
+check its own proofs? In Clearproof's current source, the answer is no —
+verification is caller-supplied and separately runnable. This explainer walks
+through what an independent verifier can check with only the public source, the
+proof, and a verification key, and where the checks are stricter than a bare
+pairing check.
+
+## No baked-in keys
+
+The [`@clearproof/proof`](https://github.com/repfigit/clearproof/blob/main/packages/proof/AGENTS.md)
+SDK has **no baked-in artifacts**. `verifyProof` reads the verification key
+from a caller-supplied `vkeyPath` and hands the proof, the public signals and
+that key straight to `snarkjs.groth16.verify`. Nothing about the result depends
+on a Clearproof-operated service. The CLI's `verify` command follows the same
+shape: `--proof <file>` plus an `--artifacts <dir>` the caller controls, and it
+exits non-zero when verification fails.
+
+That design has a consequence worth stating: the security of a verification
+inherits the provenance of the verification key. An independent verifier
+should obtain `verification_key.json` from a source it controls or has
+audited — the project's own documentation notes that production proving keys
+are expected to come from a documented multi-party ceremony, and that
+development artifacts are local-only and not safe for production. The tool
+does not make that choice for you; it refuses to hide it.
+
+## What a pairing check alone would miss
+
+The circuit takes the tier thresholds (`tier2_threshold`, `tier3_threshold`,
+`tier4_threshold` — public signals 8 through 10) as **unconstrained public
+inputs**. The prover chooses them. A proof could therefore be cryptographically
+valid while embedding an arbitrarily high `tier2_threshold`, landing any
+transfer amount in tier 1 and defeating both the tier attestation and the SAR
+review flag.
+
+Clearproof's verifier handles this explicitly rather than leaving it to the
+caller: `verifyProof` returns `valid = proofValid && thresholdsBound`, where
+`thresholdsBound` checks the submitted thresholds against the jurisdiction
+table in [`packages/proof/src/thresholds.ts`](https://github.com/repfigit/clearproof/blob/main/packages/proof/src/thresholds.ts).
+That module's own comment is the design rationale: these thresholds are a
+*consensus parameter*, not a local preference — if the table disagrees with the
+Python SDK or the on-chain `ComplianceRegistry`, proofs will verify in one
+place and fail in another.
+
+The on-chain registry enforces the same discipline. `ComplianceRegistry`'s
+`verifyAndRecord` deliberately rejects any proof whose thresholds disagree
+with the table stored on-chain, and its threshold-setting function reverts if
+the table is not strictly ordered (`tier2 < tier3 < tier4`), because an
+out-of-order table would silently make some tiers unreachable.
+
+## The other signals an independent verifier can read
+
+Beyond the two interpreted outputs — `publicSignals[0]` is `is_compliant`,
+`publicSignals[1]` is `sar_review_flag` — the full signal array is returned
+with the verification result, so a reviewer can check:
+
+- **Jurisdiction** (signal 6), decodable from its big-endian ASCII value
+  ("US" → `0x5553`); a value that is not two uppercase ASCII letters decodes
+  to `null` rather than a plausible-looking code.
+- **Jurisdiction–VASP consistency**, via the optional
+  `expectedJurisdiction` argument. The result distinguishes a real mismatch
+  from *unverified*: with no expected jurisdiction supplied,
+  `jurisdictionMatchesVASP` is `null`, never silently `true`.
+- **Rejection reasons**: the result carries explicit `rejectionReasons`
+  (`groth16_invalid`, `threshold_mismatch`) instead of a bare boolean, so a
+  failed verification says *why*.
+
+## What independent verification does not establish
+
+A valid verification is a statement about one proof against one key. It does
+not establish that the input commitments behind the proof came from trusted
+records, that the sanctions root is current (the root is relayed across
+deployed chains and staleness is a live deployment question), or that any
+counterparty's policy obligations are met. Those remain the registry and
+application checks described in the [previous
+explainer](/explainers/who-verifies-what).
+
+## The practical takeaway
+
+For an evaluator, the check is concrete and runnable today: take a proof file,
+a verification key from a source you control, and run the CLI's `verify`
+command — the same pairing check the project itself relies on, with the
+threshold-binding check that a bare snarkjs call would skip. The source makes
+that path deliberately short, and deliberately honest about what a valid proof
+still leaves open.

package/content/explainers/what-clearproof-does.md

@@ -0,0 +1,92 @@
+---
+id: UP-EX-001
+title: What Clearproof does — and what a valid proof does not establish
+date: 2026-09-13
+publishAfter: 2026-09-13T20:30:00Z
+sourceCommit: 4ed9a6ac19bbb9b479dc271b148731d1ecb04cb0
+claimRefs:
+  - README.md
+  - docs/ADOPTION_ROADMAP.md
+  - packages/content/content/topics/security.md
+  - packages/content/content/topics/quickstart.md
+status: approved
+summary: Clearproof combines scoped zero-knowledge statements, encrypted transfer information, policy decisions and retained evidence for controlled evaluation. This explainer walks through what that means in the current source, and where the proof's guarantee stops.
+canonical: /explainers/what-clearproof-does
+templateVersion: explainer-v1
+---
+
+Clearproof is an open-source project for privacy-preserving crypto transfer
+evidence. Its [README](https://github.com/repfigit/clearproof/blob/main/README.md)
+states the scope plainly: scoped zero-knowledge statements, encrypted transfer
+information, policy decisions and retained evidence for controlled evaluation by
+stablecoin processors and custodians. In the FATF Travel Rule context, the
+recurring problem is sending required transfer information to a counterparty
+without exposing more than required — and retaining evidence you can review
+later. Clearproof's answer is a Groth16 proof plus the required personal
+information encrypted to the receiving institution's key (HPKE), bound to the
+same transfer.
+
+## What the source checkout implements today
+
+The unreleased 0.4.0 development checkout implements a local adoption pilot:
+
+- Authenticated credential enrollment with holder-bound issuance membership and
+  a canonical transfer/context projection using exact asset and valuation
+  arithmetic.
+- Encrypted tenant-scoped storage with retained policy, root and revocation
+  history, actor-bound retries and atomic authorization consumption.
+- Explained policy evaluation, comparison, review and activation history.
+- Signed synthetic custody-event ingestion, simulated bilateral outcomes and
+  read-only transfer investigations with independent lifecycle states.
+- Non-authorizing observation reports with scoped coverage, disagreement and
+  timing.
+- Recipient-encrypted historical exports and offline review under independently
+  configured proof, policy, source, decision, status and timing authorities.
+
+The current pilot proof profile, `pilot-transfer-v3`, has eight public signals
+with no public amount tier or SAR advisory flag. The older 16-signal
+`compliance.circom` profile remains a separate legacy demo path — the README
+warns never to select artifacts by signal count alone.
+
+## What a valid proof establishes — and what it does not
+
+This is the boundary worth internalizing before any evaluation: a valid proof
+establishes its encoded statement. It does not establish legal compliance,
+source truth, counterparty acceptance or settlement by itself. Concretely, from
+the [security boundaries](https://github.com/repfigit/clearproof/blob/main/packages/content/content/topics/security.md)
+documentation:
+
+- Credential authenticity, holder authority, jurisdiction and actual transfer
+  binding require coordinated improvements across the proof statement and the
+  application.
+- Replay, expiry and root checks depend on the verifier and its configuration.
+- A cryptographically valid proof is not an accepted transfer.
+
+## What is available to install
+
+Public npm packages are at **0.3.0** while the development checkout is **0.4.0**;
+they are not the same. `@clearproof/proof` 0.3.0 installs as an SDK, but proof
+generation requires compatible circuit WASM and proving-key files supplied by
+the caller. The public CLI install is currently blocked by an unavailable
+registry dependency. The practical evaluation path is a
+[source checkout](https://github.com/repfigit/clearproof/blob/main/packages/content/content/topics/quickstart.md):
+clone, build from the committed lockfiles, and run the documented local pilot,
+which owns a disposable PostgreSQL cluster and loopback EVM and exercises real
+proofs. A documented clean-checkout checkpoint (September 7, 2026) reproduced
+this workflow end to end, including an offline historical review with network
+connections disabled.
+
+## Assurance status, stated once
+
+Current circuits and contracts have not completed an independent audit, and
+generated proving keys are explicitly unapproved development artifacts. Use
+synthetic data and testnet funds. Development proofs and passing local tests do
+not establish production readiness — see the
+[adoption roadmap](https://github.com/repfigit/clearproof/blob/main/docs/ADOPTION_ROADMAP.md)
+for what the project treats as its public priorities and follow-on gates.
+
+If that scoped problem — verifiable transfer statements with minimized data
+exposure and independently reviewable retained evidence — matches a workflow you
+own, the fastest next step is the [full walkthrough](https://github.com/repfigit/clearproof/blob/main/packages/content/content/recipes/full-walkthrough.md):
+build the sanctions tree, issue a credential, generate a proof, verify it, and
+record the verified result on a testnet registry.

package/content/explainers/who-verifies-what.md

@@ -0,0 +1,86 @@
+---
+id: UP-EX-003
+title: Who verifies what — circuit, registry and application responsibilities in Clearproof
+date: 2026-09-17
+publishAfter: 2026-09-17T00:00:00Z
+sourceCommit: eaab3d020c6d3f2943cb20d56633e919d6c1579e
+claimRefs:
+  - packages/content/content/topics/architecture.md
+  - specs/pilot-transfer-v3.md
+  - packages/content/content/topics/security.md
+  - README.md
+status: approved
+summary: A zero-knowledge proof is one verifier among several. Reading where Clearproof's circuit stops and the registry and application take over is the difference between evaluating the system and over-crediting the math.
+canonical: /explainers/who-verifies-what
+templateVersion: explainer-v1
+---
+
+A recurring evaluation mistake with zero-knowledge compliance systems is
+treating the proof as the security model. In Clearproof's source, the proof is
+one verifier among at least three, and the [architecture
+documentation](https://github.com/repfigit/clearproof/blob/main/packages/content/content/topics/architecture.md)
+draws the line explicitly: "The circuit constrains particular mathematical
+relationships. The application establishes trusted input sources and the policy
+context. The registry additionally checks on-chain state, domain, expiry,
+revocation and replay. Do not collapse these into a single claim that every
+security property is proved by the circuit."
+
+## What the circuit constrains
+
+The pilot profile `pilot-transfer-v3` (Circom `pilot_compliance.circom`) proves
+statements over the 48-field canonical transfer projection. Its public signals
+include the projection commitment, issuer and sanctions tree roots, an
+authorization nullifier, and domain binding (`domain_chain_id`,
+`domain_registry`) that stops a proof built for one deployment being replayed
+against another. The commitment binds the exact credential and issuance root
+used by the credential subcircuit — the spec is explicit that it "is not a
+caller-selected opaque assertion."
+
+But the [public
+statement](https://github.com/repfigit/clearproof/blob/main/specs/pilot-transfer-v3.md)
+also states the boundary plainly: "Proof verification alone neither
+authenticates those records nor establishes current roots, revocation, policy
+compliance or legal compliance. The profile cannot authorize replay through
+historical inspection."
+
+## What the registry checks that the circuit does not
+
+The registry is a second verifier. Per the architecture documentation, it
+checks on-chain state, domain, expiry, revocation and replay. The development
+registry includes a versioned verifier router, so a deployed registry and its
+selector/artifacts must be checked against the intended proof version — v1 and
+v2 profiles have the same signal count but different first-signal meanings and
+different keys, and current artifact-context and root checks reject v1. That
+router is what stops a proof built against one proving-key generation from
+being verified against the wrong artifacts.
+
+## What the application owns outright
+
+The application layer establishes trusted input sources and the policy context.
+The circuit never sees raw sanctions data or credential fields — it sees
+commitments built from them. So the integrity of those commitments inherits
+every assumption of the enrollment and projection pipeline: canonical
+projection arithmetic, credential issuance membership, and the sanctions tree
+build (script `scripts/build_sanctions_tree.py`, root relayed via the
+SanctionsOracle). If an input source is untrusted, the proof is faithfully
+proving a statement about untrusted data.
+
+## Practical reading for evaluators
+
+Three checks that don't require running anything:
+
+1. **Match the profile to the artifacts.** Check the registry's versioned
+   router against the manifest's named profile (v2 manifests name it
+   explicitly; legacy manifests retain v1 meaning). Never select artifacts by
+   signal count alone — v1 and v2 both have eight.
+2. **Ask who maintains the roots.** The sanctions root is relayed to the
+   oracle across all deployed chains; a stale root is a live question for any
+   deployment you evaluate, and proof verification alone does not establish
+   current roots or revocation.
+3. **Trace trusted-input provenance.** The proof binds commitments; the
+   application binds the data behind them. Evaluating only the circuit
+   under-credits the registry checks and over-credits the math.
+
+The opening line is the architecture documentation's own summary, and it is the
+right one: the circuit, the registry and the application each verify a
+different layer, and a complete evaluation reads all three.

package/content/recipes/deploy-contracts.md

@@ -0,0 +1,45 @@
+---
+title: Deploy Contracts to Sepolia
+prereqs:
+  - sepolia-rpc
+  - funded-deployer
+estimated-time: 5 min
+---
+
+# Deploy Contracts to Sepolia
+
+Deploy the full contract suite (Groth16Verifier, SanctionsOracle, VASPRegistry, ComplianceRegistry, SanctionsRootRelay) to Sepolia testnet and verify on Etherscan.
+
+## 1. Set environment variables
+
+```bash:run
+export SEPOLIA_RPC_URL="https://rpc.sepolia.org"
+export PRIVATE_KEY="YOUR_DEPLOYER_PRIVATE_KEY"
+export ETHERSCAN_API_KEY="YOUR_ETHERSCAN_API_KEY"
+```
+
+Expected: No output (variables set)
+
+## 2. Compile contracts
+
+```bash:run
+cd packages/contracts && npx hardhat compile
+```
+
+Expected: `Compiled N Solidity files successfully`
+
+## 3. Deploy all contracts
+
+```bash:run
+cd packages/contracts && npx hardhat run scripts/deploy.ts --network sepolia
+```
+
+Expected: Five contract addresses printed, deployment artifacts written to `deployments/sepolia/`
+
+## 4. Verify on Etherscan
+
+```bash:run
+cd packages/contracts && npx hardhat run scripts/verify-etherscan.ts --network sepolia
+```
+
+Expected: All five contracts verified on Sepolia Etherscan with green checkmarks