@clearproof/content 0.5.0

package/content/recipes/full-walkthrough.md

@@ -0,0 +1,84 @@
+---
+title: Full End-to-End Walkthrough
+prereqs:
+  - api-running
+  - circuits-compiled
+  - contracts-deployed
+  - sepolia-rpc
+estimated-time: 10 min
+---
+
+# Full End-to-End Walkthrough
+
+> **Legacy demo path.** This recipe uses the 16-signal legacy profile (`/proof/generate`, `/proof/verify`). It does not exercise the current `pilot-transfer-v3` workflow; for that, follow the [local acceptance guide](https://github.com/repfigit/clearproof/blob/main/docs/operations/local-pilot-acceptance.md).
+
+Complete compliance flow: issue a credential, generate a proof, verify off-chain, and record on-chain.
+
+The local API defaults to API-key auth:
+
+```bash:run
+export CLEARPROOF_API_KEY="dev-api-key"
+export AUTH_MODE="api-key"
+export API_KEY="$CLEARPROOF_API_KEY"
+```
+
+## 1. Build the sanctions tree
+
+```bash:run
+python scripts/build_sanctions_tree.py --offline
+```
+
+Expected: Sanctions tree built with root hash and leaf count displayed
+
+## 2. Issue a zkKYC credential
+
+```bash:run
+curl -s -X POST http://localhost:8000/credential/issue \
+  -H "X-API-Key: $CLEARPROOF_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"issuer_did":"did:web:vasp.example.com","subject_wallet":"0x1234abcd5678ef901234abcd5678ef9012345678","jurisdiction":"US","kyc_tier":"retail"}'
+```
+
+Expected: 200 with `credential_id` and `commitment`
+
+## 3. Generate a compliance proof
+
+```bash:run
+curl -s -X POST http://localhost:8000/proof/generate \
+  -H "X-API-Key: $CLEARPROOF_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"credential_id":"CRED_ID_FROM_STEP_2","wallet_address":"0x1234abcd5678ef901234abcd5678ef9012345678","amount_usd":500,"asset":"USDC","destination_wallet":"0xabcd1234abcd1234abcd1234abcd1234abcd1234","jurisdiction":"US","idempotency_key":"recipe-full-001"}'
+```
+
+Expected: 200 with `compliance_proof` (Groth16 proof + 16 public signals) and `encrypted_pii`
+
+## 4. Verify the proof off-chain
+
+```bash:run
+curl -s -X POST http://localhost:8000/proof/verify \
+  -H "X-API-Key: $CLEARPROOF_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"proof_id":"PROOF_ID_FROM_STEP_3","groth16_proof":{"pi_a":["..."],"pi_b":["..."],"pi_c":["..."]},"public_signals":["1","0","..."],"expected_amount_tier":1,"originator_vasp_did":"did:web:vasp.example.com","transfer_timestamp":1711929600}'
+```
+
+Expected: 200 with `valid: true` and `is_compliant: true`
+
+## 5. Record the proof on-chain
+
+```bash:run
+export PROOF_PATH="$PWD/artifacts/latest_proof.json"
+export TRANSFER_ID="recipe-transfer-001"
+export VASP_DID="did:web:vasp.example.com"
+cd packages/contracts && npx hardhat run scripts/verify-onchain.ts --network sepolia
+```
+
+Expected: Transaction hash and `ProofVerified` event emitted on ComplianceRegistry
+
+## 6. Confirm on-chain recording
+
+```bash:run
+export TRANSFER_ID="recipe-transfer-001"
+cd packages/contracts && npx hardhat run scripts/check-transfer.ts --network sepolia
+```
+
+Expected: `isVerified` returns `true` for the transfer ID

package/content/recipes/generate-proof.md

@@ -0,0 +1,43 @@
+---
+title: Generate a Compliance Proof
+prereqs:
+  - api-running
+  - circuits-compiled
+estimated-time: 2 min
+---
+
+# Generate a Compliance Proof
+
+> **Legacy demo path.** This recipe uses the 16-signal legacy profile (`/proof/generate`, `/proof/verify`). It does not exercise the current `pilot-transfer-v3` workflow; for that, follow the [local acceptance guide](https://github.com/repfigit/clearproof/blob/main/docs/operations/local-pilot-acceptance.md).
+
+Issue a zkKYC credential and then generate a Groth16 compliance proof against it.
+
+The local API defaults to API-key auth:
+
+```bash:run
+export CLEARPROOF_API_KEY="dev-api-key"
+export AUTH_MODE="api-key"
+export API_KEY="$CLEARPROOF_API_KEY"
+```
+
+## 1. Issue a credential
+
+```bash:run
+curl -s -X POST http://localhost:8000/credential/issue \
+  -H "X-API-Key: $CLEARPROOF_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"issuer_did":"did:web:vasp.example.com","subject_wallet":"0x1234abcd5678ef901234abcd5678ef9012345678","jurisdiction":"US","kyc_tier":"retail"}'
+```
+
+Expected: 200 with `credential_id` and `commitment`
+
+## 2. Generate proof
+
+```bash:run
+curl -s -X POST http://localhost:8000/proof/generate \
+  -H "X-API-Key: $CLEARPROOF_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"credential_id":"CRED_ID_FROM_STEP_1","wallet_address":"0x1234abcd5678ef901234abcd5678ef9012345678","amount_usd":500,"asset":"USDC","destination_wallet":"0xabcd1234abcd1234abcd1234abcd1234abcd1234","jurisdiction":"US","idempotency_key":"recipe-generate-001"}'
+```
+
+Expected: 200 with `compliance_proof` containing Groth16 proof, 16 public signals, and `encrypted_pii`

package/content/recipes/update-sanctions.md

@@ -0,0 +1,35 @@
+---
+title: Update Sanctions Tree
+prereqs:
+  - api-running
+  - contracts-deployed
+estimated-time: 2 min
+---
+
+# Update Sanctions Tree
+
+Rebuild the sanctions Merkle tree from OFAC/UN/EU lists and relay the new root to the on-chain SanctionsOracle.
+
+## 1. Build the sanctions tree
+
+```bash:run
+python scripts/build_sanctions_tree.py --offline
+```
+
+Expected: Tree built with leaf count printed, root hash displayed. The `--offline` flag uses cached list data; omit it to fetch fresh lists from OFAC/UN/EU sources.
+
+## 2. Relay the new root to SanctionsOracle
+
+```bash:run
+python scripts/relay_sanctions_root.py --network sepolia
+```
+
+Expected: Transaction hash printed, `RootUpdated` event emitted on SanctionsOracle with new root and leaf count
+
+## 3. Verify the oracle is not stale
+
+```bash:run
+cd packages/contracts && npx hardhat run scripts/check-oracle-staleness.ts --network sepolia
+```
+
+Expected: `isStale` returns `false`, `lastUpdated` is recent

package/content/recipes/verify-onchain.md

@@ -0,0 +1,41 @@
+---
+title: Verify a Proof On-Chain
+prereqs:
+  - contracts-deployed
+  - proof-generated
+  - sepolia-rpc
+estimated-time: 3 min
+---
+
+# Verify a Proof On-Chain
+
+Submit a compliance proof to the ComplianceRegistry contract on Sepolia testnet. The contract performs 14 checks including Groth16 verification, sanctions root validation, and nullifier uniqueness.
+
+## 1. Set environment variables
+
+```bash:run
+export SEPOLIA_RPC_URL="https://rpc.sepolia.org"
+export DEPLOYER_PRIVATE_KEY="YOUR_VASP_WALLET_PRIVATE_KEY"
+export COMPLIANCE_REGISTRY="YOUR_COMPLIANCE_REGISTRY_ADDRESS" # optional if deployments/sepolia.json exists
+export PROOF_PATH="$PWD/../../artifacts/latest_proof.json"
+export TRANSFER_ID="recipe-transfer-001"
+export VASP_DID="did:web:vasp.example.com"
+```
+
+Expected: No output (variables set)
+
+## 2. Submit proof to ComplianceRegistry
+
+```bash:run
+cd packages/contracts && npx hardhat run scripts/verify-onchain.ts --network sepolia
+```
+
+Expected: Transaction hash and `ProofVerified` event emitted with the blinded nullifier
+
+## 3. Confirm the transfer is recorded
+
+```bash:run
+cd packages/contracts && npx hardhat run scripts/check-transfer.ts --network sepolia
+```
+
+Expected: `isVerified` returns `true` for the transfer ID

package/content/recipes/verify-proof.md

@@ -0,0 +1,36 @@
+---
+title: Verify a Proof Off-Chain
+prereqs:
+  - api-running
+  - proof-generated
+estimated-time: 1 min
+---
+
+# Verify a Proof Off-Chain
+
+> **Legacy demo path.** This recipe uses the 16-signal legacy profile (`/proof/generate`, `/proof/verify`). It does not exercise the current `pilot-transfer-v3` workflow; for that, follow the [local acceptance guide](https://github.com/repfigit/clearproof/blob/main/docs/operations/local-pilot-acceptance.md).
+
+Take an existing compliance proof and verify it locally using the API server. This does not interact with any blockchain.
+
+The local API defaults to API-key auth:
+
+```bash:run
+export CLEARPROOF_API_KEY="dev-api-key"
+```
+
+## 1. Verify the proof
+
+```bash:run
+curl -s -X POST http://localhost:8000/proof/verify \
+  -H "X-API-Key: $CLEARPROOF_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"proof_id":"PROOF_ID_FROM_GENERATE","groth16_proof":{"pi_a":["..."],"pi_b":["..."],"pi_c":["..."]},"public_signals":["1","0","..."],"expected_amount_tier":2,"originator_vasp_did":"did:web:vasp.example.com","transfer_timestamp":1711929600}'
+```
+
+Expected: 200 with `valid: true` and `compliance_attestations` showing `is_compliant: true`
+
+The verification checks:
+- Groth16 proof is cryptographically valid against the verification key
+- `is_compliant` signal equals 1
+- Amount tier matches the expected tier
+- Transfer timestamp is reasonable

package/content/signals.yaml

@@ -0,0 +1,128 @@
+signals:
+  - index: 0
+    name: is_compliant
+    type: bit
+    description: 1 for the encoded circuit checks; not a legal compliance determination
+    source: circuits/compliance.circom
+    onChainUsage: Must equal 1 for proof acceptance
+    isOutput: true
+
+  - index: 1
+    name: sar_review_flag
+    type: bit
+    description: Public tier-derived advisory bit; 1 if amount_tier >= 3, not a suspicious-activity determination
+    source: circuits/amount_tier.circom
+    onChainUsage: Emitted as the review bit in the development ProofVerified event
+    isOutput: true
+
+  - index: 2
+    name: sanctions_tree_root
+    type: field
+    description: Merkle root of the supplied sanctions dataset; source completeness and freshness require verification
+    source: circuits/compliance.circom
+    onChainUsage: Checked against SanctionsOracle.currentRoot()
+    isOutput: false
+
+  - index: 3
+    name: issuer_tree_root
+    type: field
+    description: Merkle root of the trusted VASP issuer tree
+    source: circuits/compliance.circom
+    onChainUsage: Checked against VASPRegistry.issuerMerkleRoot()
+    isOutput: false
+
+  - index: 4
+    name: amount_tier
+    type: uint64
+    description: Amount bucket 1 through 4 under the supplied ordered thresholds
+    source: circuits/amount_tier.circom
+    onChainUsage: Used for tier-based compliance rules
+    isOutput: false
+
+  - index: 5
+    name: transfer_timestamp
+    type: uint64
+    description: Unix timestamp of the transfer
+    source: circuits/compliance.circom
+    onChainUsage: Must be <= block.timestamp
+    isOutput: false
+
+  - index: 6
+    name: jurisdiction_code
+    type: uint16
+    description: 16-bit jurisdiction input; integrations must agree on its encoding
+    source: circuits/credential_validity.circom
+    onChainUsage: Used for jurisdiction-specific compliance rules
+    isOutput: false
+
+  - index: 7
+    name: credential_commitment
+    type: field
+    description: Poseidon hash of credential preimage (issuer_did, kyc_tier, sanctions_clear, issued_at, expires_at)
+    source: circuits/credential_validity.circom
+    onChainUsage: Used for credential binding
+    isOutput: false
+
+  - index: 8
+    name: tier2_threshold
+    type: uint64
+    description: Inclusive lower boundary in USD cents for tier 2
+    source: circuits/amount_tier.circom
+    onChainUsage: Jurisdiction-configurable threshold
+    isOutput: false
+
+  - index: 9
+    name: tier3_threshold
+    type: uint64
+    description: Inclusive lower boundary in USD cents for tier 3
+    source: circuits/amount_tier.circom
+    onChainUsage: Jurisdiction-configurable threshold
+    isOutput: false
+
+  - index: 10
+    name: tier4_threshold
+    type: uint64
+    description: Inclusive lower boundary in USD cents for tier 4
+    source: circuits/amount_tier.circom
+    onChainUsage: Jurisdiction-configurable threshold
+    isOutput: false
+
+  - index: 11
+    name: domain_chain_id
+    type: uint256
+    description: Ethereum chain ID (e.g., 1=mainnet, 11155111=Sepolia)
+    source: circuits/compliance.circom
+    onChainUsage: Must equal block.chainid
+    isOutput: false
+
+  - index: 12
+    name: domain_contract_hash
+    type: field
+    description: keccak256 of the encoded ComplianceRegistry address reduced modulo the scalar field
+    source: circuits/compliance.circom
+    onChainUsage: Must equal keccak256(address(this)) % BN128_R
+    isOutput: false
+
+  - index: 13
+    name: transfer_id_hash
+    type: field
+    description: Registry expects keccak256 of encoded transferId reduced modulo the scalar field; API consistency remains open
+    source: circuits/compliance.circom
+    onChainUsage: Checked against transferId by the registry, alongside duplicate-record and nullifier checks
+    isOutput: false
+
+  - index: 14
+    name: credential_nullifier
+    type: field
+    description: Poseidon(credential_commitment, transfer_id_hash) -- one-time-use value stored on-chain
+    source: circuits/compliance.circom
+    onChainUsage: Stored in usedNullifiers mapping, checked for uniqueness
+    isOutput: false
+
+  - index: 15
+    name: proof_expires_at
+    type: uint64
+    description: Unix timestamp after which proof is invalid
+    source: circuits/compliance.circom
+    onChainUsage: Must be >= block.timestamp
+    isOutput: false

package/content/topics/api.md

@@ -0,0 +1,61 @@
+---
+title: API Reference
+category: reference
+order: 5
+cli-topic: api
+---
+
+# API reference
+
+The Python API (FastAPI) is a development component in the source checkout, reviewed September 25, 2026. It is not part of the published npm packages. Use the running application's [local OpenAPI UI](http://localhost:8000/docs) for exact request and response schemas.
+
+Protected routes require the configured authentication. Pilot routes also require an authenticated tenant principal with explicit roles and issuer scope; there is no implicit administrator override. PostgreSQL, storage keys and tenant trust configuration are required for the pilot routes. See [deployment](/docs/deployment).
+
+## Pilot routes
+
+| Route | Purpose |
+| --- | --- |
+| `POST /pilot/credential/enroll` | Enroll a credential with the holder wallet's signed consent |
+| `POST /pilot/credential/revoke` | Revoke an enrolled credential permanently |
+| `POST /pilot/policy/approve` | Approve a reviewed policy version (activation is a separate step) |
+| `POST /pilot/policy/diff` | Compare a proposed policy against supplied cases |
+| `POST /pilot/policy/diff/stored` | Compare a proposed policy against retained evidence |
+| `POST /pilot/proof/inspect` | Read-only inspection of a current proof against current state; never consumes |
+| `POST /pilot/proof/evaluate` | Explained policy evaluation of a current proof |
+| `POST /pilot/proof/authorize` | Consume one authorization after an `ALLOW`, sealing information to the recipient |
+| `POST /pilot/proof/observe` | Record a non-authorizing observation |
+| `POST /pilot/proof/observations/read`, `/list`, `/report` | Read observations and cohort reports |
+| `POST /pilot/events/ingest` | Ingest signed custody, counterparty or chain events |
+| `POST /pilot/events/investigate` | Transfer investigation timeline |
+| `POST /pilot/events/queue` | Paginated investigation queue |
+| `POST /pilot/fireblocks/{integration_id}` | Verify and retain a signed Fireblocks notification from a tenant relay |
+| `GET /pilot/usage` | Retained record counters (not billable charges) |
+
+## Wallet ownership extension
+
+| Route | Purpose |
+| --- | --- |
+| `POST /wallet/ownership/challenge` | Five-minute EOA signing challenge for an enrolled credential |
+| `POST /wallet/ownership/verify` | Verify the EIP-191 signature; issue a 24-hour attestation |
+| `GET /wallet/ownership/attestations/{attestation_id}` | Current attestation eligibility |
+| `POST /wallet/ownership/revoke` | Revoke an attestation |
+| `POST /wallet/ownership/credential` | Issue the optional versioned extension credential |
+
+The extension circuit is staged; no deployed verifier accepts it. See the [wallet ownership guide](https://github.com/repfigit/clearproof/blob/main/docs/internal/WALLET_OWNERSHIP.md).
+
+## Shared and legacy routes
+
+| Route | Purpose |
+| --- | --- |
+| `GET /health` | Process liveness, not pilot readiness |
+| `GET /metrics` | Operational counters |
+| `GET /.well-known/clearproof.json` | Discovery metadata: exact `did:web` identity and HPKE key |
+| `GET /auth/nonce`, `POST /auth/verify` | SIWE challenge and verification |
+| `POST /credential/issue`, `POST /credential/revoke` | Legacy development credentials |
+| `POST /proof/generate`, `POST /proof/verify` | Legacy 16-signal demo proof generation and verification |
+
+The legacy routes serve the demo profile. A legacy proof is never current pilot authorization.
+
+## Limits
+
+A successful response is not legal compliance, settlement or a live counterparty's acceptance. Inspection and observation results never authorize a transfer. Only `/pilot/proof/authorize` consumes an authorization, and only after an `ALLOW`. See [architecture](/docs/architecture) and [security](/docs/security).

package/content/topics/architecture.md

@@ -0,0 +1,50 @@
+---
+title: Architecture
+category: concepts
+order: 2
+cli-topic: architecture
+---
+
+# Architecture
+
+clearproof combines a Python API with PostgreSQL storage, Circom circuits, TypeScript proof tooling and Solidity contracts. The pilot workflow below is implemented in the source checkout and tested locally with synthetic data and real development proofs. It has not been independently audited or deployed to production.
+
+## Pilot workflow
+
+```mermaid
+flowchart LR
+    Enroll[Wallet-signed credential enrollment] --> Roots[Signed issuance, issuer and sanctions roots]
+    Roots --> Prove[pilot-transfer-v3 Groth16 proof]
+    Policy[Reviewed, active policy] --> Authorize
+    Prove --> Authorize[Authorization service: current state + policy ALLOW]
+    Authorize --> Seal[Information sealed to recipient's HPKE key]
+    Authorize --> Receipt[Consumed receipt in PostgreSQL]
+    Receipt --> Mirror[Optional on-chain receipt mirror]
+    Seal --> Peer[Counterparty verifies and responds]
+    Receipt --> Evidence[Encrypted evidence export for offline review]
+```
+
+## Responsibilities
+
+The **circuit** proves the transfer projection, credential, issuer membership and sanctions non-membership relationships. See [circuits](/docs/circuits).
+
+The **authorization service** checks everything the circuit cannot: the current roots and their signatures, credential revocation, the active policy, signed valuation and external facts, and the real proof pairing. Only a policy `ALLOW` can consume an authorization. `DENY`, `REVIEW`, `INDETERMINATE`, invalid pairing and untrusted inputs cannot. On `ALLOW` it seals the approved transfer information to a trusted recipient key and records the evidence, the receipt and the consumed nullifier in one PostgreSQL transaction.
+
+The **contract** (`PilotCurrentRegistry`) mirrors receipts that were already consumed, under checkpoints published by a trusted publisher. It checks the chain ID, its own address and the expiry, but it cannot create an authorization or detect a publisher that lies about private records.
+
+Read-only inspection and observation never consume an authorization.
+
+## Around the proof
+
+- **Policy review:** explained outcomes, stored comparisons of a proposed policy against past cases, and separate approval and activation history.
+- **Investigations:** read-only timelines that join policy, counterparty, custody, chain and evidence events, keeping duplicates, ordering and unresolved conflicts visible.
+- **Historical evidence:** recipient-encrypted exports that an independent reviewer can check offline after the proof expires, using separately configured trust.
+- **Observation mode:** runs alongside an existing workflow and records explained outcomes without authorizing anything.
+
+## Legacy path
+
+The original `compliance.circom` profile, `/proof/generate`, `/proof/verify`, the `ComplianceRegistry` contract and the hybrid payload remain as a separate demo and parity path. Their proofs are not current pilot authorization.
+
+## Not yet done
+
+Live provider and counterparty interoperability, remote TRP/TRISA conformance, re-screening from an upstream feed, managed distribution, an independent audit and a production setup are separate follow-on gates. See [project status](/docs/status).

package/content/topics/circuits.md

@@ -0,0 +1,66 @@
+---
+title: Circuits
+category: concepts
+order: 3
+cli-topic: circuits
+---
+
+# Circuits
+
+clearproof uses Circom and Groth16 over BN254. CI compiles with circom **2.2.2**. These are unaudited development components with development-only proving keys. See [security](/docs/security).
+
+There are two proof profiles. **Never select a profile by its signal count.**
+
+| Profile | Circuit | Public signals | Status |
+| --- | --- | --- | --- |
+| `pilot-transfer-v3` | `pilot_compliance.circom` | 8 | **Current** pilot profile |
+| `pilot-transfer-v2` / `v1` | same circuit, earlier tree depths or binding | 8 | Historical; current checks reject them |
+| Legacy | `compliance.circom` | 16 | Separate demo and parity path; never current pilot authorization |
+
+## Current profile: pilot-transfer-v3
+
+The circuit is instantiated as `PilotCompliance(32, 20, 20)`: an issuance tree of depth 32 (about 4.3 billion credentials per issuer), an authorized-issuer tree of depth 20 and a sanctions tree of depth 20 (1,048,574 addresses plus two boundary leaves). It has 95,408 constraints and needs `2^17` powers-of-tau parameters. The authoritative statement is [`specs/pilot-transfer-v3.md`](https://github.com/repfigit/clearproof/blob/main/specs/pilot-transfer-v3.md).
+
+```text
+PilotCompliance(32, 20, 20)
+├── PilotTransferProjection   48 private transfer fields, exact valuation, private tier
+├── PilotCredentialValidity   credential, holder secret, issuance and issuer membership
+└── PilotSanctionsGap × 2     raw-address non-membership for originator and beneficiary
+```
+
+### Public signals
+
+| Index | Signal | What the circuit enforces |
+| --- | --- | --- |
+| 0 | `projection_commitment` | Commits to the private transfer projection, the exact credential and the issuance root |
+| 1 | `authorized_issuer_root` | The credential's issuer is a member of this tree |
+| 2 | `sanctions_root` | Neither wallet is in this sorted address tree |
+| 3 | `authorization_nullifier` | Derived from the holder secret and the transfer's authorization scope |
+| 4 | `evaluated_at` | Evaluation time; the credential must be valid at this time |
+| 5 | `proof_expires_at` | Later than `evaluated_at`, and no later than the transfer expiry, the credential expiry or `evaluated_at` + 300 seconds |
+| 6 | `domain_chain_id` | Equals the private deployment field only; the registry checks the real chain |
+| 7 | `domain_registry` | Equals the private deployment field only; the registry checks its own address |
+
+The amount, tier, wallets, jurisdiction, participants and credential fields are **private**. There is no public amount tier or review flag. A verifier must reconstruct signal 0 from its own authenticated records; a proof that verifies cryptographically says nothing about which transfer it covers until that check passes.
+
+### What each part checks
+
+- **Transfer projection.** All 48 fields are range-checked. Time ordering (observation ≤ creation ≤ evaluation < transfer expiry ≤ quote expiry), maximum age, decimals and nonzero identities are enforced. The amount is converted to USD cents with exact integer arithmetic, and the tier is derived privately from the policy thresholds.
+- **Credential.** The credential commitment must be a member of the issuance root, and the issuer's leaf must be a member of the authorized-issuer root. The holder must know the secret behind the credential's holder commitment. Tenant, subject wallet and jurisdiction must match the transfer.
+- **Sanctions.** A sorted-tree gap proof shows each raw 160-bit wallet address lies strictly between two adjacent leaves. Adjacency is derived from the Merkle path bits, and all compared values are range-checked.
+- **Replay and expiry.** The nullifier stays the same for a given holder and transfer scope, so a replacement proof cannot be spent twice. The five-minute expiry bound is enforced in the circuit.
+
+Some acceptance properties live outside the circuit. The authorization service checks current roots, revocation, policy and signed facts, and consumes the nullifier in PostgreSQL. `PilotCurrentRegistry` checks the chain ID, its own address and the expiry against published statements. See [architecture](/docs/architecture).
+
+## Legacy profile
+
+`ComplianceProof(20, 10)` in `compliance.circom` publishes 16 values, including `is_compliant`, a tier-derived `sar_review_flag`, the amount tier, the jurisdiction and the tier thresholds. It remains a demo and parity path with its own verifier, SDK function and tests. Legacy proofs are never current pilot authorization.
+
+## Building development artifacts
+
+```bash
+.venv/bin/python scripts/test_development_circuits.py /absolute/new-directory \
+  --prepared-ptau /absolute/ppot_0080_17.ptau
+```
+
+This compiles both profiles, creates explicitly unapproved development keys and runs real proof round trips. CI uses the SHA-256-pinned [PSE perpetual powers of tau](https://pse-trusted-setup-ppot.s3.eu-central-1.amazonaws.com/pot28_0080/ppot_0080_17.ptau) file (`f807e065…3a367c`). Without `--prepared-ptau`, a local single-party `2^17` setup is generated, which can take over an hour. Development keys are not production keys; the production setup path is still an open decision (ADR 0004).

package/content/topics/contracts.md

@@ -0,0 +1,60 @@
+---
+title: Smart Contracts
+category: concepts
+order: 4
+cli-topic: contracts
+---
+
+# Smart Contracts
+
+The project includes two sets of EVM contracts. The **pilot contracts** verify and mirror current `pilot-transfer-v3` proofs; they exist in source and are tested locally, but are **not deployed** to any shared network. The **legacy contracts** serve the 16-signal demo profile; the Sepolia addresses below are historical testnet records of those. None of these contracts has been independently audited.
+
+## Pilot contracts (source, not deployed)
+
+**PilotGroth16Verifier** checks the eight-signal pilot proof against a verification key and artifact manifest digest fixed at construction. It reports `proofProfile` as `pilot-transfer-v3` and `assurance` as `development-unapproved`. Pairing alone does not reconstruct the transfer statement, check current state or consume a nullifier.
+
+**PilotCurrentRegistry** publishes tenant checkpoints (revisioned heads for issuance, issuers, sanctions, credential, policy, valuation, participants and authorization) and statement bindings from one assigned publisher per tenant. `inspect` is a read-only call that checks a proof against a published statement, including the chain ID, the registry's own address and the expiry. It then mirrors receipts that PostgreSQL has already consumed. It cannot create an authorization, and it cannot detect a publisher that lies about private records. See the [registry trust boundary](https://github.com/repfigit/clearproof/blob/main/docs/internal/PILOT_CURRENT_REGISTRY.md).
+
+## Legacy contracts: recorded Sepolia deployments
+
+The July 20, 2026 manifest records these addresses for the legacy demo profile. Bytecode was present at all five on September 5, 2026. This check does not establish equivalence between every current source change and deployed bytecode.
+
+| Contract | Sepolia address |
+| --- | --- |
+| Groth16Verifier | [0x6F8e6f64C5601Eb25716f45C78c9B7C9c0bde8EA](https://sepolia.etherscan.io/address/0x6F8e6f64C5601Eb25716f45C78c9B7C9c0bde8EA#code) |
+| VASPRegistry | [0x99FE2813FD9D66Df43d1ce37d39341F5A7a557F0](https://sepolia.etherscan.io/address/0x99FE2813FD9D66Df43d1ce37d39341F5A7a557F0#code) |
+| SanctionsOracle | [0x2822db7e67E1152a9cC81E44Df2182CA4662c7a2](https://sepolia.etherscan.io/address/0x2822db7e67E1152a9cC81E44Df2182CA4662c7a2#code) |
+| ComplianceRegistry | [0x941F7f188843279C03D1960821B4332A40e806F7](https://sepolia.etherscan.io/address/0x941F7f188843279C03D1960821B4332A40e806F7#code) |
+| SanctionsRootRelay | [0x911d8244F3b63a40040862dB0CC285A753036F87](https://sepolia.etherscan.io/address/0x911d8244F3b63a40040862dB0CC285A753036F87#code) |
+
+## Groth16Verifier
+
+Checks cryptographic proof validity against its verification key. That check alone does not establish source authenticity, current state, legal compliance or authorization to execute a transfer. Verifiers and artifacts must match the intended proof version.
+
+## ComplianceRegistry
+
+The development registry coordinates proof acceptance with other contracts. Its source checks duplicate transfer records, dependency pause/freshness, active VASP and submitting wallet, chain/contract domain, expiry and future timestamps, sanctions/issuer roots, transfer reference, configured thresholds, revocation and nullifier use. The current development code routes cryptographic verification through a versioned verifier router and configured selector.
+
+Successful acceptance records the proof and consumes a nullifier. Read-only cryptographic verification in an SDK is a different operation. A recorded proof is not itself evidence of successful transfer settlement.
+
+## VASPRegistry
+
+Stores registered VASPs, authorized submitting wallets, jurisdictions, discovery endpoints and the issuer Merkle root. Registration and directory metadata must be interpreted under an explicit trust policy; they do not independently establish licensing or factual credential validity.
+
+## SanctionsOracle
+
+Stores a current root, update time, leaf count and bounded history. Controls include a one-hour update cooldown, a configured staleness window and a leaf-count floor. The history is a ring of up to 1,000 records, not a complete long-term evidence archive.
+
+## SanctionsRootRelay
+
+Forwards authorized root updates to the oracle. A local tree rebuild is not evidence that every intended chain received its update.
+
+## Development
+
+```bash
+cd packages/contracts
+npx hardhat compile
+npx hardhat test
+```
+
+Use the ABI and deployment configuration for your exact target. Existing testnet addresses must not be represented as an independently audited production release.

package/content/topics/gdpr.md

@@ -0,0 +1,36 @@
+---
+title: GDPR Data-Minimization
+category: concepts
+order: 8
+cli-topic: gdpr
+---
+
+# Privacy and data minimization
+
+clearproof explores reducing disclosure by separating verification of specific predicates from encrypted exchange of required personal information. This is an architectural objective, not a GDPR exemption or a compliance certification.
+
+## Encryption and proofs have different roles
+
+A proof can establish its encoded statement without exposing every private witness value. Encrypted personal information can travel to an authorized recipient. The recipient may still need to obtain, verify and retain information under applicable requirements.
+
+For covered EU crypto transfers, the Transfer of Funds Regulation sets information and missing-information obligations. An amount tier does not define a blanket exemption from those obligations. [EU Regulation 2023/1113, Articles 14–17](https://eur-lex.europa.eu/eli/reg/2023/1113/oj/eng)
+
+Encrypted personal data remains personal data. Keeping it off-chain and limiting disclosure must be considered alongside purpose, access, retention and governance. [EDPB Guidelines 02/2025, final version 2, July 7, 2026](https://www.edpb.europa.eu/system/files/2026-07/edpb_guidelines_202502_blockchain_v2_en.pdf)
+
+## What remains visible
+
+A current `pilot-transfer-v3` proof publishes eight values: a commitment to the transfer and credential, the authorized-issuer and sanctions roots, a nullifier, the evaluation and expiry times, and the chain and registry it is bound to. The amount, tier, wallets, jurisdiction and participants stay private. See [circuits](/docs/circuits).
+
+Commitments, nullifiers and timestamps are still not automatically anonymous. Linking them to other records, on-chain transactions or retained evidence can identify or correlate people. The legacy 16-signal demo circuit publishes more, including an amount tier, jurisdiction and a tier-derived review flag; do not use it where that metadata matters.
+
+## Deployment questions
+
+- Which facts actually need a private predicate proof?
+- Which recipient is authorized to receive each piece of information?
+- How are credentials, source data and recipient keys authenticated?
+- What can repeated commitments, timestamps and status checks reveal?
+- How are retention, access, deletion, incident handling and evidence export implemented?
+
+Measure disclosure and operational data copying in the intended deployment. Neither encryption, ZK, nor explorer verification independently establishes compliance.
+
+Read [current assurance limits](/docs/security).