From a5582a1bad8525648b46dfaffea8fb6d636b8267 Mon Sep 17 00:00:00 2001 From: Meyanis95 Date: Thu, 23 Apr 2026 16:04:53 +0200 Subject: [PATCH 01/10] feat(patterns): migrate batch 1 (30 cards) to schema v2 (#150) --- patterns/pattern-co-snark.md | 115 +++++--- patterns/pattern-commit-and-prove.md | 105 ++++--- patterns/pattern-compliance-monitoring.md | 162 +++++------ .../pattern-cross-chain-privacy-bridge.md | 189 ++++++------ ...pattern-crypto-registry-bridge-ewpg-eas.md | 105 ++++--- patterns/pattern-dvp-erc7573.md | 176 ++++++------ patterns/pattern-eil.md | 127 ++++---- patterns/pattern-erc3643-rwa.md | 123 ++++---- patterns/pattern-focil-eip7805.md | 130 +++++---- patterns/pattern-forced-withdrawal.md | 180 ++++++------ .../pattern-hybrid-public-private-modes.md | 153 +++++----- patterns/pattern-icma-bdt-data-model.md | 95 ++++-- .../pattern-l2-encrypted-offchain-audit.md | 125 +++++--- patterns/pattern-l2-privacy-evaluation.md | 272 ++++++++---------- patterns/pattern-lean-ethereum.md | 147 +++++----- patterns/pattern-mixnet-anonymity.md | 131 +++++---- patterns/pattern-modular-privacy-stack.md | 185 ++++++------ patterns/pattern-mpc-custody.md | 140 ++++++--- .../pattern-native-account-abstraction.md | 108 ++++--- patterns/pattern-network-anonymity.md | 145 +++++----- patterns/pattern-noir-private-contracts.md | 190 ++++++------ patterns/pattern-oif.md | 119 +++++--- patterns/pattern-onion-routing.md | 138 +++++---- ...ttern-origin-locked-confidential-ledger.md | 140 +++++---- ...rn-permissioned-ledger-interoperability.md | 134 ++++++--- patterns/pattern-permissionless-spend-auth.md | 137 +++++---- patterns/pattern-plasma-stateless-privacy.md | 148 ++++++---- .../pattern-pretrade-privacy-encryption.md | 141 ++++++--- patterns/pattern-privacy-l2s.md | 149 +++++++--- patterns/pattern-private-iso20022.md | 165 +++++------ patterns/pattern-shielding.md | 124 +++++--- 31 files changed, 2533 insertions(+), 1965 deletions(-) diff --git a/patterns/pattern-co-snark.md b/patterns/pattern-co-snark.md index 3c29fb3..dbfe6c7 100644 --- a/patterns/pattern-co-snark.md +++ b/patterns/pattern-co-snark.md @@ -1,64 +1,103 @@ --- -title: "Pattern: co-SNARKs (Collaborative Proving)" +title: "Pattern: Delegated Proving (co-SNARKs)" status: draft -maturity: PoC +maturity: testnet +type: standard layer: hybrid -privacy_goal: Enable multi-party ZK proving over distributed private inputs without disclosure -assumptions: co-SNARK protocol infrastructure, MPC network coordination, honest majority among proving parties -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-23 + works-best-when: - - Multiple parties each hold sensitive data or models, and need to jointly prove compliance, settlement, or state updates without revealing inputs. + - A user or institution lacks the compute, memory, or battery to generate a ZK proof client-side and wants to offload the work without disclosing the witness. + - The delegatee set can be run by independent operators so no single party sees the full witness. avoid-when: - - A single party can generate the proof without external data. -dependencies: - - co-SNARK protocols (e.g. TACEO) + - Client-side proving is feasible and low-latency is critical. + - Only one proving node is available (no honest-majority distribution possible); use a TEE-based prover instead. + context: both +context_differentiation: + i2i: "Between institutions, delegated proving is typically contracted between known parties with SLAs and legal recourse. The prover set can be small and stable. Honest-majority risk is mitigated by bilateral agreements and audit logs." + i2u: "For users, the prover set must be permissionless or at least operator-diverse so that no coalition can recover the witness. Economic bonding with slashing and publicly auditable proving logs protect against collusion. A user has no recourse if the prover set silently leaks their witness." + crops_profile: cr: medium - os: yes - privacy: full - security: medium + o: yes + p: full + s: medium + +crops_context: + cr: "Reaches `high` when the prover network is permissionless and bond-backed with slashing for Byzantine behaviour. Drops to `low` when a single proving service controls the pipeline." + o: "Proving-framework implementations are published under permissive licenses; production deployments may bundle proprietary orchestration." + p: "The witness stays hidden from each individual prover and from the verifier. Metadata about who requested a proof, when, and against which circuit can still leak." + s: "Rides on the soundness of the underlying SNARK and the honest-majority assumption of the MPC protocol. Trusted-setup requirements inherit from the SNARK (Groth16 needs per-circuit setup; PLONK/KZG uses universal setup)." + +post_quantum: + risk: high + vector: "Pairing-based SNARKs (Groth16, PLONK/KZG) broken by CRQC. MPC communication inherits the underlying key-exchange assumptions." + mitigation: "co-STARK alternatives with hash-based commitments. See [Post-Quantum Threats](../domains/post-quantum.md)." + +standards: [] + +related_patterns: + composes_with: [pattern-shielding, pattern-safe-proof-delegation, pattern-permissionless-spend-auth] + alternative_to: [pattern-tee-based-privacy] + see_also: [pattern-private-shared-state-cosnark, pattern-zk-proof-systems] + +open_source_implementations: + - url: https://github.com/TaceoLabs/co-snarks + description: "co-SNARK proving framework supporting Groth16 and PLONK (research/testnet)" + language: "Rust" --- ## Intent -Enable **collaborative zero-knowledge proving** over distributed private inputs. -Co-SNARKs let institutions, investors, or service providers jointly prove properties without disclosing raw data, and optionally commit the result as an **onchain state update**. +Offload ZK proof generation to a distributed prover network without revealing the witness. The user secret-shares their witness across several proving nodes; the nodes jointly run an MPC protocol to compute a single SNARK proof; no individual node ever reconstructs the full witness. The resulting proof is identical to one produced client-side and is verified on-chain or off-chain with no changes on the verifier side. + +This pattern covers **delegated proving for a single prover's witness**. For multi-party joint computation over shared secret inputs (e.g. a consortium ledger), see `pattern-private-shared-state-cosnark`. + +## Components + +- **User or application** holds the witness and wants a proof generated without exposing the witness. +- **Share-distribution layer** splits the witness using secret-sharing (additive or Shamir) and routes shares to proving nodes. +- **Distributed prover network** runs the MPC protocol to jointly compute the SNARK. Each node sees only its share. +- **Coordinator** sequences MPC rounds and assembles the final proof. Can be one of the proving nodes or a separate role. +- **Verifier** checks the final proof exactly as it would check a client-side SNARK. No changes on the verification side. + +## Protocol -## Ingredients +1. [user] Secret-share the witness across N proving nodes. +2. [prover] Proving nodes jointly execute the co-SNARK MPC protocol, exchanging shares across multiple rounds to compute witness polynomials and commitments. +3. [prover] The coordinator assembles the final proof from the MPC output. +4. [user] Receive the assembled proof from the coordinator. +5. [contract] A verifier contract (or off-chain verifier) checks the proof against the public statement. -- **Cryptography**: co-SNARK ([Collaborative zk-SNARKs](https://eprint.iacr.org/2021/1530.pdf), e.g. TACEO) -- **Infra**: Offchain MPC network, optional L1/L2 onchain commitments -- **Standards**: Can tie into ERC-3643 (identity claims), [attestations](pattern-verifiable-attestation.md), ERC-7573 for settlement +## Guarantees & threat model -## Protocol (concise) +Guarantees: -1. Each participant provides private inputs (e.g. compliance model, investor data, transaction intent). -2. Parties jointly run a co-SNARK protocol to produce a single proof. -3. Proof can be verified by a regulator, counterparty, or onchain contract. -4. Can maintain a **shared private state** in a 3PC setting, committing roots onchain. +- The witness stays hidden from every individual prover and from the verifier. +- Verification cost is identical to a client-side SNARK for the same circuit. +- Preserves trade secrets, user balances, or model weights under honest-majority assumptions. -## Guarantees +Threat model: -- Prove statements across multiple private data silos without disclosure. -- Preserve trade secrets and client privacy. -- Anchor proofs or state commitments onchain if required. +- Soundness of the underlying SNARK, including any trusted-setup ceremony. +- Honest-majority assumption across proving nodes. A colluding majority can recover the witness and, in some constructions, forge proofs. +- Non-censoring coordinator. A malicious coordinator can refuse to finalize or selectively drop requests. +- Authenticated and confidential channels between nodes. Metadata about participation and timing is out of scope. ## Trade-offs -- Heavy communication and coordination overhead (scales with number of parties). -- Requires new infra (MPC nodes, co-prover setup). -- Delegated proving possible, but introduces new trust assumptions. -- Honest-majority assumption: if a majority of proving parties collude, proof integrity is compromised. -- **CROPS context (both)**: CR could reach `high` if economic incentives like bond-backed provers with slashing are added for Byzantine behavior. Security improves to `high` by replacing trusted setup with a universal setup. In I2I settings, multi-party proving typically involves known counterparties with existing legal agreements, so the honest-majority assumption carries lower practical risk. In I2U settings, end-users contributing private inputs face greater exposure if the proving coalition is dominated by institutional actors. -- **Post-quantum exposure**: co-SNARK (Groth16-based) relies on pairings broken by CRQC. Mitigation: co-STARK alternatives. See [Post-Quantum Threats](../domains/post-quantum.md). +- Heavy communication overhead. Round count and bandwidth scale with both the number of provers and circuit size. +- New infrastructure requirements: MPC nodes, share routing, key management. +- Liveness depends on all designated nodes remaining online through the proving session. Dropouts typically force a restart. +- Latency is higher than client-side proving because of MPC round trips; not suitable for sub-second proving budgets. -## Examples +## Example -- **Compliance**: Bank + investor prove AML/KYC checks without sharing raw data. -- **Shared state**: Consortium of custodians maintain a private ledger offchain, publish commitment + co-SNARK consistency proof to L1. -- **Settlement**: Cross-institution cash/asset swap where each side’s balance sheet remains private. +- A user holds a shielded balance and wants to prove a spend on a mobile device. The wallet secret-shares the spending witness across three independent proving operators. The operators jointly produce a Groth16 proof. None of them sees the balance or the spend amount. The user submits the proof to the shielded pool contract. ## See also -- TACEO co-SNARK: https://core.taceo.io/articles/mpc-kyc/ +- [Collaborative zk-SNARKs (Ozdemir & Boneh, 2021)](https://eprint.iacr.org/2021/1530.pdf) +- [TACEO private proof delegation](https://core.taceo.io/articles/private-proof-delegation/) +- [TACEO Merces vendor page](../vendors/taceo-merces.md) diff --git a/patterns/pattern-commit-and-prove.md b/patterns/pattern-commit-and-prove.md index 4d32d32..b257a84 100644 --- a/patterns/pattern-commit-and-prove.md +++ b/patterns/pattern-commit-and-prove.md @@ -1,68 +1,99 @@ --- title: "Pattern: Commit-and-Prove Fallback" status: draft -maturity: pilot +maturity: testnet +type: standard layer: hybrid -privacy_goal: Achieve conditional atomicity via shared commitments across chains -assumptions: On-chain commitment contracts, coordination runbook, both parties accept coordination overhead -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 + works-best-when: - Both parties accept extra coordination overhead. - Circuit complexity or infra constraints block other patterns. avoid-when: - Near-real-time settlement is required (added latency). -dependencies: - - ERC-7573, EAS (commit attestations) + context: both +context_differentiation: + i2i: "Both counterparties typically have legal recourse if one leg finalizes and the other does not, reducing the practical impact of weak atomicity. Commitments can be backed by bilateral netting agreements. Irreversibility of a one-sided settlement is manageable through off-chain remedies." + i2u: "End-users lack equivalent legal remedies for a stuck half-settled trade. Protocol-enforced timelocks with forced-refund paths become critical, and the user must be able to unilaterally reclaim funds on any chain without operator cooperation." + crops_profile: cr: medium - os: partial - privacy: none - security: medium + o: partial + p: none + s: medium + +crops_context: + cr: "Reaches `high` with protocol-enforced timelocks and forced-withdrawal paths on both chains, removing any operator ability to strand a leg. Drops to `low` if one chain is an operator-controlled rollup without exit proofs." + o: "Coordination logic is often bespoke and may be proprietary. Improves to `yes` when the runbook and timeout contracts are open-sourced under a permissive license." + p: "No amount or counterparty privacy at the base layer. The shared commitment `C` creates a meta-linkage between the two legs observable to anyone watching both chains. Can reach `partial` by proving knowledge of `C`'s pre-image via ZK instead of revealing `C`." + s: "Rides on the security of each chain's settlement and the commitment scheme's binding property. Honest counterparty behavior is required to post both legs; dishonesty is mitigated through timeout refunds but the mitigation is economic, not cryptographic." + +post_quantum: + risk: medium + vector: "Commitment schemes built on discrete log (Pedersen) broken by CRQC. Signatures on settlement transactions inherit the host chain's signature assumptions." + mitigation: "Hash-based commitments (SHA-2, SHA-3) resist CRQC. See [Post-Quantum Threats](../domains/post-quantum.md)." + +standards: [ERC-20, EIP-7573] + +related_patterns: + alternative_to: [pattern-dvp-erc7573] + composes_with: [pattern-verifiable-attestation, pattern-forced-withdrawal] + see_also: [pattern-cross-chain-privacy-bridge] + +open_source_implementations: [] --- ## Intent -Fallback atomic DvP by both parties posting commitments to shared secret `C=Com(w)`; each leg verified against `C` before settlement. +Coordinate a cross-chain settlement by having both parties post commitments to a shared secret witness `C = Com(w)`. Each leg of the trade references `C`, so auditors can link the two legs after the fact and each chain can verify its side against the same binding commitment. Atomicity is conditional: both legs settle independently, but neither can claim to have settled against a different commitment than the other. + +## Components + +- **Commitment scheme** (hash-based or Pedersen) binds the shared witness `w` to a public value `C` that both parties post. +- **Per-chain settlement contracts** accept a settlement transaction that references `C` and verifies local conditions (asset transfer, payment). +- **Coordination layer** (off-chain) holds the pre-image `w`, sequences the two legs, and drives retry logic. +- **Timeout and refund paths** on each chain allow a counterparty to reclaim funds if the other leg never posts within a deadline. +- **Attestation log** (optional) records the commitments and settlement events for later audit. + +## Protocol -## Ingredients +1. [user] Both parties agree off-chain on trade terms and jointly generate witness `w`. Each party computes `C = Com(w)`. +2. [user] Party A posts the asset leg on Chain A with settlement bound to `C`. +3. [user] Party B posts the cash leg on Chain B with settlement bound to `C`. +4. [contract] Each chain locally verifies its leg against `C` and finalizes if valid. +5. [contract] If one leg's timeout expires without a matching counter-leg, the affected party invokes the refund path to reclaim their assets. +6. [auditor] A later auditor can correlate the two legs via the shared `C` without needing to coordinate the chains in real time. -- **Standards**: ERC-7573, ERC-20 -- **Infra**: On-chain commitment contracts -- **Off-chain**: Coordination runbook +## Guarantees & threat model -## Protocol (concise) +Guarantees: -1. Both parties commit to secret witness `w` via `C=Com(w)`. -2. Party A posts proof bound to `C` on Chain A. -3. Party B posts proof bound to `C` on Chain B. -4. Each chain verifies proofs locally; if both legs are posted and valid, settlement is effectively atomic. -5. If only one leg is posted, the other remains unsettled — unless additional mechanisms (time-locks, refund paths, relayers) are layered in. +- Both legs are cryptographically bound to the same witness, so neither party can claim settlement against a different trade. +- Each chain's finalization is independent, providing conditional atomicity: if both legs post before their timeouts, the trade is effectively atomic. +- Auditable commitments support post-hoc reconciliation. -## Guarantees +Threat model: -- Conditional atomicity only: both legs reference the same `C`, but each chain finalizes independently. - - If one leg finalizes and the other fails to appear, there is no cross-chain revert. - - True all-or-nothing atomicity requires additional mechanisms (zk-SPV, single-domain execution). -- Minimal infra requirements. -- Provides auditable commitments. +- Soundness of the commitment scheme (binding property). A broken commitment allows a party to claim a different `w` than was agreed. +- Non-censoring sequencer or validator set on both host chains during the settlement window. A censored leg triggers the refund path but breaks liveness. +- Honest off-chain coordination is assumed. Both parties must actually post their legs; dishonesty is mitigated only by timeouts, not by cross-chain enforcement. +- No cross-chain revert: once one leg finalizes, it cannot be rolled back. True all-or-nothing atomicity is out of scope and requires a different pattern. ## Trade-offs -- Slower, requires coordination & retries. -- Commitment reveals meta-linkage. -- No built-in privacy of amounts. -- Irreversibility: once one chain finalizes, that leg cannot be rolled back. -- Refunds/time-locks are required to mitigate stuck or one-sided settlements. -- **CROPS context (both)**: CR could reach `high` if protocol-enforced timelocks with forced-withdrawal are added on both chains. OS improves to `yes` by open-sourcing coordination logic under a permissive license. Privacy could reach `full` by proving knowledge of the commitment pre-image via ZKP without revealing it. Security improves to `high` by replacing irreversibility risk with guaranteed revert paths and verifiable finality proofs. In I2I settings, both counterparties typically have legal recourse if one leg fails, reducing the practical impact of weak CR. In I2U settings, end-users lack equivalent remedies, making protocol-enforced timelocks and revert paths more critical. +- Slower than single-chain settlement; requires round-trips and retries. +- Meta-linkage risk: the shared `C` is visible on both chains and correlates otherwise-independent flows. +- No built-in amount privacy. Each chain's leg reveals whatever the host protocol exposes. +- Refunds require reliable timeout handling on both sides; operational failures can strand funds until manual intervention. ## Example -- Bank A commits to selling €5m bond, Bank B commits to paying EURC. -- Both commit to shared `C`. -- Each leg verifies settlement bound to `C`; both finalize if valid. +- Two institutions agree off-chain on a bond-for-stablecoin trade and jointly generate witness `w`. +- The asset issuer locks the bond on the issuance chain with settlement bound to `C = Com(w)`. +- The buyer locks the stablecoin on the payment chain with settlement bound to the same `C`. +- Both legs finalize independently within their timeout windows. An auditor later correlates the two legs via `C`. ## See also -- pattern-dvp-erc7573.md -- pattern-l1-zk-commitment-pool.md +- [EIP-7573 specification](https://ercs.ethereum.org/ERCS/erc-7573) diff --git a/patterns/pattern-compliance-monitoring.md b/patterns/pattern-compliance-monitoring.md index 7bbc219..de4df09 100644 --- a/patterns/pattern-compliance-monitoring.md +++ b/patterns/pattern-compliance-monitoring.md @@ -1,116 +1,110 @@ --- title: "Pattern: Compliance Monitoring" status: draft -maturity: pilot +maturity: testnet +type: standard layer: hybrid -privacy_goal: Screen transactions for regulatory compliance while preserving privacy through selective disclosure -assumptions: Compliance oracle or screening service, threshold-based alerting, regulatory disclosure infrastructure -last_reviewed: 2026-02-03 +last_reviewed: 2026-04-22 + works-best-when: - - Institution must monitor transactions for AML/sanctions compliance - - Privacy is required but regulators need audit capability - - Real-time screening is mandatory before settlement + - Institution must monitor transactions for AML or sanctions compliance. + - Privacy is required but regulators need audit capability. + - Real-time screening is mandatory before settlement. avoid-when: - - Full transparency is acceptable (no privacy requirement) - - Jurisdiction has no transaction monitoring requirements -dependencies: [EAS, threshold-KMS, compliance-oracle] + - Full transparency is acceptable (no privacy requirement). + - Jurisdiction has no transaction monitoring requirements. + context: both +context_differentiation: + i2i: "Counterparties may accept a single compliance oracle operated by a trusted consortium member or shared service. Bilateral contracts govern screening rules and dispute handling. Appeals are resolved through existing institutional channels." + i2u: "End-users have no visibility into oracle decisions and no direct recourse if flagged incorrectly. Threshold consensus across independent oracle operators, transparent appeal processes, and ZK-based screening that hides transaction details from individual operators become essential." + crops_profile: cr: none - os: partial - privacy: partial - security: low ---- + o: partial + p: partial + s: low -## Intent - -Enable institutions to monitor private transactions for regulatory compliance (AML, sanctions, fraud) without exposing transaction details to unauthorized parties. Balance privacy preservation with auditability through selective screening approaches and tiered disclosure. +crops_context: + cr: "The screening oracle is a single point of censorship by design. Reaches `medium` if replaced with a threshold consensus oracle network that includes appeal routes and cannot unilaterally block transactions." + o: "Rule engines are often proprietary and bundled with screening vendors. Improves to `yes` by open-sourcing the rule engine under a copyleft license and making rule updates auditable." + p: "The oracle sees some transaction metadata by design. Reaches `full` when enforced screening uses ZK proofs (prove amount under threshold, prove counterparty not on sanctions list) so the oracle validates attestations without seeing amounts or identities." + s: "Rides on a single operator's honesty and availability. Improves to `high` by replacing single-operator trust with threshold KMS and timelocked recovery for rule updates." -## Ingredients +post_quantum: + risk: medium + vector: "Signatures on screening attestations inherit host-chain and oracle signature assumptions. ZK proofs used in privacy-preserving screening inherit their proof system's exposure." + mitigation: "Hash-based signatures and STARK-based screening proofs. See [Post-Quantum Threats](../domains/post-quantum.md)." -- **Standards:** EAS for audit logging, ERC-3643 for permissioned tokens (requires privacy extension — ONCHAINID is not privacy-preserving today; see [ERC-3643 RWA pattern](pattern-erc3643-rwa.md#trade-offs)), W3C Verifiable Credentials for compliance attestations -- **Infra:** Compliance oracle (Chainalysis, Elliptic, or internal), threshold KMS for viewing keys, L2 with privacy features -- **Off-chain:** Screening service, alert management system, case management workflow, regulatory reporting interface +standards: [EAS, ERC-3643] -## Protocol (concise) +related_patterns: + composes_with: [pattern-regulatory-disclosure-keys-proofs, pattern-user-controlled-viewing-keys, pattern-verifiable-attestation, pattern-zk-kyc-ml-id-erc734-735, pattern-erc3643-rwa] + see_also: [pattern-shielding, pattern-proof-of-innocence, pattern-zk-promises] -1. **Pre-screening:** Before transaction submission, sender's compliance node checks recipient against sanctions lists and internal policies -2. **Commit phase:** Transaction submitted with encrypted payload; compliance oracle receives viewing key or ZK proof of compliance -3. **Screen:** Oracle verifies transaction against AML rules without seeing full details (amount ranges, counterparty risk scores) -4. **Alert or Clear:** If screening passes, transaction proceeds; if flagged, alert generated with severity level -5. **Escalation:** High-severity alerts trigger hold and manual review; low-severity logged for batch review -6. **Settlement:** Cleared transactions settle; flagged transactions held pending resolution -7. **Audit trail:** All screening decisions logged to EAS with timestamps and rule versions -8. **Reporting:** Periodic compliance reports generated from audit logs for regulators +open_source_implementations: [] +--- -## Guarantees +## Intent -- **Privacy:** - - Transaction details visible only to compliance function and authorized parties - - Screening can use ZK proofs (prove amount < threshold without revealing amount) - - Counterparty identities protected from public view +Enable institutions to screen private transactions for regulatory compliance (AML, sanctions, fraud) without exposing transaction details to unauthorized parties. Balance privacy preservation with auditability through selective screening approaches and tiered disclosure, so settlement can proceed under compliance controls while counterparty identities and amounts remain shielded from public view. -- **Compliance:** - - All transactions screened against current sanctions lists - - Configurable rule engine supports jurisdiction-specific requirements - - Immutable audit trail proves due diligence +This is an orchestration pattern that composes primitives (viewing keys, ZK proofs, threshold KMS, attestations) into a compliance workflow. The unique contribution is the rule engine, alert pipeline, and audit trail that hold the workflow together; the underlying disclosure primitives are linked via `related_patterns`. -- **Auditability:** - - Regulator can request disclosure via viewing keys (see [Selective Disclosure](pattern-regulatory-disclosure-keys-proofs.md)) - - Screening decisions timestamped and signed - - Alert resolution workflow fully logged +## Components -## Trade-offs +- **Compliance oracle or screening service** evaluates transactions against sanctions lists, AML rules, and internal policies. Can be centralized, federated, or threshold-operated. +- **Rule engine** stores jurisdiction-specific rules with versioning. Rule updates are logged and auditable. +- **Threshold key management** issues and rotates viewing keys distributed to authorized parties, so no single operator can unilaterally decrypt transaction contents. +- **ZK proof verifiers** (optional) validate compliance attestations such as "amount below reporting threshold" or "counterparty not on sanctions list" without revealing the underlying values. +- **Alert and case management system** handles flagged transactions through severity tiers with defined response times. +- **Audit log** records every screening decision with timestamp, rule version, and decision hash. Typically anchored on-chain via attestations for tamper evidence. -| Aspect | Trade-off | Mitigation | -|--------|-----------|------------| -| **Latency** | Real-time screening adds 100-500ms per transaction | Batch screening for low-risk flows; parallel screening | -| **Privacy leak** | Compliance oracle sees some transaction metadata | Use ZK proofs for screening; minimize oracle data access | -| **False positives** | Overly strict rules block legitimate transactions | Tiered thresholds; human review for edge cases | -| **Oracle trust** | Centralized compliance oracle is a privacy risk | Threshold oracle with multiple providers; TEE-based screening | -| **Cost** | Screening services charge per-transaction fees | Volume discounts; internal screening for high-frequency flows | -| **Censorship** | Compliance oracle can unilaterally block any transaction; no on-chain bypass in base protocol | Threshold oracle with governance; transparent appeal process | +## Protocol -- **CROPS context (both)**: CR could reach `medium` if the centralized oracle is replaced with a threshold consensus oracle network that includes appeal routes. OS improves to `yes` by open-sourcing the screening rule engine under a copyleft license. Privacy could reach `full` by enforcing ZK proof-based screening where the oracle validates compliance attestations without seeing amounts or identities. Security improves to `high` by replacing single-operator trust with threshold KMS and timelocked recovery. In I2I settings, counterparties may accept a single compliance oracle operated by a trusted consortium member. In I2U settings, end-users have no visibility into oracle decisions, making threshold consensus and transparent appeal processes essential. +1. [user] Sender constructs a transaction and generates a compliance attestation (viewing key or ZK proof) alongside the encrypted payload. +2. [operator] Compliance oracle pre-screens the recipient against sanctions lists and internal policies before the transaction is submitted. +3. [operator] Oracle verifies the transaction against AML rules using the attestation, without seeing the full plaintext when ZK proofs are used. +4. [operator] If screening passes, the oracle emits a cleared attestation; if flagged, an alert is generated with severity level. +5. [operator] High-severity alerts trigger a hold and manual review; low-severity cases are logged for batch review. +6. [contract] Cleared transactions settle on the host chain; flagged transactions remain held pending resolution. +7. [auditor] Periodic compliance reports are generated from the audit log for regulator filing. Regulators can request selective disclosure via viewing keys on demand. -## Alert Thresholds (Reference) +## Guarantees & threat model -| Severity | Trigger | Response Time | Action | -|----------|---------|---------------|--------| -| **Critical** | Sanctioned entity match | Immediate | Block transaction, notify compliance officer | -| **High** | Amount > jurisdiction threshold | < 1 hour | Hold for manual review | -| **Medium** | Unusual pattern detected | < 24 hours | Flag for batch review | -| **Low** | Minor policy deviation | Next business day | Log and monitor | +Guarantees: -## Example +- Transaction details are visible only to the compliance function and authorized parties. +- All transactions are screened against current sanctions lists and jurisdiction rules before settlement. +- Screening decisions produce an immutable, timestamped audit trail suitable for regulator review. +- Counterparty identities are protected from public view; disclosure is scoped to authorized auditors via viewing keys. -**Private Bond Settlement with Compliance Screening:** +Threat model: -1. Bank A initiates €5M bond purchase from Bank B on privacy L2 -2. Bank A's compliance node pre-screens Bank B against sanctions list (clear) -3. Transaction submitted with encrypted amount; compliance oracle receives ZK proof that amount is within reporting threshold -4. Oracle verifies proof, checks counterparty risk score (medium), clears transaction -5. Settlement executes; audit log records: timestamp, screening version, result (cleared), proof hash -6. Monthly report aggregates cleared transactions for regulatory filing +- Soundness of any ZK proofs used for screening attestations. +- Non-colluding oracle operators. A single compromised or coerced operator in a centralized deployment can leak transaction metadata or unilaterally block transactions. +- Rule engine integrity. A tampered rule set can allow prohibited transactions or block legitimate ones. +- Key management for viewing keys. Compromised keys enable unauthorized decryption of historical transactions. +- Network-layer metadata (IP, timing, submission patterns) is out of scope and must be covered separately. -**Flagged Transaction Flow:** +## Trade-offs -1. Corporation X initiates transfer to newly onboarded counterparty -2. Pre-screening detects counterparty jurisdiction requires enhanced due diligence -3. Alert (severity: High) generated; transaction held in pending state -4. Compliance officer reviews counterparty documentation, approves with note -5. Transaction released; audit log includes officer ID, approval timestamp, justification hash +- Real-time screening adds 100 to 500 ms per transaction. Batch screening for low-risk flows mitigates this. +- False positives from overly strict rules block legitimate transactions. Tiered thresholds and human review for edge cases are standard mitigations. +- Oracle trust is a concentration point. Threshold operation with multiple providers or TEE-based screening reduces this risk. +- Per-transaction screening fees can be significant at volume; internal screening for high-frequency flows is common. +- Centralized oracles retain unilateral censorship power even when privacy is otherwise strong; threshold governance and transparent appeals are necessary counterweights. -## See also +## Example -- [Selective Disclosure (Viewing Keys + ZK Proofs)](pattern-regulatory-disclosure-keys-proofs.md) - On-demand regulator access -- [Verifiable Attestation](pattern-verifiable-attestation.md) - On-chain credential verification -- [ERC-3643 RWA](pattern-erc3643-rwa.md) - Permissioned tokens with identity -- [ZK KYC/ML ID](pattern-zk-kyc-ml-id-erc734-735.md) - Zero-knowledge identity verification -- [Approach: Private Bonds](../approaches/approach-private-bonds.md) - End-to-end compliant bond issuance +- An institution initiates a large bond purchase on a privacy L2. +- The sender's compliance node pre-screens the counterparty against the sanctions list (clear). +- The transaction is submitted with an encrypted amount and a ZK proof that the amount is within the reporting threshold. +- The oracle verifies the proof, checks the counterparty risk score (medium), and clears the transaction. +- Settlement executes. The audit log records timestamp, screening version, result, and proof hash. +- A monthly report aggregates cleared transactions for the regulatory filing. -## External References +## See also -- [FATF Travel Rule Guidance](https://www.fatf-gafi.org/en/publications/Fatfrecommendations/Guidance-rba-virtual-assets-2021.html) - AML requirements for virtual assets -- [Chainalysis Compliance](https://www.chainalysis.com/solutions/compliance/) - Transaction screening provider -- [Elliptic](https://www.elliptic.co/) - Blockchain analytics and compliance +- [FATF Travel Rule guidance](https://www.fatf-gafi.org/en/publications/Fatfrecommendations/Guidance-rba-virtual-assets-2021.html) +- [EAS specification](https://docs.attest.org/) diff --git a/patterns/pattern-cross-chain-privacy-bridge.md b/patterns/pattern-cross-chain-privacy-bridge.md index d1532b0..d4294c4 100644 --- a/patterns/pattern-cross-chain-privacy-bridge.md +++ b/patterns/pattern-cross-chain-privacy-bridge.md @@ -1,139 +1,120 @@ --- title: "Pattern: Cross-Chain Privacy Bridge" status: draft -maturity: PoC +maturity: testnet +type: standard layer: hybrid -privacy_goal: Move assets between chains while preserving privacy on the destination -assumptions: Destination chain has shielded pool or private execution; bridge trust model accepted -last_reviewed: 2026-01-22 +last_reviewed: 2026-04-22 + works-best-when: - - Moving assets between domains while minimizing linkability - - Both chains have shielded pools (required for full amount privacy) - - Explicit bridge trust assumptions are acceptable + - Moving assets between domains while minimizing linkability. + - Both chains have shielded pools (required for full amount privacy). + - Explicit bridge trust assumptions are acceptable. avoid-when: - - Both legs on same domain (use internal transfer) - - Destination lacks privacy primitive (no benefit to bridge privacy) - - Regulatory requirements demand end-to-end public transparency - - Either or both chains have frequent reorgs (finality assumptions unreliable) -dependencies: - - Source-domain escrow contract (lock or burn) - - Destination-domain mint contract integrated with shielded pool - - Cross-domain verification mechanism (operator/optimistic/ZK/light client) + - Both legs on same domain (use internal transfer). + - Destination lacks a privacy primitive (no benefit to bridge privacy). + - Regulatory requirements demand end-to-end public transparency. + - Either or both chains have frequent reorgs (finality assumptions unreliable). + context: both +context_differentiation: + i2i: "Institutions may operate their own relayers under bilateral agreements, reducing censorship risk but concentrating trust. KYC-aligned identities on both ends simplify audit, and escrow operators are typically known parties bound by contract. The anonymity set is narrower but acceptable because unlinkability from competitors is the primary goal." + i2u: "End-users depend entirely on public relayer availability and cannot assume any operator will act in their interest. Permissionless relayer selection, source-side anonymization before bridging, and forced-withdrawal from destination pools are required to preserve meaningful privacy and liveness." + crops_profile: cr: medium - os: partial - privacy: partial - security: medium + o: partial + p: partial + s: medium + +crops_context: + cr: "Reaches `high` if relay infrastructure is decentralized with permissionless relayer selection and the destination mint cannot be gated by a single operator. Drops to `low` under custodial bridges where one operator controls mints." + o: "Bridge contracts and verification circuits are often partially open. Improves to `yes` with reproducible builds and open-sourced bridge contracts, verification circuits, and relayer code." + p: "Destination shielding provides receiver privacy, but source-side sender privacy is not automatic. Reaches `full` by mandating source-side anonymization (deposit through a pre-bridge shielded pool before generating commitments) and enforcing relayer-based submission with timing delays." + s: "Varies widely by verification mechanism. ZK verification of source consensus with economic finality guarantees reaches `high`; custodial or MPC operators sit at `medium` or `low`." + +post_quantum: + risk: high + vector: "ZK verification of source consensus inherits the underlying SNARK's PQ exposure. Shielded pool commitments and note encryption on the destination carry HNDL risk." + mitigation: "STARK-based bridge proofs and hash-commitment shielded pools. See [Post-Quantum Threats](../domains/post-quantum.md)." + +standards: [ERC-20] + +related_patterns: + requires: [pattern-shielding] + composes_with: [pattern-stealth-addresses, pattern-network-anonymity, pattern-regulatory-disclosure-keys-proofs] + alternative_to: [pattern-permissioned-ledger-interoperability] + see_also: [pattern-privacy-l2s, pattern-forced-withdrawal] + +open_source_implementations: [] --- ## Intent -Move assets between chains while preserving privacy on the destination by minting shielded notes whose ownership is not linkable to the source-domain depositor. +Move assets between chains while preserving privacy on the destination by minting shielded notes whose ownership is not linkable to the source-domain depositor. Full sender and amount privacy requires privacy primitives on the source chain or pre-bridge anonymization; without these, the source lock transaction reveals the depositor address and amount. -**Note:** Full sender/amount privacy requires privacy primitives on source chain or pre-bridge anonymization (e.g., deposit through existing shielded pool before bridging). Without this, the source-side lock transaction reveals depositor address and amount. +## Components -## Ingredients - -- **Source escrow:** Lock-mint (forward) / burn-unlock (return) contract on origin chain -- **Destination privacy primitive:** Shielded pool with commitments + nullifiers (e.g., Aztec, Railgun, Privacy Pools) -- **Cross-domain message:** Event/log attesting to deposit; inclusion proof -- **Verification mechanism:** Operator signature, optimistic challenge, ZK proof, or light client -- **Relayer infrastructure:** Submit proofs on destination without linking depositor (fee model matters) -- **Optional compliance hooks:** View keys for auditors, screening gates, deposit limits +- **Source escrow contract** locks assets on forward bridging or burns them on return. Emits an event carrying the destination commitment. +- **Destination privacy primitive** is a shielded pool with commitments and nullifiers. The bridge mints a note into this pool rather than transferring a transparent token. +- **Cross-domain message and verification mechanism** carries finality evidence from source to destination. Options include operator signatures, MPC or threshold signatures, optimistic claims with challenge windows, ZK succinct proofs of source consensus (zk-SPV), light clients, or TEE-attested enclaves. +- **Relayer infrastructure** submits finality proofs on the destination without linking the depositor. Fee model matters: if the depositor pays the relayer directly from a known address, the linkage is reintroduced. +- **Optional compliance hooks** include viewing keys for auditors, screening gates, and deposit limits. +- **Timeout and recovery path** on the source escrow allows the depositor to reclaim funds if the destination mint never completes. ## Protocol -1. **Deposit intent** — User generates destination note commitment `C = hash(value, recipient_pubkey, randomness)`. Does not reveal recipient on source chain. - -2. **Source escrow** — Lock or burn assets in source contract. Emit event containing `(amount, C, nonce)`. This step is typically public on source chain. +1. [user] Generate a destination note commitment `C = hash(value, recipient_pubkey, randomness)`. The recipient is not revealed on the source chain. +2. [contract] Lock or burn the assets in the source escrow. Emit an event containing the amount, `C`, and a nonce. The lock is public on the source chain. +3. [relayer] Obtain finality evidence for the source lock: operator signature, threshold signature, optimistic claim, ZK proof of source consensus, light-client header, or TEE attestation, depending on the bridge's trust model. +4. [contract] The destination bridge contract verifies the finality evidence and mints a note into the shielded pool with commitment `C`. +5. [user] The recipient spends the note privately within the destination pool using standard shielded-pool semantics (nullifier reveal, proof of membership and ownership). +6. [user] For the return path, burn the shielded note on the destination, prove the burn to the source, and unlock the escrowed assets. The return leg can also be private if the source supports it. +7. [user] If the mint never completes within the timeout window, reclaim from the source escrow via the recovery path (requires a proof of non-mint or a governance override, depending on the bridge design). -3. **Finality evidence** — Obtain proof that source escrow finalized: - - *Custodial:* Operator signature - - *MPC/TSS:* Threshold signature from committee - - *Optimistic:* Relayer claim + challenge period - - *ZK:* Succinct proof of source consensus + inclusion (zk-SPV) - - *Light client:* Verify source headers on destination - - *TEE:* Attested enclave signature +## Guarantees & threat model -4. **Destination mint** — Submit finality evidence to destination bridge contract. Contract verifies, then mints note into shielded pool with commitment `C`. +Guarantees: -5. **Private spend** — Recipient proves ownership of `C` via nullifier reveal, spends privately within destination pool. Standard shielded-pool semantics apply. +- Destination recipient is not revealed on the source chain; the commitment hides their identity. +- Destination observers cannot link the recipient to the source depositor when a relayer submits the mint and timing is obfuscated. In custodial designs, the operator still knows the depositor but the destination chain does not. +- Amount privacy on the destination if the shielded pool supports confidential amounts or fixed denominations. +- Integrity: no double-mint (replayed deposits are blocked by nullifier or nonce tracking), and value is conserved across the two domains. +- Selective auditor access via viewing keys or compliance proofs, scoped to the destination pool's disclosure mechanism. -6. **Return path (optional)** — Burn shielded note on destination, prove burn finality on source, unlock escrowed assets. Return leg can also be private if source supports it. +Threat model: -7. **Recovery/expiry** — If mint never completes within timeout, depositor can reclaim from source escrow (requires proof of non-mint or governance override). - -## Guarantees - -- **Recipient privacy:** Destination recipient not revealed on source chain (commitment hides identity) -- **Sender privacy:** Destination observers cannot link recipient to source depositor (requires relayer that doesn't leak depositor, timing obfuscation). In custodial model, source deposit goes to operator address (like a CEX deposit), so the operator knows the depositor but the destination chain does not. -- **Amount privacy:** If destination uses confidential amounts or fixed denominations -- **Integrity:** No double-mint (replay protected by nullifier or nonce tracking); conservation of value across domains -- **Auditor access:** View keys or compliance proofs can selectively reveal to authorized parties - -**NOT guaranteed:** -- Instant atomic settlement — this is a two-phase commit workflow -- Source-side sender privacy — without pre-bridge mixing, depositor is visible +- Soundness of the verification mechanism. A compromised operator (custodial), a threshold breach (MPC), an unchallenged fraudulent claim (optimistic), a circuit bug (ZK), or a mishandled fork (light client) each break bridge integrity. +- Non-censoring relayer set. A single required relayer can refuse to submit the mint; the user then depends on the recovery path. +- Non-censoring destination sequencer or validator set for mint transactions. +- Reorg handling on the source chain. Finality assumptions must hold for the bridge's chosen finality evidence; chains with frequent reorgs break this. +- Source-side sender privacy is not provided by this pattern; depositor address and amount are visible on the source chain unless combined with pre-bridge anonymization. +- Metadata leakage (IP, timing, gas patterns, relayer fee payment) is out of scope for the bridge layer. ## Trade-offs -### Trust Model Comparison - -| Model | What you trust | Latency | Cost | Typical risk | -|-------|----------------|---------|------|--------------| -| Custodial | Single operator honesty | Low | Low | Theft (operator receives deposit but doesn't mint), censorship | -| MPC/TSS | Threshold of signers | Low-Med | Medium | Key compromise if threshold breached | -| Optimistic | At least one honest watcher | Med-High | Medium | Delayed finality, griefing | -| ZK (zk-SPV) | Proof system soundness + verifier | Medium | High | Prover DoS, circuit bugs | -| Light client | Destination verifies source consensus | Medium | Medium | Fork handling, header availability | -| TEE-assisted | Enclave attestation validity | Low | Medium | Side-channel attacks, vendor trust | - -### Failure Modes - -**Privacy leakage:** -- Amount correlation — exact deposit amounts visible on source -- Timing correlation — deposit/mint timing reveals linkage -- Fee linkage — if depositor pays relayer fees directly -- Metadata — IP addresses, transaction ordering, gas patterns - -**Bridge correctness:** -- Reorg handling — source finality assumptions may be violated -- Replay/double-mint — must track processed deposits (nullifier set) -- Cross-domain confusion — wrong chain ID, token mismatch - -**Liveness/censorship:** -- Operator refuses relay — user needs alternative submission path -- Griefing via spam — deposits that are never minted, locking funds -- Destination chain censorship — mint transactions blocked - -**Key/governance risks:** -- Threshold key compromise — TSS/MPC signers collude -- View key misuse — auditors leak or sell data -- Upgrade attacks — malicious contract upgrades -- **CROPS context (both)**: CR could reach `high` if relay infrastructure is decentralized with permissionless relayer selection. OS improves to `yes` by open-sourcing bridge contracts and verification circuits with reproducible builds. Privacy could reach `full` by mandating source-side anonymization (deposit through a pre-bridge shielded pool before generating commitments). Security improves to `high` by replacing custodial or MPC operators with ZK verification of source consensus and economic finality guarantees. In I2I settings, institutions may operate their own relayers under bilateral agreements, reducing censorship risk but concentrating trust. In I2U settings, end-users depend entirely on public relayer availability, making permissionless relayer selection and source-side anonymization more critical. +- Two-phase commit workflow, not instant atomic settlement. Latency depends on source finality and any challenge window. +- Cost scales with the verification mechanism. ZK proofs are expensive to generate; optimistic systems impose challenge delays; custodial designs are cheap but centralized. +- Reorg handling and cross-domain confusion (wrong chain ID, token mismatch) are recurring failure modes that must be guarded at the contract layer. +- Griefing through deposits that are never minted locks funds until timeout. The recovery path must be robust and well-documented. +- Key and governance risks: TSS or MPC signer collusion, view-key misuse, and malicious contract upgrades each sit outside the cryptographic trust model and require operational controls. ## Example -An institution holds tokenized bonds on Ethereum L1 and wants to enable private secondary-market trading. - -1. **Deposit:** Institution deposits 100 bond tokens into source escrow, specifying destination commitment `C` (no recipient revealed on L1) -2. **Finality:** After L1 finality (~12 min), optimistic bridge posts claim on privacy L2 -3. **Mint:** After challenge period (e.g., 1 hour), L2 mints shielded note for commitment `C` -4. **Trade:** Bond holder trades privately within L2 shielded pool — counterparties and amounts hidden -5. **Exit:** When redeeming, burn shielded note on L2, prove burn to L1, unlock from escrow - -Privacy achieved: L2 trading activity not linkable to original L1 depositor (assuming proper relayer usage and timing delays). +- An institution holds tokenized bonds on Ethereum L1 and wants to enable private secondary-market trading on a privacy L2. +- The institution deposits bond tokens into the source escrow, specifying destination commitment `C`. No recipient is revealed on L1. +- After L1 finality, an optimistic bridge posts a claim on the L2. +- After the challenge period, the L2 mints a shielded note for commitment `C` into its pool. +- The bond holder trades privately within the L2 shielded pool; counterparties and amounts are hidden from chain observers. +- On redemption, the holder burns the shielded note on the L2, proves the burn to L1, and unlocks the escrow. ## Variants -- **Pre-bridge mixing:** Deposit through source-chain shielded pool first, then bridge — achieves full sender privacy -- **Hub-and-spoke:** Use L1 as verification hub; L2s prove deposits via L1 bridge contract -- **Privacy-to-privacy:** Both source and destination have shielded pools — maximum privacy but complex verification -- **Asymmetric:** Only one direction is private (e.g., public L1 → private L2) +- **Pre-bridge mixing**: Deposit through a source-chain shielded pool first, then bridge. Achieves full sender privacy at the cost of additional latency. +- **Hub-and-spoke**: Use L1 as a verification hub; multiple L2s prove deposits via the L1 bridge contract. +- **Privacy-to-privacy**: Both source and destination have shielded pools. Maximum privacy but verification is more complex. +- **Asymmetric**: Only one direction is private (for example, public L1 to private L2). ## See also -- [pattern-permissioned-ledger-interoperability.md](pattern-permissioned-ledger-interoperability.md) — Enterprise ledger sync -- [pattern-privacy-l2s.md](pattern-privacy-l2s.md) — Destination privacy environments -- [pattern-shielding.md](pattern-shielding.md) — Commitment/nullifier pools +- [EIP-7281 (xERC20)](https://eips.ethereum.org/EIPS/eip-7281) diff --git a/patterns/pattern-crypto-registry-bridge-ewpg-eas.md b/patterns/pattern-crypto-registry-bridge-ewpg-eas.md index 77d0e4c..47218aa 100644 --- a/patterns/pattern-crypto-registry-bridge-ewpg-eas.md +++ b/patterns/pattern-crypto-registry-bridge-ewpg-eas.md @@ -1,56 +1,95 @@ --- title: "Pattern: Crypto-register bridge (eWpG) with EAS mirroring" status: ready -maturity: pilot +maturity: concept +type: standard layer: hybrid -privacy_goal: Mirror licensed crypto-register facts on-chain as attestations without exposing PII -assumptions: Licensed crypto-register (eWpG), EAS infrastructure, registrar API access -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 + works-best-when: - - Germany/eWpG applies and a licensed crypto-register is required. + - Germany or eWpG applies and a licensed crypto-register is required. avoid-when: - You can legally replace the register on day one. -dependencies: - - eWpG policy - - EAS + context: i2i + crops_profile: cr: none - os: partial - privacy: full - security: medium + o: partial + p: full + s: medium + +crops_context: + cr: "The registrar is the sole gatekeeper and can refuse or delay registrations. Reaches `medium` if an open API standard enables alternative registrar implementations, reducing single-registrar lock-in." + o: "Middleware is often proprietary. Improves to `yes` by publishing the registrar integration layer and EAS schema definitions under an open-source license." + p: "No PII is posted on-chain; only hashes and attestations. Plaintext legal records stay with the licensed registrar and are disclosed off-chain under NDA." + s: "Rides on the registrar's operational integrity and the EAS attester's key management. Improves to `high` by requiring multiple independent EAS attesters to cross-validate registrar claims." + +post_quantum: + risk: medium + vector: "Attestation signatures rely on standard ECDSA and inherit PQ exposure. Hashes anchored on-chain are PQ-safe." + mitigation: "Migrate attestation signatures to PQ-safe schemes as ecosystem standards mature. See [Post-Quantum Threats](../domains/post-quantum.md)." + +standards: [EAS] + +related_patterns: + composes_with: [pattern-regulatory-disclosure-keys-proofs, pattern-icma-bdt-data-model, pattern-verifiable-attestation] + see_also: [pattern-erc3643-rwa] + +open_source_implementations: [] --- ## Intent -Operate with a licensed **crypto-register** today while **mirroring key facts** (issuance, transfers, liens) as **on-chain attestations** to anchor integrity and pave automation. -## Ingredients -- **Standards**: EAS schemas for legal facts -- **Infra**: Registrar API integration -- **Off-chain**: Notarized records; NDA-regulated reveal process +Operate with a licensed crypto-register today while mirroring key legal facts (issuance, transfers, liens) as on-chain attestations. The registrar remains the legal source of truth; the on-chain anchor provides tamper evidence and paves the way for later automation once regulation allows. + +## Components -## Protocol (concise) -1. Registrar records legal event; emits signed record. -2. Middleware posts an **EAS attestation hash** (no PII) on-chain. -3. Audits: match registrar record ↔ on-chain anchor. +- **Licensed crypto-register** under eWpG holds the legal records, PII, and signed notarial documents off-chain. It is the sole source of legal truth. +- **Registrar API integration layer** exposes signed records for each legal event (issuance, transfer, lien) to downstream systems. +- **On-chain attestation schema** defines the structure of mirrored facts: event type, record hash, registrar identifier, timestamp. PII never appears on-chain. +- **Middleware attester** reads the registrar's signed records, computes the hash, and posts an attestation on-chain under the schema. +- **Reconciliation and audit tooling** matches the on-chain anchor to the off-chain registrar record and flags drift. -## Guarantees -- Legal compliance now; cryptographic anchors for later automation. -- Tamper-evident record linkage. +## Protocol + +1. [operator] Registrar records the legal event in the off-chain register and emits a signed record containing the event details and a record hash. +2. [operator] Middleware consumes the signed record, verifies the registrar's signature, and constructs an attestation containing the record hash, event type, and timestamp. +3. [contract] The attestation is posted on-chain under the agreed EAS schema. No PII is included. +4. [auditor] Later audits match the on-chain anchor to the registrar record: retrieve the registrar's plaintext record under NDA, recompute the hash, and confirm it equals the anchored attestation. +5. [auditor] Discrepancies trigger the incident runbook: the registrar remains legally authoritative, but a mismatch is evidence of tampering in one of the two systems. + +## Guarantees & threat model + +Guarantees: + +- Legal compliance with eWpG is preserved; the licensed registrar remains the authoritative record keeper. +- On-chain anchor provides tamper-evident linkage between the registrar's private ledger and a public timestamp. +- Mirrored facts are cryptographically verifiable without requiring regulator access to the plaintext. + +Threat model: + +- Trust in the registrar as sole gatekeeper. The registrar can refuse or delay any registration with no on-chain bypass. +- Middleware attester key compromise allows forged anchors. Multi-attester cross-validation mitigates this. +- Collusion between the registrar and the middleware can produce consistent but fraudulent records on both sides. Independent attesters reduce but do not eliminate this risk. +- PII exposure is out of scope for the on-chain layer by design; the registrar's access controls govern all PII handling. ## Trade-offs -- Two sources of truth; reconciliation required. -- Strong incident/runbook discipline. -- Registrar is sole gatekeeper; can refuse or delay registrations with no on-chain bypass. -- **CROPS context (i2i)**: CR could reach `medium` if an open API standard enables alternative registrar implementations, reducing single-registrar lock-in. OS improves to `yes` by publishing the registrar integration layer and EAS schema definitions under an open-source license. Security improves to `high` by requiring multiple independent EAS attesters to cross-validate registrar claims. Between institutions, the registrar dependency is partially offset by existing contractual relationships, but multi-registrar interoperability would reduce concentration risk and simplify cross-border issuance under eWpG. + +- Two sources of truth require ongoing reconciliation. Drift between the registrar and the on-chain anchor must be detected and resolved operationally. +- Strong incident and runbook discipline is required. A mismatch is not self-resolving; it triggers a manual investigation. +- Registrar dependency limits availability. Downtime at the registrar halts new anchors even if the on-chain side is healthy. +- The pattern is explicitly transitional: it assumes a future regulatory regime where the register itself can move on-chain and automation can replace the middleware. ## Example -- Issuance logged by registrar; hash anchored on-chain; auditor verifies hash match later. + +- An issuer records a bond issuance with the licensed registrar under eWpG. +- The registrar emits a signed record. +- The middleware hashes the record and posts an EAS attestation on Ethereum. +- A year later, an auditor retrieves the registrar's plaintext record under NDA, recomputes the hash, and confirms it matches the on-chain attestation, establishing integrity. ## See also -- pattern-regulatory-disclosure-keys-proofs.md · pattern-icma-bdt-data-model.md -## See also (external) -- BaFin on eWpG: https://www.bafin.de/EN/PublikationenDaten/Fachartikel/2021/fa_bj_2107_eWpG_en_en.html -- BaFin · Crypto-securities register: https://www.bafin.de/EN/Aufsicht/FinTech/Geschaeftsmodelle/DLT_Blockchain_Krypto/Kryptowertpapierregisterfuehrung/Wertapierregister_node_en.html -- EAS docs: https://easscan.org/docs \ No newline at end of file +- [BaFin on eWpG](https://www.bafin.de/EN/PublikationenDaten/Fachartikel/2021/fa_bj_2107_eWpG_en_en.html) +- [BaFin crypto-securities register](https://www.bafin.de/EN/Aufsicht/FinTech/Geschaeftsmodelle/DLT_Blockchain_Krypto/Kryptowertpapierregisterfuehrung/Wertapierregister_node_en.html) +- [EAS documentation](https://easscan.org/docs) diff --git a/patterns/pattern-dvp-erc7573.md b/patterns/pattern-dvp-erc7573.md index 62a7d46..46b02b0 100644 --- a/patterns/pattern-dvp-erc7573.md +++ b/patterns/pattern-dvp-erc7573.md @@ -1,133 +1,119 @@ --- title: "Pattern: Atomic DvP via ERC-7573 (cross-network)" status: ready -maturity: pilot +maturity: concept +type: standard layer: hybrid -privacy_goal: Enable atomic cross-network DvP with optional privacy extensions -assumptions: ERC-7573 contracts on both networks, stateless decryption oracle, trade negotiation system -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 + works-best-when: - - Asset and cash legs live on different networks (L1/L2). + - Asset and cash legs live on different networks (L1 or L2). avoid-when: - Both legs already settle on the same network with simple on-chain transfers. - - You're searching for a production-ready solution (EIP not yet recommended) - - You're searching for a fully trustless solution -dependencies: - - ERC-7573 locking contract (asset leg) - - ERC-7573 decryption contract (payment leg) - - Stateless decryption oracle on the payment network -context: both -crops_profile: - cr: medium - os: partial - privacy: none - security: medium ---- - -## Intent - -Enable atomic Delivery-versus-Payment (DvP) across two networks using ERC-7573, so that either the asset is delivered and payment is completed, or the asset returns to the seller. -The pattern targets institutions that need cross-network settlement with clear behaviour, auditability, and optional privacy. - -In this pattern: -- **asset leg** = the tokenised security or collateral being delivered -- **cash leg** = the token used for payment (for example, a stablecoin or tokenised deposit) -- **decryption oracle** = a service on the payment network that, for each trade, decrypts one of two outcome keys based on the actual payment result; the asset contract then uses that key to decide whether to deliver or reclaim - -## Ingredients + - You're searching for a production-ready solution (EIP not yet recommended). + - You're searching for a fully trustless solution. -- **Standards** - - ERC-7573 locking contract on the asset network - - ERC-7573 decryption contract on the payment network - - Oracle proxy and callback contracts (per ERC-7573) +context: i2i -- **Infra** - - Asset network where the security or collateral is issued - - Payment network that holds the payment token - - Stateless decryption oracle implementation (single or multi-operator) +crops_profile: + cr: medium + o: partial + p: none + s: medium -- **Off-chain** - - Trade negotiation or order system that assigns a shared trade identifier - - A component that creates and distributes two outcome keys per trade (success / failure) and keeps them off-chain - - Monitoring and logging for contracts and oracle +crops_context: + cr: "Oracle governance is typically codified in bilateral or consortium agreements, so the practical censorship risk sits below the protocol-level score. Reaches `high` if threshold decryption oracles with k-of-n quorum replace single-operator oracles, removing any single exclusion point." + o: "Oracle and contract implementations vary by deployment. Improves to `yes` by releasing oracle implementations and outcome key services under a copyleft license." + p: "Standard ERC-7573 provides atomic settlement but no privacy: trade identifier, amounts, and counterparties may be observable on-chain. Reaches `partial` or `full` by layering threshold-encrypted mempools, minimal on-chain trade data, and private or proof-based payment layers." + s: "Rides on the decryption oracle operator's honesty for liveness. Improves to `high` by replacing operational trust with verifiable proofs of outcome key validity and threshold quorum." -## Protocol (concise) +post_quantum: + risk: medium + vector: "Oracle decryption relies on standard public-key encryption; outcome key commitments inherit hash assumptions. Payment-network signatures carry host-chain PQ exposure." + mitigation: "Migrate decryption to PQ-safe KEM schemes (Kyber, ML-KEM) as ERC-7573 extensions mature. See [Post-Quantum Threats](../domains/post-quantum.md)." -1. **Agree trade off-chain** - Two institutions agree on asset, quantity, payment token, amount, a shared trade identifier `T`, and a latest time to settle or unwind. They record `T` and the terms in their internal systems. +standards: [EIP-7573, ERC-20] -2. **Lock the asset with outcome keys** - For trade `T`, the trade-setup system provides two outcome keys (one meaning “deliver to buyer”, one meaning “return to seller”). - The seller locks the asset in the ERC-7573 locking contract on the asset network under `T`, registering hashed values of these two keys. The keys themselves stay off-chain. +related_patterns: + composes_with: [pattern-mpc-custody, pattern-regulatory-disclosure-keys-proofs, pattern-threshold-encrypted-mempool] + alternative_to: [pattern-commit-and-prove] + see_also: [pattern-private-pvp-stablecoins-erc7573] -3. **Register the payment** - On the payment network, the buyer registers `T` and the payment details in the ERC-7573 decryption contract, along with encrypted forms of the same two outcome keys: one to use if the payment succeeds, one if it fails or is cancelled. +open_source_implementations: [] +--- -4. **Execute payment and call the oracle** - The buyer executes the payment through the decryption contract. The contract checks the payment against the registered details for `T` and then asks the decryption oracle to decrypt the encrypted key that matches the actual outcome (success or failure). - The oracle decrypts and returns that outcome key to the decryption contract. +## Intent -5. **Settle on the asset leg** - An authorised party submits the outcome key for `T` to the locking contract on the asset network. The contract verifies it against the registered values and either: - - delivers the locked asset to the buyer (payment succeeded), or - - lets the seller reclaim the asset (payment failed, was cancelled, or never completed in time). +Enable atomic Delivery-versus-Payment across two networks so that either the asset is delivered and payment is completed, or the asset returns to the seller. The pattern targets institutions that need cross-network settlement with predictable failure behavior, auditability, and optional privacy extensions layered on top. - If no valid outcome key is submitted before the latest time, the seller uses the reclaim path. +In this pattern: -## Privacy Extensions +- **asset leg** is the tokenized security or collateral being delivered. +- **cash leg** is the token used for payment, such as a stablecoin or tokenized deposit. +- **decryption oracle** is a service on the payment network that, for each trade, decrypts one of two outcome keys based on the actual payment result; the asset contract then uses that key to decide whether to deliver or reclaim. -Standard ERC-7573 provides atomic settlement but no privacy. For institutional use cases requiring confidentiality: +## Components -- **Multi-operator oracle** - Run the decryption oracle with several independent operators and require a threshold of them to cooperate before an outcome key is released. +- **Locking contract on the asset network** registers the hashed outcome keys per trade identifier and gates delivery of the locked asset. +- **Decryption contract on the payment network** holds the encrypted outcome keys and calls the oracle after observing the payment result. +- **Decryption oracle** is a single or multi-operator service that decrypts the outcome key matching the actual payment result. Stateless by design. +- **Off-chain trade negotiation layer** assigns a shared trade identifier, creates and distributes two outcome keys per trade (success and failure), and holds them off-chain. +- **Oracle proxy and callback contracts** bridge the decryption contract and the oracle per the ERC-7573 interface. +- **Monitoring and logging infrastructure** watches both networks for event correlation and reconciles trade state. -- **Minimal on-chain trade data** - Keep full trade terms (price, size, counterparties) in internal systems; on-chain, store only a trade identifier and a short reference that links back to those records. +## Protocol -- **Private or proof-based payment layer** - Use a network or rollup for the cash leg that hides detailed balances but can provide a clear “payment completed / not completed” result for each trade identifier. +1. [user] Two institutions agree off-chain on the asset, quantity, payment token, amount, shared trade identifier `T`, and a latest time to settle or unwind. +2. [user] The trade-setup system generates two outcome keys for `T` (one meaning "deliver to buyer", one meaning "return to seller") and distributes them off-chain. +3. [contract] The seller locks the asset in the locking contract on the asset network under `T`, registering hashed values of the two outcome keys. +4. [contract] The buyer registers `T` and payment details in the decryption contract on the payment network, along with encrypted forms of the same two outcome keys. +5. [user] The buyer executes the payment through the decryption contract. The contract checks the payment against the registered details for `T`. +6. [operator] The decryption contract calls the oracle, which decrypts the encrypted key matching the actual outcome (success or failure) and returns it. +7. [contract] An authorized party submits the outcome key to the locking contract, which verifies it against the registered hashes and either delivers the asset to the buyer (on success) or lets the seller reclaim it (on failure or timeout). -These extensions do not change how ERC-7573 contracts decide outcomes: the asset contract still receives an outcome key and either delivers the asset or allows reclaim. +## Guarantees & threat model -## Guarantees +Guarantees: -- **Atomic settlement** - For each trade, both asset and cash legs settle together, or the asset is reclaimed by the seller; one-sided settlement is not an intended state. +- Atomic settlement: for each trade, both asset and cash legs settle together, or the asset is reclaimed by the seller. One-sided settlement is not an intended state. +- Defined failure behavior: if the payment fails, is cancelled, no outcome key is released, or the latest time passes, the contracts expose a predictable reclaim path for the seller. +- Optional privacy extensions allow observers to see that a trade settled or not without seeing full terms; institutions can still disclose details off-chain when required. -- **Defined failure behaviour** - If the payment fails, is cancelled, no outcome key is released, or the latest time passes, the contracts expose a predictable reclaim path for the seller. +Threat model: -- **Optional privacy** - With minimal on-chain trade data and a private or proof-based payment layer, observers see that a trade settled or not without seeing full terms, while institutions can still disclose details off-chain when required. +- Soundness of the commitment scheme binding outcome key hashes. +- Non-colluding decryption oracle operators. A single operator in a centralized deployment can withhold decryption or release the wrong outcome key, breaking atomicity or liveness. +- Non-censoring sequencers on both networks during the settlement window. A censored payment or settlement transaction forces the fallback to the reclaim path. +- Honest trade-setup system that generates unique, unpredictable outcome keys and distributes them correctly. Collision or replay across trades breaks the guarantee. +- Network-layer metadata (IP, timing, gas patterns) is out of scope. ## Trade-offs -- **Oracle governance** - Institutions must agree who runs the oracle, how its keys are managed, and how incidents (downtime, misconfiguration) are handled. +- Oracle governance is a recurring operational question. Institutions must agree on who runs the oracle, how its keys are managed, and how incidents (downtime, misconfiguration) are handled. +- Settlement latency depends on payment finality, oracle processing, and any proof generation, adding delay relative to same-network transfers. +- Integration effort is non-trivial. Internal systems must handle outcome keys, track trade identifiers, listen to events on both networks, and reconcile them with internal ledgers. +- Exceptional cases (incorrect parameters, operational errors, regulatory holds) still require documented off-chain procedures. Fully automated recovery is out of scope. +- Standard ERC-7573 provides no privacy. Confidentiality requires layering additional patterns: threshold oracles, minimal on-chain data, or private payment layers. -- **Latency and cost** - Settlement depends on payment finality, oracle processing, and any proof generation, adding delay and cost relative to same-network transfers. +## Example -- **Integration effort** - Internal systems must handle outcome keys, track trade identifiers, listen to events on both networks, and reconcile them with internal ledgers. +- An issuer issues a tokenized bond on Ethereum L1 (asset leg). A buyer holds EURC stablecoin on an L2 rollup (cash leg). +- They agree off-chain on trade identifier `T`, bond quantity, payment amount, and a latest settlement time. +- The seller locks the bond in the locking contract on L1 under `T`. +- The buyer registers `T` and executes the EURC payment via the decryption contract on the rollup; the oracle releases the success outcome key for `T`. +- That key is submitted to the L1 locking contract, which transfers the bond to the buyer. If the payment had failed or been cancelled, the failure outcome key would have been used instead and the seller would reclaim the bond. -- **Failure and dispute handling** - Exceptional cases (incorrect parameters, operational errors, regulatory holds) still require documented off-chain procedures. -- **CROPS context (i2i)**: CR could reach `high` if threshold decryption oracles with k-of-n quorum replace single-operator oracles, removing any single exclusion point. OS improves to `yes` by releasing oracle implementations and outcome key services under a copyleft license. Privacy could reach `full` by layering threshold-encrypted mempools so trade details remain encrypted until block inclusion. Security improves to `high` by replacing operational trust with verifiable proofs of outcome key validity. Between institutions, oracle governance is typically codified in bilateral or consortium agreements, so the practical censorship risk is lower than the protocol-level score suggests, but threshold oracles would eliminate residual single-operator risk in multi-party settlement networks. +## Privacy extensions -## Example +Standard ERC-7573 provides atomic settlement but no privacy. For institutional use cases requiring confidentiality: + +- **Threshold decryption oracle**: Run the oracle with several independent operators and require a k-of-n quorum before an outcome key is released. +- **Minimal on-chain trade data**: Keep full trade terms (price, size, counterparties) in internal systems; on-chain, store only a trade identifier and a short reference that links back to those records. +- **Private or proof-based payment layer**: Use a network or rollup for the cash leg that hides detailed balances but can provide a clear "payment completed or not completed" result for each trade identifier. -- Bank A issues a tokenised bond on Ethereum L1 (asset leg). -- Bank B holds EURC stablecoin on an L2 rollup (cash leg). -- They agree off-chain on trade id `T`, bond quantity, payment amount, and a latest settlement time. -- Bank A locks the bond in the ERC-7573 locking contract on L1 under `T`. -- Bank B registers `T` and executes the EURC payment via the ERC-7573 decryption contract on the rollup; the oracle releases the success outcome key for `T`. -- That key is submitted to the L1 locking contract, which transfers the bond to Bank B. If the payment had failed or been cancelled, the failure outcome key would have been used instead and Bank A would reclaim the bond. +These extensions do not change how the contracts decide outcomes: the asset contract still receives an outcome key and either delivers the asset or allows reclaim. ## See also -- [Private Trade Settlement](../approaches/approach-private-trade-settlement.md) -- [Commit and Prove](pattern-commit-and-prove.md) -- [MPC Custody](pattern-mpc-custody.md) -- [Selective Disclosure](pattern-regulatory-disclosure-keys-proofs.md) -- [ERC-7573 spec](https://ercs.ethereum.org/ERCS/erc-7573) \ No newline at end of file +- [ERC-7573 specification](https://ercs.ethereum.org/ERCS/erc-7573) +- [Private Trade Settlement approach](../approaches/approach-private-trade-settlement.md) diff --git a/patterns/pattern-eil.md b/patterns/pattern-eil.md index 3465500..4c2c359 100644 --- a/patterns/pattern-eil.md +++ b/patterns/pattern-eil.md @@ -1,78 +1,109 @@ --- title: "Pattern: EIL (Ethereum Interoperability Layer)" status: draft -maturity: pilot +maturity: concept +type: standard layer: hybrid -privacy_goal: No privacy improvements; provides censorship-resistant cross-L2 execution -assumptions: ERC-4337 accounts, XLP infrastructure with L1 staking, L1 canonical bridge for disputes -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 rollout-plan: ready to be integrated in wallets + works-best-when: - - User needs to execute calls on multiple L2s with one signature - - Assets scattered across chains need to be used without bridging friction - - No gas on destination chain but funds available on source chain + - User needs to execute calls on multiple L2s with one signature. + - Assets scattered across chains need to be used without bridging friction. + - No gas on destination chain but funds available on source chain. avoid-when: - - Contract-to-contract composability required (use crosschain messaging instead) - - High-level intent without knowing specific contract calls (solvers better suited) - - Institutional-scale transfers requiring immediate economic finality -dependencies: [ERC-4337, EIP-7701, RIP-7859] + - Contract-to-contract composability required (use crosschain messaging instead). + - High-level intent without knowing specific contract calls (solvers better suited). + - Institutional-scale transfers requiring immediate economic finality. + context: both +context_differentiation: + i2i: "Between institutions, both counterparties have legal recourse and symmetric trust. Visible call targets and amounts across chains are tolerable given bilateral confidentiality agreements; the value is atomic multi-chain execution without custody intermediaries. Liquidity providers take on slashing risk under L1-enforced dispute rules, so no counterparty depends on operator honesty." + i2u: "The user is asymmetric to any liquidity provider. The L1 dispute mechanism must guarantee funds cannot be stolen regardless of provider behavior; the user's unilateral exit must not require provider cooperation. Public UserOp contents expose end-user activity to MEV extraction and surveillance, making encrypted submission a priority for user-facing deployments." + crops_profile: cr: high - os: yes - privacy: none - security: high + o: yes + p: none + s: high + +crops_context: + cr: "Reaches `high` through a permissionless P2P UserOp mempool where a single honest node is sufficient to propagate intents. Drops if the mempool becomes operator-gated or if liquidity providers coordinate to ignore specific users." + o: "Open specifications (ERC-4337, EIP-7701, RIP-7859) and open-source SDKs. Any actor can register as a liquidity provider by staking on L1, and users can bypass providers by paying gas directly." + p: "No privacy. Token amounts, gas limits, and call targets are visible pre-execution across all involved chains. Could reach `partial` by integrating encrypted UserOps via threshold encryption where cross-L2 intents remain encrypted until ordering is finalized." + s: "Inherits the security of each underlying chain. Liquidity providers face L1 slashing on misbehavior, so user funds cannot be stolen, only face short-term delays. An 8-day unstake window bounds the economic risk window." + +post_quantum: + risk: medium + vector: "Signature schemes used by ERC-4337 accounts (ECDSA, BLS) are broken by a CRQC. HNDL risk is low since UserOp contents are public and non-confidential." + mitigation: "Migrate account validation modules to post-quantum signatures (hash-based or lattice-based) once standardized in EIPs." + +standards: [ERC-4337, EIP-7701, RIP-7859] + +related_patterns: + composes_with: [pattern-native-account-abstraction, pattern-threshold-encrypted-mempool] + alternative_to: [pattern-oif, pattern-cross-chain-privacy-bridge] + see_also: [pattern-forced-withdrawal, pattern-focil-eip7805] + +open_source_implementations: + - url: https://github.com/eth-infinitism/eil-sdk + description: "TypeScript SDK for constructing multichain UserOps and interacting with the liquidity provider mempool." + language: TypeScript --- ## Intent -Account-based cross-L2 interoperability where users sign once and execute transactions directly on multiple chains. XLPs (Crosschain Liquidity Providers) supply gas and liquidity via optimistic atomic swaps, but never execute calls on the user's behalf. +Account-based cross-L2 interoperability where users sign once and execute transactions directly on multiple chains. Crosschain Liquidity Providers supply gas and liquidity via optimistic atomic swaps anchored in an L1 staking contract, but never execute calls on the user's behalf. Dispute resolution on L1 ensures funds cannot be lost or stolen. -## Ingredients +## Components -- ERC-4337 accounts with multichain validation modules (Merkle root over UserOps) -- CrossChainPaymaster contracts on each L2 -- L1CrossChainStakeManager for XLP registration -- XLPs staking on L1 (8-day unstake delay, O(networks) not O(funds)) -- P2P mempool for UserOp propagation -- L1 canonical bridge for dispute resolution +- **ERC-4337 account with multichain validation module** signs a Merkle root over the set of UserOps, letting one signature authorize calls across many chains. +- **CrossChainPaymaster contracts** on each L2 accept vouchers from liquidity providers, pay gas, and release funds on the destination. +- **L1CrossChainStakeManager** tracks liquidity provider registrations and stakes, with an 8-day unstake delay. +- **Liquidity providers** stake on L1 once per network and quote fees via reverse Dutch auction; stake sizing is O(networks), not O(funds moved). +- **P2P UserOp mempool** propagates signed intents and vouchers permissionlessly. +- **L1 canonical bridge** serves as the arbiter for disputes when a liquidity provider misbehaves. ## Protocol -1. Alice finds registered XLPs operating on both source and destination chains -2. Alice signs multichain `UserOp`. On source chain she locks funds in `CrossChainPaymaster`, requests voucher specifying XLP list and fee schedule (reverse Dutch auction). Request is short-lived; funds unlock if no voucher provided promptly -3. XLP claims Alice's source funds by providing signed voucher (commitment for destination). Same voucher that claims source funds releases XLP funds on destination. Source funds remain locked 1 hour before crediting XLP deposit -4. Alice appends XLP voucher to destination `UserOp` signature, submits to destination chain -5. Destination `CrossChainPaymaster` verifies voucher, checks XLP has sufficient deposits, pays gas and gives Alice the funds -6. Alice's calls execute. Flow can traverse any number of L2s using same signature -7. If XLP misbehaves: L1-based dispute mechanism ensures funds cannot be lost or stolen, penalizes violating XLPs, incentivizes other XLPs to prove violations +1. [user] Discover registered liquidity providers operating on both source and destination chains. +2. [user] Sign a multichain UserOp. On the source chain, lock funds in the CrossChainPaymaster and request a voucher specifying provider list and fee schedule via reverse Dutch auction. Funds unlock automatically if no voucher arrives promptly. +3. [operator] A liquidity provider claims the source-chain funds by submitting a signed voucher. The same voucher releases provider funds on the destination. Source funds remain locked for one hour before crediting the provider's deposit. +4. [user] Append the provider voucher to the destination UserOp signature and submit to the destination chain. +5. [contract] Destination CrossChainPaymaster verifies the voucher, checks provider deposits, pays gas, and releases funds to the user. +6. [user] Calls execute on the destination. The same signature can traverse any number of additional L2s using more vouchers. +7. [contract] If a provider misbehaves, the L1 dispute mechanism slashes the violating stake and rewards any other provider that supplies a violation proof. + +## Guarantees & threat model + +Guarantees: + +- Censorship resistance via a permissionless mempool where a single honest node is sufficient to propagate intents. +- No trusted intermediaries: users execute their own calls, and disputes resolve on L1. +- Inherits the security of each underlying chain. Providers cannot steal funds, only face slashing risk. +- One signature authorizes operations across all involved chains. +- Latency matches the slowest underlying chain. -## Guarantees +Threat model: -- No privacy improvements (token amounts and gas limits revealed pre-execution; call targets visible on-chain) -- Censorship resistance via permissionless mempool (single honest node sufficient) -- No trusted intermediaries (users execute directly, disputes resolved via L1) -- Same security as underlying chains (XLPs cannot steal funds, only face slashing risk) -- One signature per operation across all chains -- Minimum latency (as fast as underlying chains) +- Requires the same account implementation or a compatible validation module on every involved chain. +- Requires the same signing key on every chain until an L1 keystore with L1SLOAD is available. +- Capital efficiency cost: one-hour fund lock on the source chain after voucher issuance. +- Reorg risk on destination chains with frequent reorganizations; a deep reorg can invalidate a voucher redemption. +- Out of scope: application-layer confidentiality. Call targets, amounts, and account identities are all visible. ## Trade-offs -- Requires same account implementation or validation module on all chains -- Requires same key on all chains (mitigated long-term via L1 keystore with L1SLOAD) -- 1-hour fund lock on source chain after voucher issuance (capital efficiency cost) -- XLP reorg risk on chains with frequent reorganizations -- Not suitable for contract-to-contract composability (only account-based) -- ERC-4337 overhead until EIP-7701 (Native AA) adoption -- Dispute mechanism adds complexity vs simple bridges -- **CROPS context (both)**: Privacy could reach `full` by integrating encrypted UserOps via threshold encryption where cross-L2 intents remain encrypted until XLP ordering is finalized. In I2I settings, counterparties may tolerate visible call targets and amounts given existing confidentiality agreements. In I2U settings, public UserOp contents expose end-user activity to MEV extraction and surveillance, making encrypted submission a higher priority. +- Not suitable for contract-to-contract composability. The model is account-based only. +- ERC-4337 bundler overhead persists until EIP-7701 (Native AA) adoption. +- Dispute mechanism adds complexity compared to simple bridges; wallets must track open vouchers and their dispute windows. +- Requires wallet-side coordination to discover providers and construct cross-chain Merkle roots before signing. ## Example -Arbitrum Alice wants to mint 1 ETH NFT on Linea. She has 0.8 ETH on Arbitrum and 0.5 ETH on Scroll. Wallet generates 3 UserOps (Arbitrum transfer, Scroll transfer, Linea mint), signs Merkle root once. XLPs provide vouchers on Arbitrum and Scroll, Alice's funds atomic-swapped to Linea, NFT minted, all verified within 2-3 seconds total. +A user wants to mint a 1 ETH NFT on one L2. They hold 0.8 ETH on a second L2 and 0.5 ETH on a third. The wallet builds three UserOps (two transfers and one mint), signs the Merkle root once, and two liquidity providers supply vouchers on the source chains. Funds atomic-swap to the destination, the mint executes, and the whole flow settles within seconds. ## See also -- [Ethrearch post](https://ethresear.ch/t/eil-trust-minimized-cross-l2-interop/23437) -- [Typescript SDK](https://github.com/eth-infinitism/eil-sdk) -- [Yoav Weiss - Trust-Minimized Interop with EIL](https://www.youtube.com/watch?v=kFKvZuXUmQY) +- [Ethresearch post on trust-minimized cross-L2 interop](https://ethresear.ch/t/eil-trust-minimized-cross-l2-interop/23437) +- [Yoav Weiss: Trust-Minimized Interop with EIL (video)](https://www.youtube.com/watch?v=kFKvZuXUmQY) diff --git a/patterns/pattern-erc3643-rwa.md b/patterns/pattern-erc3643-rwa.md index b03447b..611819e 100644 --- a/patterns/pattern-erc3643-rwa.md +++ b/patterns/pattern-erc3643-rwa.md @@ -2,81 +2,100 @@ title: "Pattern: ERC-3643 Tokenized RWAs" status: ready maturity: production +type: standard layer: L1 -privacy_goal: Enforce compliant token transfers with identity verification at contract level -assumptions: ONCHAINID infrastructure, trusted claim issuers, ERC-734/735 key management -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 + works-best-when: - - Regulatory compliance is mandatory - - Need permissioned transfers with identity verification - - Tokenizing real-world assets (bonds, equity, funds) + - Regulatory compliance is mandatory. + - Transfers must be gated by on-chain identity verification. + - Tokenizing real-world assets such as bonds, equity, or funds. avoid-when: - - Full ERC-20 interoperability is needed (unrestricted transfers) - - High-frequency trading with minimal compliance checks -dependencies: [ERC-3643, ONCHAINID, ERC-734, ERC-735] + - Full ERC-20 interoperability with unrestricted transfers is required. + - High-frequency trading with minimal compliance checks. + context: both +context_differentiation: + i2i: "Between institutions, centralized token-agent control (freeze, force-transfer, blacklist) is partially mitigated by bilateral legal agreements between issuer and investor. Both sides have KYC-aligned identities, legal recourse, and symmetric trust; the compliance framework enforces a pre-agreed contractual envelope rather than replacing negotiated terms." + i2u: "End users face freeze and force-transfer risk with no negotiating leverage and no legal parity with the issuer. A user-facing deployment should restrict agent powers to compliance-triggered actions, decentralize claim issuance (for example via permissionless attestations), and pair identity checks with zero-knowledge proofs so user PII never appears on chain." + crops_profile: cr: none - os: partial - privacy: none - security: medium + o: partial + p: none + s: medium + +crops_context: + cr: "Transfers are gated by the identity registry and compliance modules. Any token agent can freeze, force-transfer, or blacklist addresses at will, so censorship resistance is structurally `none`." + o: "Standard specification is open and the reference implementations are source-available, but claim issuer ecosystems are gatekept. Could reach `yes` by requiring copyleft licensing on compliance modules and a permissionless attestation registry for claim issuers." + p: "Identities and transfer parameters are public on chain. Could reach `partial` by replacing on-chain identity checks with zero-knowledge proofs of claim validity, enabling transfer validation without exposing PII." + s: "Rides on correctness of the compliance modules and operational security of the token-agent key. Could reach `high` with multisig governance and time-locked upgrades on the issuer admin path." + +post_quantum: + risk: medium + vector: "ECDSA signatures on agent and holder keys are broken by a CRQC. HNDL risk is moderate since on-chain identity data is public but linkable to off-chain PII." + mitigation: "Migrate agent and governance keys to post-quantum signature schemes; anchor claims via hash-based attestation schemes rather than ECDSA-signed claims." + +standards: [ERC-3643, ERC-734, ERC-735, ERC-8056] + +related_patterns: + composes_with: [pattern-crypto-registry-bridge-ewpg-eas, pattern-regulatory-disclosure-keys-proofs, pattern-zk-kyc-ml-id-erc734-735] + see_also: [pattern-shielding, pattern-compliance-monitoring] --- ## Intent -Enable compliant tokenization of real-world assets with built-in identity management, transfer restrictions, and regulatory compliance enforced at the smart contract level. +Enable compliant tokenization of real-world assets with built-in identity management, transfer restrictions, and regulatory rules enforced at the smart-contract level. Each transfer is gated by an on-chain identity check and a configurable compliance module before the underlying transfer executes. + +## Components + +- **Permissioned token contract** (ERC-3643) exposes an ERC-20 interface but routes every transfer through compliance and identity checks. +- **On-chain identity contract** per participant stores claims (KYC, accreditation, jurisdiction) and exposes verification endpoints. +- **Identity registry** maps wallet addresses to identity contracts and gates who is eligible to hold the token. +- **Compliance module suite** is a pluggable rules engine that evaluates per-transfer restrictions (caps, lockups, eligibility classes). +- **Claim issuers** are off-chain actors that sign claims written into identity contracts; the registry tracks trusted issuers. +- **Token agent** holds administrative powers: freeze, force-transfer, blacklist, supply management, compliance-rule updates. + +## Protocol -## Ingredients +1. [user] Create an on-chain identity and collect signed claims from trusted issuers (KYC, accreditation, jurisdiction). +2. [operator] Deploy the permissioned token with a specific compliance ruleset and transfer restrictions. +3. [operator] Populate the identity registry with eligible participants and their identity contracts. +4. [user] Initiate a transfer to a recipient address. +5. [contract] Validate both sender and receiver against the identity registry and run every compliance module; revert on any failure. +6. [contract] Execute the balance change and emit transfer and compliance events. +7. [regulator] Query the on-chain compliance history to reconcile against regulatory filings. -- **ERC-3643**: Core permissioned token standard with compliance framework - - **ONCHAINID**: Decentralized identity management system for KYC/AML verification - - **T-REX Protocol**: Complete suite of smart contracts for tokenized securities - - **ERC-734/735**: Key and claim management for identity verification - - **Compliance Modules**: Pluggable rules engine for transfer restrictions - - **Identity Registry**: On-chain registry of verified participants +## Guarantees & threat model -## Protocol (concise) +Guarantees: -1. **Identity Setup**: Participants create ONCHAINID with verified claims (KYC, accreditation, jurisdiction) -2. **Token Deployment**: Issue ERC-3643 token with specific compliance rules and transfer restrictions -3. **Registry Population**: Add eligible participants to identity registry with required credentials -4. **Transfer Initiation**: Token holder initiates transfer to eligible recipient -5. **Compliance Check**: Smart contract validates both sender and receiver against transfer rules -6. **Execution**: Transfer executes only if all compliance conditions are met; reverts if failed -7. **Audit Trail**: All transfers and compliance checks logged on-chain for regulatory reporting +- Every transfer passes identity verification and compliance checks before execution. +- Transfer rules enforce KYC/AML status, investor accreditation, and jurisdictional restrictions automatically. +- Full on-chain audit trail of ownership changes, freezes, and force-transfers. +- Interface compatibility with ERC-20 tooling, with additional transfer restrictions opaque to the caller. -## Guarantees +Threat model: -- **Identity Verification**: All token holders verified through ONCHAINID system -- **Regulatory Compliance**: Transfer rules enforce KYC/AML, investor accreditation, jurisdiction restrictions -- **Selective Permissions**: Granular control over who can hold, transfer, and receive tokens -- **Audit Transparency**: Complete on-chain history of ownership and compliance status -- **Interface Compatibility**: Uses ERC-20 interface but with additional transfer restrictions +- Trusted claim issuers: compromised issuers can mint false claims, enabling ineligible holders to pass compliance checks. +- Token-agent key compromise is catastrophic: the attacker can freeze, force-transfer, or seize any balance. +- On-chain identity links all token activity to KYC data; a privacy leak at the claim issuer side cascades to on-chain positions. +- Out of scope: transaction-level confidentiality. Amounts, positions, and counterparties remain visible on chain. ## Trade-offs -- **Complexity**: More complex than simple ERC-20 tokens, requires identity infrastructure -- **Gas Costs**: Additional compliance checks increase transaction costs -- **Permissioned Nature**: Not suitable for permissionless DeFi applications -- **Centralized Control**: Token agents can freeze, force-transfer, and blacklist addresses; admin key compromise affects all holders -- **Regulatory Dependency**: Compliance rules must be maintained and updated -- **Privacy Limitation**: Identity verification may conflict with transaction privacy needs -- **Limited support for Stock Split events**: Stock split events mint new tokens, which is infeasible for larger amounts of token holders. Reverse stock splits introduce uncertainties around burning/transferring tokens which are not modelled. [ERC-8056](https://eips.ethereum.org/EIPS/eip-8056) proposes an extension to ERC-20 tokens that enables issuers to apply an updatable multiplier to the UI, efficiently handling stock splits and reverse stock splits. -- **CROPS context (both)**: CR could reach `medium` if claim issuers are decentralized via permissionless attestation (e.g. EAS-based), removing institutional gatekeeping. OS improves to `yes` by requiring all compliance modules use copyleft licensing with a transparent on-chain registry of approved issuers. Privacy could reach `full` by replacing on-chain identity checks with ZK proofs of claim validity, enabling transfer validation without exposing PII. Security improves to `high` by upgrading to multisig governance with time-locked upgrades. In I2I settings, centralized token-agent control is partially mitigated by legal agreements between issuer and investors. In I2U settings, end-users face freeze and force-transfer risk with no negotiating leverage, making decentralized claim issuance and governance safeguards more relevant. +- More complex than plain ERC-20 tokens; requires identity infrastructure and claim issuer onboarding. +- Additional compliance checks on every transfer raise gas costs. +- Not suitable for permissionless DeFi composition. Many protocols will reject permissioned tokens. +- Compliance rules must be maintained and updated as regulations evolve, which requires ongoing governance. +- Limited support for stock split events: ERC-8056 proposes an extension that applies a UI multiplier rather than minting new tokens for each holder. ## Example -"Corporation issues €100M tokenized bond series with ERC-3643 compliance": -• Corporation deploys ERC-3643 bond token with investor accreditation requirements -• Qualified institutional investors complete KYC process and receive ONCHAINID credentials -• Bond tokens distributed to verified investors' addresses in identity registry -• Secondary trading restricted to other qualified investors meeting compliance rules -• All transfers automatically enforce regulatory requirements without manual oversight +An issuer tokenizes a bond as a permissioned token with investor accreditation requirements. Qualified institutional investors complete KYC and register identity contracts. Bond tokens are distributed to verified investors through the identity registry. Secondary trading is restricted by the compliance module to other qualified investors meeting the issuance rules. All transfers enforce regulatory requirements without manual oversight. ## See also - [Private Bonds Approach](../approaches/approach-private-bonds.md) -- [Crypto Registry Bridge eWpG EAS](pattern-crypto-registry-bridge-ewpg-eas.md) -- [Regulatory Disclosure Keys Proofs](pattern-regulatory-disclosure-keys-proofs.md) -- [ZK KYC ML ID ERC734-735](pattern-zk-kyc-ml-id-erc734-735.md) -- [ERC-3643 Documentation](https://docs.erc3643.org/erc-3643) +- [ERC-3643 documentation](https://docs.erc3643.org/erc-3643) +- [ERC-8056 UI-multiplier stock split extension](https://eips.ethereum.org/EIPS/eip-8056) diff --git a/patterns/pattern-focil-eip7805.md b/patterns/pattern-focil-eip7805.md index d30af1d..314f03e 100644 --- a/patterns/pattern-focil-eip7805.md +++ b/patterns/pattern-focil-eip7805.md @@ -1,82 +1,106 @@ --- title: "Pattern: FOCIL - Fork-Choice Enforced Inclusion Lists" status: draft -maturity: experimental +maturity: testnet +type: standard layer: L1 -privacy_goal: No privacy; provides censorship resistance via forced transaction inclusion -assumptions: EIP-7805 adoption, 1-of-16 honest IL committee member, consensus layer changes -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 rollout-plan: glamsterdam or later forks + works-best-when: - - Censorship resistance is critical - - Block builders concentrate power and may censor transactions - - Same-slot transaction inclusion guarantees needed + - Censorship resistance is critical and must not depend on builder honesty. + - Block builders concentrate power and may selectively censor transactions. + - Same-slot inclusion guarantees are required (no one-slot delay). avoid-when: - - Mempool visibility of transaction details is unacceptableh -dependencies: [EIP-7805] + - Mempool visibility of transaction details is unacceptable (combine with encrypted mempools instead). + context: both +context_differentiation: + i2i: "Between institutions, inclusion guarantees protect bilateral settlement against builder-level censorship, but trade details remain publicly visible in the mempool. Acceptable where counterparties already publish identities and amounts; inadequate where institutional trades must stay confidential from competitors. Pair with encrypted-mempool patterns to cover trade details between institutional counterparties." + i2u: "The user is asymmetric to block builders and cannot negotiate inclusion directly. The 1-of-16 committee honesty assumption provides protocol-level protection against OFAC-style censorship or MEV-motivated exclusion. Public transaction details still expose end-user activity to front-running and surveillance; encrypted submission is a priority for user-facing deployments." + crops_profile: cr: high - os: yes - privacy: none - security: high + o: yes + p: none + s: high + +crops_context: + cr: "Reaches `high` through a 1-of-16 committee honesty assumption: a single honest IL committee member suffices to force-include a transaction. Drops if the P2P gossip network is partitioned or if committee selection is subverted." + o: "Fully open specification (EIP-7805) implemented in consensus layer clients. Any staked validator rotates through the committee, and any node can verify IL satisfaction." + p: "No privacy: transaction details remain fully visible in the mempool and on chain. Could reach `partial` by combining with encrypted mempools so inclusion lists carry ciphertexts rather than plaintext transactions." + s: "Inherits the security of Ethereum consensus. Fork-choice enforcement means non-compliant blocks cannot become canonical, so the guarantee is as strong as the underlying finality mechanism." + +post_quantum: + risk: medium + vector: "BLS signatures used for committee IL signatures and attestations are broken by a CRQC. HNDL risk is low since IL contents are public." + mitigation: "Migrate consensus signatures to a post-quantum scheme (hash-based or lattice-based) as part of the broader Ethereum consensus PQ transition." + +standards: [EIP-7805] + +related_patterns: + composes_with: [pattern-pretrade-privacy-encryption, pattern-threshold-encrypted-mempool, pattern-private-stablecoin-shielded-payments] + alternative_to: [pattern-private-transaction-broadcasting] + see_also: [pattern-verifiable-attestation, pattern-privacy-l2s] + +open_source_implementations: + - url: https://eips.ethereum.org/EIPS/eip-7805 + description: "EIP-7805 specification and reference implementation notes." + language: Specification --- ## Intent -FOCIL (Fork-Choice Enforced Inclusion Lists) is an EIP that enables a committee of 16 validators to force-include transactions in blocks, preventing censorship by sophisticated block builders. FOCIL itself does not provide privacy, transactions remain fully visible in the public mempool and on-chain. It only guarantees that transactions cannot be censored once submitted to the mempool. +Prevent censorship of Ethereum transactions by sophisticated block builders. A committee of 16 validators per slot can force-include transactions in the next block; non-compliant blocks fail fork-choice and cannot reach finality. The pattern provides no privacy on its own: transactions remain fully visible in the mempool and on chain. It guarantees only that a transaction cannot be censored once it reaches the public mempool. -## Ingredients +## Components -- **Standards**: EIP-7805 (FOCIL specification) -- **Infra**: Ethereum consensus layer with fork-choice enforcement, P2P gossip network for IL propagation -- **Off-chain**: IL committee selection mechanism, equivocation detection +- **IL committee** of 16 validators selected per slot to construct inclusion lists for the following slot. +- **Inclusion list** is a signed, bounded set of transactions (8 KiB max per member) that the next block must include. +- **P2P gossip network** propagates signed inclusion lists across the validator set. +- **Fork-choice enforcement** is the consensus-layer rule: attesters refuse to attest to blocks that fail to satisfy observed ILs. +- **Equivocation detection** identifies committee members publishing conflicting ILs and discards their contributions. -## Protocol (concise) +## Protocol -1. Committee Selection (Slot N), a committee of 16 validators is selected for slot N to build ILs for slot N+1 -2. IL Construction (t=0-8s), committee members monitor the public mempool and construct ILs (max 8 KiB) containing transactions they want force-included -3. IL Broadcasting (t=8s), Committee members gossip their signed ILs over the P2P network after processing slot N's block -4. View Freeze (t=9s), All validators freeze their view of ILs; no new ILs accepted after this deadline; equivocation detection active -5. Block Building (t=11s), Builder for slot N+1 collects all ILs and updates execution payload to include IL transactions (anywhere in block) -6. Block Proposal (Slot N+1, t=0s), Proposer broadcasts block with IL transactions included -7. Attestation (t=4s), Attesters verify all non-equivocated IL transactions are included (or invalid); only attest if satisfied -8. Fork-Choice Enforcement, Blocks failing to satisfy ILs receive no attestations and cannot become canonical +1. [sequencer] A committee of 16 validators is selected for slot N to build inclusion lists for slot N+1. +2. [sequencer] Between t=0s and t=8s of slot N, committee members monitor the public mempool and assemble inclusion lists of transactions they want force-included. +3. [sequencer] At t=8s, committee members broadcast signed inclusion lists over the P2P network after processing slot N's block. +4. [sequencer] At t=9s, validators freeze their view of inclusion lists; later ILs are rejected, and equivocators are flagged. +5. [sequencer] At t=11s, the builder for slot N+1 collects observed inclusion lists and constructs an execution payload that includes their transactions anywhere in the block. +6. [sequencer] At t=0s of slot N+1, the proposer broadcasts the block containing the IL transactions. +7. [sequencer] At t=4s, attesters verify that every non-equivocated IL transaction is included or provably invalid; otherwise they withhold attestations. +8. [contract] Fork-choice rejects any block that fails IL satisfaction, so a non-compliant block cannot become canonical. -## Guarantees +## Guarantees & threat model -- **Censorship Resistance Under Builder Centralization:** 1-out-of-16 honesty assumption—single honest IL committee member prevents transaction censorship by decoupling block building from validation -- **Same-Slot:** No delay—constraints for slot N+1 include transactions from slot N (vs 1-slot delay in forward ILs) -- **Anywhere-in-Block:** Builder chooses transaction placement, reducing incentive for side channels -- **Fork-Choice Enforced:** Non-compliant blocks cannot achieve finality; attesters reject blocks not satisfying ILs -- **No Privacy:** Transaction details remain fully visible in mempool and on-chain +Guarantees: -## Trade-offs +- Censorship resistance under builder centralization via a 1-of-16 committee honesty assumption. +- Same-slot inclusion: constraints for slot N+1 include transactions visible in slot N (no one-slot delay). +- Builder flexibility: the builder chooses placement of IL transactions within the block, reducing incentives for side channels. +- Fork-choice enforced: non-compliant blocks receive no attestations and cannot finalize. -- **Performance:** Additional bandwidth for IL gossip (up to 16 × 8 KiB per slot); potential O(n²) validity checks if naively implemented -- **Liveness Risk:** Builder must be well-connected to IL committee; insufficient time between view freeze (t=9s) and block broadcast risks missed ILs -- **Equivocation Handling:** P2P rule allows forwarding up to 2 ILs per committee member; equivocators ignored but bandwidth can double in worst case -- **No Direct Incentives:** Relies on altruistic behavior—no explicit rewards for IL committee members -- **Complexity:** Requires consensus layer fork-choice changes, execution layer validation, and coordinated P2P network updates -- **CROPS context (both)**: Privacy could reach `full` by combining with encrypted mempools, where transactions in inclusion lists remain encrypted until post-commitment, hiding amounts and counterparties while preserving censorship resistance. In I2I, encrypted inclusion lists protect trade details between institutional counterparties from competing firms. In I2U, end users gain protection against front-running and transaction surveillance by block builders. +Threat model: -## Example +- At least one honest and well-connected IL committee member per slot; the P2P network reliably delivers their list before the view-freeze deadline. +- Non-malicious builder with sufficient bandwidth between view freeze (t=9s) and block broadcast; builders disconnected from the committee can miss IL transactions. +- No privacy protection. Transaction details remain publicly visible throughout the process. +- Out of scope: builders that censor the entire mempool before any committee member sees a transaction; encrypted mempools are required to defend against that. + +## Trade-offs -**Institutional Payment Censorship Resistance (No Privacy):** +- Additional bandwidth: up to 16 × 8 KiB inclusion-list gossip per slot, plus potential O(n^2) validity checks if naively implemented. +- Liveness risk: insufficient time between view freeze and block broadcast can cause builders to miss ILs, especially for poorly-connected builders. +- Equivocation handling: the P2P rule allows forwarding up to two inclusion lists per committee member, so bandwidth can double in the worst case. +- No explicit incentives: the pattern relies on altruistic behavior; there are no direct rewards for IL committee members. +- Complexity: requires coordinated changes across consensus-layer fork-choice rules, execution-layer validation, and the P2P network. -1. Bank A submits stablecoin payment transaction (€5M EURC transfer) to public mempool at t=0s of slot N, transaction details fully visible to all observers -2. IL committee member (validator 42) sees Bank A's public transaction and includes it in their IL, broadcasts at t=8s -3. View freezes at t=9s—all validators store validator 42's IL containing Bank A's payment -4. Builder for slot N+1 collects IL at t=11s, verifies Bank A has sufficient balance/correct nonce, includes payment in block -5. Attesters at t=4s verify Bank A's payment is in block (or invalid); all attest to block -6. Result: Even if builder wants to censor Bank A (OFAC compliance, MEV extraction, competitive intelligence), fork-choice enforcement prevents censorship -7. Privacy impact: NONE, amount (€5M), counterparty, and timing remain publicly visible throughout the process +## Example -**Note:** For privacy-preserving institutional payments, FOCIL must be combined with other patterns like [Private Stablecoin Shielded Payments](./pattern-private-stablecoin-shielded-payments.md) or [Privacy L2s](./pattern-privacy-l2s.md). +A bank submits a €5M stablecoin transfer to the public mempool at t=0s of slot N. Transaction details are fully visible to all observers. An IL committee member includes it in their inclusion list and broadcasts at t=8s. At t=9s the view freezes. The slot N+1 builder collects the IL at t=11s and includes the transfer in the block. Attesters verify inclusion at t=4s. Even if the builder would have preferred to censor the payment (for OFAC compliance, MEV extraction, or competitive intelligence), fork-choice enforcement makes censorship non-viable. Privacy impact is zero: the €5M amount, counterparty, and timing remain publicly visible throughout. ## See also -- [Pre-trade Privacy (Shutter/SUAVE)](./pattern-pretrade-privacy-encryption.md) — complementary pattern for hiding transaction content before inclusion -- [EIP-7547](https://eips.ethereum.org/EIPS/eip-7547) — forward inclusion lists (1-slot delay vs same-slot in FOCIL) -- [Private Payments Approach](../approaches/approach-private-payments.md) — FOCIL ensures inclusion; private payments hide content -- [Verifiable Attestation](./pattern-verifiable-attestation.md) — attesters validate IL satisfaction before attesting +- [EIP-7547: forward inclusion lists](https://eips.ethereum.org/EIPS/eip-7547) for a one-slot-delay alternative +- [Private Payments Approach](../approaches/approach-private-payments.md) diff --git a/patterns/pattern-forced-withdrawal.md b/patterns/pattern-forced-withdrawal.md index 68d58b9..036aa56 100644 --- a/patterns/pattern-forced-withdrawal.md +++ b/patterns/pattern-forced-withdrawal.md @@ -1,139 +1,123 @@ --- title: "Pattern: Forced Withdrawal (L1 Escape Hatch)" status: draft -maturity: PoC +maturity: production +type: standard layer: hybrid -privacy_goal: Let end users recover assets on L1 without operator cooperation, within bounded time -assumptions: L1 escape hatch contract deployed, user retains note data and Merkle path, state roots anchored periodically on L1 -last_reviewed: 2026-04-08 +last_reviewed: 2026-04-22 + works-best-when: - - Users need a guaranteed exit from L2 or shielded pools even if the operator is offline or hostile - - Institutional deployments must demonstrate non-custodial protections for regulatory acceptance - - Censorship resistance is a hard requirement in I2U contexts + - Users need a guaranteed exit from L2 or shielded pools even if the operator is offline or hostile. + - Institutional deployments must demonstrate non-custodial protections for regulatory acceptance. + - Censorship resistance is a hard requirement in I2U contexts. avoid-when: - - L1-native operations where no intermediary can censor (e.g., direct shielding on L1) - - The cost of L1 proof verification exceeds the value of the assets at stake -dependencies: [L1 anchor contract, zero-knowledge proof system, Merkle commitment tree] + - L1-native operations where no intermediary can censor (for example, direct shielding on L1). + - The cost of L1 proof verification exceeds the value of the assets at stake. + context: both +context_differentiation: + i2i: "Between institutions, neither counterparty can lock the other's funds by withholding operator cooperation. Institutional deployments may accept upgrade risk under bilateral governance (both parties on the multisig), since legal recourse bounds the downside." + i2u: "For end users, unilateral exit is non-optional. The CROPS rubric requires a concrete user-initiated escape path for anything above `cr: low`. The user must be able to reconstruct their position, build the required proof, and submit it without operator cooperation; any step that depends on the operator breaks the guarantee." + crops_profile: cr: high - os: yes - privacy: partial - security: high + o: yes + p: partial + s: high + +crops_context: + cr: "Reaches `high` only when the escape-hatch contract has meaningful upgrade delays (Stage 1 or higher, 7+ days). Instant upgrades let the operator remove the hatch, which invalidates the rating entirely. DA withholding and proving liveness are liveness constraints documented under Trade-offs; they do not change the CR score, which measures whether a single party can exclude a user at the protocol level." + o: "Forced-withdrawal contracts are typically open-source and verifiable. Users can run their own prover and submit directly to L1. Proving-key hosting for Groth16 constructions is a soft dependency: if hosting goes offline, users may struggle to generate valid proofs." + p: "For privacy systems, the zero-knowledge proof hides which commitment is withdrawn; no KYC disclosure or transaction history reveal is needed. The L1 withdrawal still reveals that an exit happened at a specific time for a specific amount." + s: "Rides on the soundness of the proof system, correctness of the verifier, and honest state-root anchoring on L1. For optimistic constructions, a 7-day challenge window plus honest challengers are required. PQ exposure applies to ZK systems over BN254." + +post_quantum: + risk: high + vector: "ZK systems relying on elliptic-curve pairings (Groth16, PLONK over BN254) are broken by a CRQC. An attacker with quantum capability could forge withdrawal proofs once state roots anchored on L1 become historical." + mitigation: "STARKs with hash-based commitments are not affected. See [Post-Quantum Threats](../domains/post-quantum.md)." + +standards: [EIP-4844] + +related_patterns: + requires: [pattern-zk-proof-systems] + composes_with: [pattern-shielding, pattern-privacy-l2s, pattern-plasma-stateless-privacy] + see_also: [pattern-modular-privacy-stack, pattern-permissionless-spend-auth] --- ## Intent -When an L2 sequencer, relayer, or operator becomes unavailable, users need a unilateral path back to L1. Three pillars must hold simultaneously: the user has enough data to reconstruct their position (DA), an L1 contract accepts proof of that position and releases funds (verifier + liquidity), and the user can build the required proof on hardware they control (proving infra). If any one leg fails, the escape hatch is ineffective. +When an L2 sequencer, relayer, or operator becomes unavailable, users need a unilateral path back to L1. Three pillars must hold simultaneously: the user has enough data to reconstruct their position, an L1 contract accepts proof of that position and releases funds, and the user can build the required proof on hardware they control. If any one leg fails, the escape hatch is ineffective. -## Ingredients +## Components -### Data availability - -The user needs enough state to prove "I own X" against the last L1-anchored root. - -- **Account-model rollups:** Merkle proof of account balance. If transaction data is posted to L1 (calldata or blobs), anyone can reconstruct any account's state. -- **UTXO/note-model privacy systems:** note preimage, nullifier secret, Merkle path. The on-chain data is encrypted; "available" does not mean "usable" without the user's decryption keys. -- **Client-side architectures (Plasma):** the user is responsible for storing data locally. Some implementations offer backup storage servers (e.g., INTMAX), but these are convenience layers, not protocol guarantees. If local data is lost and no backup is reachable, funds are unrecoverable. +- **Data availability source** lets the user reconstruct their position. Can be L1 calldata, L1 blobs, an external DA layer, a validium DA committee, or client-side storage. +- **L1 state-root oracle** stores the last verified L2 state root. Validity rollups anchor with a ZK proof; optimistic rollups anchor after a challenge period survives. +- **Proof verifier contract** accepts Merkle proofs (transparent systems) or zero-knowledge proofs (privacy systems) and checks them against the anchored root. +- **Nullifier registry** records completed withdrawals to prevent double-claims. +- **Bridge liquidity contract** holds the locked deposits that forced exits draw from; no new funds are created. +- **Client-side prover** with the required circuit, proving keys or SRS artifacts, and local compute (roughly 0.5 to 3 seconds native or 20 to 30 seconds in browser WASM on current hardware). Where the data lives determines the trust assumption: -| Strategy | Trust assumption | What breaks | +| DA strategy | Trust assumption | Failure mode | | ----------------------- | ------------------------------------- | --------------------------------- | | L1 calldata | Ethereum consensus | Nothing (permanent, expensive) | -| L1 blobs (EIP-4844) | Ethereum + archival within ~18 days | Pruned if nobody archives | -| External DA Layer | DA Layer liveness + economic security | DA Layer offline or withholds | -| DA committee (Validium) | Honest committee majority | Committee withholds; funds frozen | -| Client-side | The user | User loses data = funds gone | - -For privacy systems, even with perfect DA, the user faces a five-step gap between "data exists" and "exit succeeds": raw byte access, data parsing (the rollup's compression format), state derivation, proof generation, L1 submission. Each step can independently block the exit. - -See [L2Beat DA Risk Framework](https://forum.l2beat.com/t/the-data-availability-risk-framework/318). - -### L1 verifier contract - -Three components on the L1 side: - -- **State root oracle:** stores the last verified L2 state root. For validity rollups, this root was accompanied by a zero-knowledge proof. For optimistic rollups, it survived a challenge period (typically 7 days). -- **Proof verification:** accepts Merkle proofs (transparent systems) or zero-knowledge proofs (privacy systems) and checks them against the anchored root. -- **Nullifier registry:** records completed withdrawals to prevent double-claims. - -Liquidity comes from the bridge contract's locked deposits. No new funds are created. Pending transactions after the last anchored root are unprovable and effectively lost. DeFi positions (LP tokens, lending, vaults) require custom "resolver" contracts to map complex storage slots to withdrawable amounts; most protocols have none, meaning those positions may be unescapable ([Zircuit, 2025](https://arxiv.org/html/2503.23986v1)). +| L1 blobs (EIP-4844) | Ethereum plus archival within ~18 days | Pruned if nobody archives | +| External DA layer | DA layer liveness plus economic security | DA layer offline or withholds | +| DA committee (validium) | Honest committee majority | Committee withholds; funds frozen | +| Client-side | The user | User loses data; funds gone | -### Proving infrastructure +For privacy systems, even with perfect DA the user faces a five-step gap between "data exists" and "exit succeeds": raw byte access, data parsing (the rollup's compression format), state derivation, proof generation, and L1 submission. Each step can independently block the exit. DeFi positions (LP tokens, lending, vaults) require custom resolver contracts to map complex storage slots to withdrawable amounts; most protocols have none. -What the user must produce depends on the construction: +## Protocol -| Construction | Proof required | User-side effort | -| ------------------------------ | ----------------------------------------- | ------------------------------------ | -| Optimistic rollup | None: sign an L2 tx, submit to L1 inbox | Trivial | -| Validity rollup (transparent) | Merkle inclusion proof | Low | -| Privacy rollup / shielded pool | Full zero-knowledge proof of commitment ownership | High (seconds to minutes of compute) | +1. [user] Detect operator unresponsiveness or censorship (for example, withdrawal requests ignored past a threshold). +2. [user] Retrieve the latest L1-anchored state root and your position data (note, Merkle path, nullifier secret for privacy systems; account state for transparent systems). +3. [prover] Generate the required proof: a Merkle witness for transparent systems, a zero-knowledge proof for privacy systems. +4. [user] Submit the proof and nullifier to the L1 escape-hatch contract, directly or via any willing relayer. +5. [contract] Verify the proof against the anchored root, check the nullifier is unspent, and start the withdrawal. +6. [contract] Enforce the construction-dependent delay before claim. Optimistic rollups wait a challenge period (typically 7 days); validity rollups wait an operator-liveness timeout (hours to days). +7. [contract] Record the nullifier on L1 to prevent double-withdrawal; the operator must account for this forced exit upon resumption. -For privacy escapes, users need circuit source code, access to proving keys or SRS artifacts (which can be large for Groth16), and sufficient local compute (roughly 0.5–3s native or 20–30s in browser WASM on current hardware). STARKs with transparent setup remove ceremony artifact dependencies. If Groth16 proving-key hosting goes offline, users may be unable to generate valid proofs. - -## Protocol (concise) - -1. User detects operator unresponsiveness or censorship (withdrawal requests ignored past a threshold) -2. User retrieves the latest L1-anchored state root and their position data (note, Merkle path, nullifier secret for privacy systems; account state for transparent) -3. User generates the required proof. Merkle witness for transparent systems, zero-knowledge proof for privacy systems -4. User submits the proof and nullifier to the L1 escape hatch contract (directly or via any willing relayer) -5. The contract verifies the proof against the anchored root, checks the nullifier is unspent, and starts the withdrawal -6. A construction-dependent delay follows before the user can claim funds on L1. For optimistic rollups: a challenge period (typically 7 days) during which fraud proofs can invalidate the state root. For validity rollups: the state root is already proven, so the delay is an operator liveness timeout (hours to days, protocol-configurable) plus any safety buffer -7. The nullifier is recorded on L1 to prevent double-withdrawal; the operator must account for this forced exit upon resumption - -## Guarantees +## Guarantees & threat model How strong the escape guarantee is depends on the construction class: -| | Validity rollup | Optimistic rollup | Privacy rollup | L1-native privacy | -| ----------------------- | ------------------ | ------------------------------ | ---------------------------------- | ---------------------- | -| State freshness | Latest proven root | Root must survive 7d challenge | Latest proven root | Real-time | -| Proof effort | Merkle witness | None (force-include tx) | Full zero-knowledge proof | Full zero-knowledge proof (always) | -| DA risk | Low if on-chain | Low if on-chain | High (encrypted state) | None | -| Escape without operator | Yes | Yes | Partial (may need bonded proposer) | N/A: no operator | - -When all three pillars hold: - -- **Bounded recovery time:** funds recoverable within a protocol-defined window, whether or not the operator comes back -- **No operator cooperation:** the L1 contract enforces withdrawal autonomously -- **Identity not required to exit:** for privacy systems, the zero-knowledge proof hides which commitment is being withdrawn. No KYC disclosure or transaction history reveal needed -- **I2I:** neither counterparty can lock the other's funds by withholding operator cooperation -- **I2U:** end users can exit on their own without institutional cooperation +| | Validity rollup | Optimistic rollup | Privacy rollup | L1-native privacy | +| ----------------------- | ------------------ | ------------------------------ | ---------------------------------- | ------------------------ | +| State freshness | Latest proven root | Root must survive 7d challenge | Latest proven root | Real-time | +| Proof effort | Merkle witness | None (force-include tx) | Full zero-knowledge proof | Full zero-knowledge proof | +| DA risk | Low if on-chain | Low if on-chain | High (encrypted state) | None | +| Escape without operator | Yes | Yes | Partial (may need bonded proposer) | Not applicable (no operator) | -## Trade-offs - -**Upgrade risk:** 86% of 129 L2 projects allow instant contract upgrades without exit windows ([Ethical Risk Analysis of L2 Rollups, 2025](https://arxiv.org/html/2512.12732v1)). An escape hatch the operator can remove via upgrade provides no meaningful guarantee. [L2Beat Stages](https://medium.com/l2beat/introducing-stages-a-framework-to-evaluate-rollups-maturity-d290bb22befe) requires 7-day (Stage 1) or 30-day (Stage 2) upgrade delays, minus any withdrawal delay. - -**CROPS context (`cr: high`):** the rating holds only when the escape hatch contract has meaningful upgrade delays (Stage 1+ / 7 days minimum); instant upgrades let the operator remove the hatch, which invalidates `cr: high` entirely. In I2U, unilateral exit is non-optional: the CR rubric requires a concrete user escape path for anything above `low`. In I2I, institutional deployments may accept upgrade risk under bilateral governance (both parties on the multisig). DA withholding and proving liveness, documented as separate trade-offs below, are operational/liveness constraints, not censorship: they do not change the CR score, which measures whether a single party can exclude a user at the protocol level. +Guarantees: -**DA withholding:** validium DA committees can freeze all funds by refusing to share state. External DA Layers add a liveness dependency. On-chain calldata/blobs are immune but expensive. For privacy systems, data can sit on-chain yet be useless without decryption keys. +- Bounded recovery time: funds recoverable within a protocol-defined window whether or not the operator comes back. +- No operator cooperation required. The L1 contract enforces withdrawal autonomously. +- For privacy systems, identity is not revealed at exit. The zero-knowledge proof hides which commitment is being withdrawn. -**State freshness gap:** users can prove against the most recently anchored root. Any transactions after that root are lost. Anchoring intervals range from minutes (validity rollups) to hours. +Threat model: -**Mass exit:** everyone hits L1 at once: gas prices spike, users with no L1 ETH cannot participate, and leveraged DeFi positions may create claims exceeding underlying bridge deposits. +- State-root honesty and correct challenge-window enforcement on L1. +- Non-censoring L1 inclusion path. The escape transaction must be includable on L1 regardless of L2 operator status. +- Upgrade governance on the escape-hatch contract. An operator that can instantly upgrade the contract can also remove the escape hatch. +- Out of scope: positions that rely on custom DeFi resolver contracts where no resolver exists; those balances are effectively unescapable. -**Proving liveness:** for privacy systems, the user must retain their secrets and run a compatible prover. The prover code must be open-source, deterministically compilable, and match the L1 verifier's expected proof format. A version mismatch = funds frozen until governance acts. Browser WASM proving works but is 5-15x slower than native. +## Trade-offs -**PQ exposure:** ZK systems relying on elliptic-curve pairings (Groth16/PLONK over BN254) are vulnerable to CRQC; see [Post-Quantum Threats](../domains/post-quantum.md). STARKs using hash-based commitments are not affected. +- **Upgrade risk:** 86% of 129 L2 projects allow instant contract upgrades without exit windows ([Ethical Risk Analysis of L2 Rollups, 2025](https://arxiv.org/html/2512.12732v1)). An escape hatch the operator can remove via upgrade provides no meaningful guarantee. L2Beat Stages requires 7-day (Stage 1) or 30-day (Stage 2) upgrade delays, minus any withdrawal delay. +- **DA withholding:** validium DA committees can freeze all funds by refusing to share state. External DA layers add a liveness dependency. On-chain calldata and blobs are immune but expensive. For privacy systems, data can sit on-chain yet be useless without decryption keys. +- **State freshness gap:** users can prove only against the most recently anchored root. Any transactions after that root are lost. Anchoring intervals range from minutes (validity rollups) to hours. +- **Mass exit:** everyone hits L1 at once. Gas prices spike, users with no L1 ETH cannot participate, and leveraged DeFi positions may create claims exceeding underlying bridge deposits. +- **Proving liveness:** for privacy systems, the user must retain secrets and run a compatible prover. The prover code must be open-source, deterministically compilable, and match the L1 verifier's expected proof format. A version mismatch means funds are frozen until governance acts. Browser WASM proving works but is 5 to 15 times slower than native. ## Example -**Bank X operates a private payment L2 for its clients. The sequencer goes offline.** - -1. Client C holds 500 000 USDC in shielded notes on the L2; withdrawal requests to the sequencer time out -2. Client C retrieves the latest state root anchored on L1 and builds a Merkle inclusion proof for their commitment -3. Client C generates a ZK ownership proof and submits it to the L1 escape hatch contract (~300 000 gas) -4. After the 7-day challenge period, Client C claims 500 000 USDC on L1 to a fresh address -5. The L1 transaction reveals that _someone_ withdrew 500 000 USDC, but not which client or which L2 transactions funded the balance +A bank operates a private payment L2 for its clients. The sequencer goes offline. A client holds 500 000 USDC in shielded notes on the L2 and their withdrawal requests time out. The client retrieves the latest state root anchored on L1 and builds a Merkle inclusion proof for their commitment. They generate a ZK ownership proof and submit it to the L1 escape-hatch contract (~300 000 gas). After the 7-day challenge period, the client claims 500 000 USDC on L1 to a fresh address. The L1 transaction reveals that someone withdrew 500 000 USDC, but not which client or which L2 transactions funded the balance. ## See also -- [Shielded ERC-20 Transfers](pattern-shielding.md): shielded pools whose CR depends on forced withdrawal -- [Privacy L2s](pattern-privacy-l2s.md): L2 architectures where sequencer censorship is a risk -- [Stateless Plasma Privacy](pattern-plasma-stateless-privacy.md): Plasma exit games as a specific instantiation -- [Modular Privacy Stack](pattern-modular-privacy-stack.md): forced withdrawal as the Settlement-layer safety net -- [ZK Proof Systems](pattern-zk-proof-systems.md): proof system taxonomy and PQ safety - [L2Beat Stages Framework](https://l2beat.com/stages): maturity classification for rollup escape hatches - [A Practical Rollup Escape Hatch Design (Zircuit, 2025)](https://arxiv.org/html/2503.23986v1): resolver contracts for DeFi positions -- [L2Beat DA Risk Framework](https://forum.l2beat.com/t/the-data-availability-risk-framework/318): DA Layer risk evaluation methodology +- [L2Beat DA Risk Framework](https://forum.l2beat.com/t/the-data-availability-risk-framework/318): DA layer risk evaluation methodology +- [Introducing Stages (Medium)](https://medium.com/l2beat/introducing-stages-a-framework-to-evaluate-rollups-maturity-d290bb22befe) diff --git a/patterns/pattern-hybrid-public-private-modes.md b/patterns/pattern-hybrid-public-private-modes.md index 269f8f2..f5b7d2e 100644 --- a/patterns/pattern-hybrid-public-private-modes.md +++ b/patterns/pattern-hybrid-public-private-modes.md @@ -1,120 +1,101 @@ --- title: "Pattern: Hybrid Public-Private Modes" status: draft -maturity: PoC +maturity: concept +type: standard layer: hybrid -privacy_goal: Enable per-transaction and per-counterparty selection between public and private execution -assumptions: Volition-style architecture or dual-chain setup, policy engine for mode routing, compliant token standards -last_reviewed: 2026-01-16 +last_reviewed: 2026-04-22 + works-best-when: - - Different legs of a trade have different privacy requirements (e.g., private cash, public asset). + - Different legs of a trade have different privacy requirements (for example, private cash, public asset). - Counterparties have heterogeneous compliance regimes requiring flexible disclosure. - - Cost optimization is needed—public mode for low-value, private mode for sensitive flows. + - "Cost optimization is needed: public mode for low-value, private mode for sensitive flows." avoid-when: - Uniform privacy is mandatory across all transactions (use a fully private L2 instead). - Complexity overhead outweighs benefits for simple, single-mode use cases. -dependencies: - - ERC-7573 (DvP settlement) - - ERC-3643 (compliant tokens with transfer rules) - - Volition or dual-chain architecture (public/private execution environments) + context: both +context_differentiation: + i2i: "Between institutions, mode selection is a bilateral decision backed by contractual agreements on disclosure. Decentralized policy governance prevents any single counterparty from unilaterally forcing mode changes for bilateral trades. Both parties have legal recourse against policy drift or misconfiguration." + i2u: "For end users, policy routing must be verifiable. Open-source routing logic lets users confirm their transactions are correctly assigned to private mode when required. Any operator-only override creates a pathway for forced disclosure, so the policy engine should be implemented as a permissionless smart contract rather than an operator service." + crops_profile: cr: medium - os: partial - privacy: partial - security: medium + o: partial + p: partial + s: medium + +crops_context: + cr: "Reaches `high` if the policy engine is decentralized as a permissionless smart contract with no unilateral override. Drops if the routing layer is operator-controlled, since a single party can force public-mode execution." + o: "Could reach `yes` by mandating open-source mode-routing logic and requiring privacy L2 provers to remain forkable. Today's deployments mix open public chains with partially-closed privacy environments." + p: "Public-mode legs are fully transparent; private-mode legs hide amounts and counterparties with selective disclosure via view keys. Mode selection itself leaks information: choosing private signals sensitivity." + s: "Could reach `high` with multi-operator settlement oracles using threshold cryptography. Current deployments rely on single oracle services or coordinated off-chain timing, which expands the trust surface." + +post_quantum: + risk: high + vector: "Any private leg using EC-based ZK proofs (Groth16, PLONK over BN254) is broken by a CRQC. HNDL risk is high for encrypted view-key material shared between counterparties." + mitigation: "Route private legs through STARK-based shielded pools with hash commitments. Rotate long-lived view keys and prefer post-quantum signatures for cross-mode settlement oracles." + +standards: [ERC-7573, ERC-3643, ERC-5564] + +related_patterns: + composes_with: [pattern-shielding, pattern-privacy-l2s, pattern-dvp-erc7573, pattern-commit-and-prove, pattern-regulatory-disclosure-keys-proofs, pattern-stealth-addresses] + alternative_to: [pattern-private-pvp-stablecoins-erc7573] + see_also: [pattern-modular-privacy-stack, pattern-forced-withdrawal] --- ## Intent -Allow institutions to select **public or private execution mode** on a per-transaction or per-counterparty basis, optimizing for cost, latency, and confidentiality requirements. This enables hybrid workflows where some legs execute transparently on public infrastructure while others use privacy-preserving mechanisms. - -## Ingredients - -- **Standards** - - ERC-7573 for atomic cross-leg settlement - - ERC-3643 for compliant token transfers with eligibility checks - - ERC-5564 (optional) for stealth addresses in private mode - -- **Infrastructure** - - **Public execution**: L1 or transparent L2 (e.g., Arbitrum, Optimism) - - **Private execution**: Privacy L2 (Aztec, Miden) or shielded pool (Railgun) - - **Mode-routing layer**: Smart contract or middleware that directs transactions based on policy - -- **Off-chain** - - **Policy engine**: Rules defining when to use public vs. private mode per counterparty, asset class, or threshold - - **View key infrastructure**: For selective disclosure from private legs to auditors - - **Coordination service**: Manages cross-mode settlement timing - -## Protocol (concise) +Allow institutions to select public or private execution mode on a per-transaction or per-counterparty basis, optimizing for cost, latency, and confidentiality requirements. This enables hybrid workflows where some legs execute transparently on public infrastructure while others use privacy-preserving mechanisms, with atomic cross-mode settlement. -1. **Configure policy rules** - Institution defines mode-selection criteria: counterparty whitelist, asset thresholds, jurisdiction-based rules. +## Components -2. **Evaluate mode per transaction** - When initiating a trade, the policy engine evaluates rules and assigns each leg to public or private execution. +- **Public execution environment** is an L1 or transparent L2 chain where amounts, counterparties, and timing are visible. +- **Private execution environment** is a privacy L2 or shielded pool where amounts and counterparties are hidden behind ZK commitments or FHE ciphertexts. +- **Mode-routing layer** is a smart contract or middleware that directs each transaction leg based on policy rules. +- **Policy engine** defines mode-selection criteria: counterparty whitelist, asset thresholds, jurisdiction-based rules. +- **Cross-mode settlement coordinator** uses ERC-7573 outcome keys or shared commitments to link a public leg and a private leg into one atomic trade. +- **View-key infrastructure** issues selective-disclosure artifacts from private legs to counterparties and regulators. -3. **Prepare assets in appropriate environment** - Public leg: assets remain on transparent chain. Private leg: assets are shielded (deposited to private pool or bridged to privacy L2). +## Protocol -4. **Execute legs in parallel or sequence** - Each leg executes in its assigned environment. Private legs generate ZK proofs or use FHE; public legs execute standard transfers. +1. [operator] Configure policy rules covering counterparty whitelist, asset thresholds, and jurisdictional routing. +2. [operator] When a trade arrives, the policy engine evaluates rules and assigns each leg to public or private execution. +3. [user] Prepare assets in the appropriate environment. Public legs stay on the transparent chain; private legs are shielded into a private pool or bridged to a privacy L2. +4. [contract] Execute legs in parallel or sequence. Each leg runs in its assigned environment; private legs generate ZK proofs or use FHE, public legs execute standard transfers. +5. [contract] Coordinate cross-mode settlement via ERC-7573 outcome keys or commit-and-prove so both legs settle atomically or both fail. +6. [regulator] Receive disclosure artifacts from private legs: view keys or ZK attestations delivered per policy. +7. [operator] Finalize and reconcile. Internal systems map public chain events to private proofs for the audit trail. -5. **Coordinate cross-mode settlement** - ERC-7573 or commit-and-prove mechanism ensures atomicity across modes. Outcome keys or shared commitments link the legs. +## Guarantees & threat model -6. **Generate disclosure artifacts** - Private legs produce view keys or ZK attestations for counterparties and regulators as defined by policy. +Guarantees: -7. **Finalize and reconcile** - Both legs settle. Internal systems reconcile public chain events with private proofs for audit trail. +- Mode-specific privacy. Public-mode legs reveal amounts, counterparties, and timing; private-mode legs hide amounts or counterparties and disclose selectively via view keys. +- Atomic cross-mode settlement. ERC-7573 outcome keys or shared commitments ensure either both legs succeed or both fail. +- Selective auditability. Regulators verify private legs through view keys without accessing the privacy pool's full state. +- Compliance continuity. Permissioned-token transfer rules apply regardless of execution mode, so eligibility checks hold on both public and private legs. -## Guarantees +Threat model: -- **Mode-specific privacy** - - Public mode: Full transparency of amounts, counterparties, timing. - - Private mode: Amounts and/or counterparties hidden; disclosed only via view keys. - -- **Atomic settlement** - Cross-mode DvP achieves conditional atomicity—both legs settle or both fail—via ERC-7573 outcome keys or shared commitments. - -- **Auditability** - Regulators can verify private legs through selective disclosure without accessing the privacy pool's full state. - -- **Compliance continuity** - ERC-3643 transfer rules apply regardless of mode, ensuring eligibility checks on both public and private legs. +- Non-compromised policy engine. A tampered engine can route sensitive transactions to public mode. +- Honest cross-mode settlement oracle. A compromised oracle can withhold outcome keys to grief one of the legs. +- Non-censoring sequencer set on the privacy L2 (or forced-withdrawal fallback on the shielded pool). +- Out of scope: metadata correlation across modes. Timing and transaction-size correlation between the public and private legs can re-link counterparties even without direct leakage. ## Trade-offs -- **Metadata leakage** - Mode selection itself reveals information (choosing private signals sensitivity). Timing correlation between legs may link transactions. - -- **Operational complexity** - Dual infrastructure requires expertise in both transparent and privacy systems. Failure modes multiply. - -- **Cost asymmetry** - Private execution incurs ZK proof generation costs; public execution is cheaper but exposes data. Mixed-mode trades pay both overheads. - -- **Tooling maturity** - Cross-mode settlement is less battle-tested than single-environment flows. Limited production deployments exist. - -- **Policy drift risk** - Rules must stay synchronized across systems; misconfigurations can route sensitive transactions to public mode. -- **CROPS context (both)**: CR could reach `high` if the policy engine is decentralized as a permissionless smart contract with no unilateral override. OS improves to `yes` by mandating open-source mode-routing logic and requiring privacy L2 provers to remain forkable. Security could reach `high` with multi-operator settlement oracles using threshold cryptography. In I2I, decentralized policy governance prevents any single counterparty from controlling mode selection for bilateral trades. In I2U, open-source routing logic lets end users verify that their transactions are correctly assigned to private mode when required. +- Metadata leakage. Mode selection itself reveals information: choosing private signals sensitivity. Timing correlation between legs may link transactions. +- Operational complexity. Dual infrastructure requires expertise in both transparent and privacy systems; failure modes multiply. +- Cost asymmetry. Private execution incurs ZK proof generation costs; public execution is cheaper but exposes data. Mixed-mode trades pay both overheads. +- Tooling maturity. Cross-mode settlement is less battle-tested than single-environment flows. Limited production deployments exist. +- Policy drift risk. Rules must stay synchronized across systems; misconfigurations can route sensitive transactions to public mode. ## Example -- Bank A sells a tokenized bond (public asset leg on L1) to Bank B for EURC (private cash leg on privacy L2). -- Policy engine assigns: bond transfer = public (asset is already public, no sensitivity); cash payment = private (amount confidentiality required). -- Bank A locks bond in ERC-7573 contract on L1. -- Bank B shields EURC on privacy L2 and executes private payment referencing trade ID `T`. -- Oracle confirms private payment success, releases outcome key. -- L1 contract delivers bond to Bank B. Regulator receives Bank B's view key for the cash leg. +A bank sells a tokenized bond (public asset leg on L1) to a counterparty for a stablecoin payment (private cash leg on a privacy L2). The policy engine assigns the bond transfer to public execution (the asset is already public, no sensitivity) and the cash payment to private execution (amount confidentiality required). The seller locks the bond in an ERC-7573 contract on L1. The buyer shields the stablecoin on the privacy L2 and executes the private payment referencing trade ID T. An oracle confirms private payment success and releases the outcome key. The L1 contract delivers the bond to the buyer. The regulator receives the buyer's view key for the cash leg. ## See also -- [Shielded ERC-20 Transfers](pattern-shielding.md) -- [Private L2s](pattern-privacy-l2s.md) -- [Atomic DvP via ERC-7573](pattern-dvp-erc7573.md) -- [Commit-and-Prove Fallback](pattern-commit-and-prove.md) -- [Regulatory Disclosure Keys](pattern-regulatory-disclosure-keys-proofs.md) +- [Private Bonds Approach](../approaches/approach-private-bonds.md) +- [ERC-7573 specification](https://eips.ethereum.org/EIPS/eip-7573) diff --git a/patterns/pattern-icma-bdt-data-model.md b/patterns/pattern-icma-bdt-data-model.md index 09c3994..74dde5e 100644 --- a/patterns/pattern-icma-bdt-data-model.md +++ b/patterns/pattern-icma-bdt-data-model.md @@ -2,52 +2,87 @@ title: "Pattern: ICMA Bond Data Taxonomy (canonical terms/events)" status: ready maturity: production +type: standard layer: offchain -privacy_goal: Standardize bond data for clean attestations without exposing raw data -assumptions: ICMA BDT schema adoption, schema validator tooling, registrar integration -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 + works-best-when: - - You want machine-readable bond terms/events across tools. + - You want machine-readable bond terms and lifecycle events across tools. + - Multiple issuance platforms need to interoperate without bespoke mappings. avoid-when: - - N/A (use as a baseline; extend as needed) - - ICMA is not the schema being used for a particular jurisdiction/domain -dependencies: - - ICMA BDT schema + - A jurisdiction or domain mandates a different canonical schema. + context: i2i + crops_profile: cr: none - os: yes - privacy: full - security: high + o: yes + p: full + s: high + +crops_context: + cr: "Schema governance sits with a single standards body (ICMA). Could reach `medium` if the schema is published as a permissionless open registry with attestation-anchored contributions and no approval gate." + o: "Open specification, publicly documented. Implementations can reuse the schema without licensing barriers, though schema evolution is gated by the standards body." + p: "Schema itself contains no participant data; only field definitions. Raw bond data stays off-chain, with only hashes anchored on-chain, so the pattern does not expose confidential details." + s: "Rides on the correctness of off-chain validators and the integrity of hash anchoring. Well-defined schemas reduce integration errors and make regulator reconciliation straightforward." + +post_quantum: + risk: low + vector: "Hash-based anchoring is not directly affected. Any ECDSA-signed off-chain attestations over BDT records are vulnerable to a CRQC, but the canonical schema itself has no cryptographic dependency." + mitigation: "Use post-quantum signatures for attestations over BDT records; hash-based commitments for on-chain anchoring remain safe." + +standards: [ICMA-BDT] + +related_patterns: + composes_with: [pattern-crypto-registry-bridge-ewpg-eas, pattern-verifiable-attestation, pattern-regulatory-disclosure-keys-proofs] + see_also: [pattern-private-iso20022] --- ## Intent -Use **ICMA Bond Data Taxonomy** as the canonical schema for bond terms & lifecycle events to avoid fragmentation and enable clean attestations/proofs. -## Ingredients -- **Standards**: ICMA BDT -- **Infra**: Schema loader/validator; compression (XML→binary) -- **Off-chain**: Mapping to registrar records; EAS hash anchoring +Use the ICMA Bond Data Taxonomy as the canonical schema for bond terms and lifecycle events. A shared data model avoids fragmentation across issuance platforms, registrars, and regulators, and provides a stable foundation for attestations and zero-knowledge proofs over bond data. + +## Components -## Protocol (concise) -1. Author terms/events in BDT. -2. Validate; compress; store (on/off-chain hash). -3. Use same schema in proofs/disclosures. +- **Canonical schema** defines bond terms (identifiers, parties, cash flows, covenants) and lifecycle events (issuance, coupons, redemption, restructuring). +- **Schema validator** checks that bond records conform to the canonical definitions before they are signed, hashed, or anchored. +- **Compression layer** converts verbose representations (for example XML) into binary or compact serialization for efficient on-chain anchoring. +- **Registrar integration** maps internal registrar records to the canonical schema so existing systems can emit conformant data without rewriting their back office. +- **Attestation anchor** posts hashes of conformant records to an on-chain attestation registry so any verifier can check that a disclosed document matches what the registrar recorded. -## Guarantees -- Interop-ready, regulator-friendly data. -- Easier proofs/attestations. +## Protocol + +1. [operator] Author bond terms and lifecycle events in the canonical schema. +2. [operator] Validate the record against the schema and compress for storage. +3. [operator] Store the record (on-chain hash anchor, off-chain canonical payload). +4. [auditor] Use the same schema when preparing selective-disclosure proofs or attestations. +5. [regulator] Verify consistency between disclosed payloads and on-chain hash anchors. + +## Guarantees & threat model + +Guarantees: + +- Interoperable, regulator-friendly bond data across platforms. +- Easier proofs and attestations over common fields without bespoke per-issuer schemas. +- Clean baseline for composing with hash-anchored registries and zero-knowledge disclosure patterns. + +Threat model: + +- Schema governance integrity. If the standards body publishes conflicting revisions, validators may diverge on what counts as conformant. +- Registrar mapping correctness. A mismapping at integration time can silently break consistency between internal records and canonical output. +- Out of scope: data confidentiality. The schema is a structural artifact, not a privacy tool; confidentiality must come from accompanying patterns (hash anchoring, selective disclosure, ZK proofs). ## Trade-offs -- Up-front mapping effort to existing systems. -- **CROPS context (i2i)**: CR could reach `medium` if the BDT schema is published as a permissionless open registry with EAS-anchored contributions and no approval gate. Among institutional counterparties, open schema governance ensures no single issuer or registrar controls the canonical bond data format, enabling competitive issuance platforms to interoperate without gatekeeping. + +- Up-front mapping effort is required to wire existing registrar systems into the canonical schema. +- Schema extensions for new product types (complex derivatives, non-standard covenants) need standards-body involvement, which can lag market innovation. +- Not a privacy mechanism on its own. Must be paired with hashing, attestation, or zero-knowledge patterns to protect the underlying data. ## Example -- Issuance terms in BDT; hash anchored via EAS; regulator verifies consistency. + +An issuance platform publishes bond terms in the canonical schema. The registrar validates the record and anchors its hash via an on-chain attestation registry. A regulator later receives the full payload off-chain and verifies the hash matches the on-chain anchor, confirming the record has not been altered since issuance. ## See also -- pattern-crypto-registry-bridge-ewpg-eas.md -## See also (external) -- ICMA BDT overview: https://www.icmagroup.org/fintech-and-digitalisation/fintech-advisory-committee-and-related-groups/bond-data-taxonomy/ -- BDT factsheet (PDF): https://www.icmagroup.org/assets/documents/Regulatory/FinTech/Bond-data-taxonomy/ICMA-Bond-Data-Taxonomy-BDT-Factsheet-March-2023-140323.pdf +- [ICMA Bond Data Taxonomy overview](https://www.icmagroup.org/fintech-and-digitalisation/fintech-advisory-committee-and-related-groups/bond-data-taxonomy/) +- [ICMA BDT Factsheet (PDF)](https://www.icmagroup.org/assets/documents/Regulatory/FinTech/Bond-data-taxonomy/ICMA-Bond-Data-Taxonomy-BDT-Factsheet-March-2023-140323.pdf) diff --git a/patterns/pattern-l2-encrypted-offchain-audit.md b/patterns/pattern-l2-encrypted-offchain-audit.md index 370a759..75de5fb 100644 --- a/patterns/pattern-l2-encrypted-offchain-audit.md +++ b/patterns/pattern-l2-encrypted-offchain-audit.md @@ -1,65 +1,104 @@ --- title: "Pattern: Low-cost L2 + Off-chain Encrypted Audit Log" status: ready -maturity: pilot +maturity: testnet +type: standard layer: hybrid -privacy_goal: Hide amounts and positions with only commitments on-chain; encrypted audit log off-chain -assumptions: L2 infrastructure, threshold KMS for scoped keys, EAS for access logging -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 + works-best-when: - - Need hidden amounts/positions with minimal on-chain footprint. - - Prefer cheap daily settlement over full on-chain private compute. + - You need hidden amounts and positions with a minimal on-chain footprint. + - Cheap daily settlement is preferable to full on-chain private compute. + - A trusted off-chain operator or consortium can run the encrypted log. avoid-when: - - Regulator demands full on-chain plaintext or off-chain infra is not feasible. -dependencies: - - ERC-7573 - - EIP-4844 - - ERC-3643 - - EAS - - Threshold-KMS + - The regulator requires full on-chain plaintext of each transaction. + - Off-chain infrastructure cannot be operated reliably across multiple regions. + context: both +context_differentiation: + i2i: "Between institutions, the encrypted log can be hosted by a consortium or mutualized operator. Both parties have legal recourse if log integrity is disputed, and the on-chain Merkle anchor constrains what can be retroactively changed. Scoped regulator keys cover audit without revealing unrelated trades." + i2u: "The user cannot verify that an off-chain log contains their own entries unless they keep client-side ciphertext and can reproduce commitments. Without a forced on-chain settlement path, the user depends on the operator to release data needed for withdrawal. The pattern should therefore surface an L1 escape hatch and give the user a copy of their encrypted records." + crops_profile: cr: medium - os: partial - privacy: partial - security: medium + o: partial + p: partial + s: medium + +crops_context: + cr: "Reaches `high` only when the L2 exposes an L1 escape hatch usable without operator cooperation. On sequencer-controlled L2s with no force-inclusion path, censorship resistance is effectively `low`." + o: "On-chain contracts can be open source; the threshold KMS and off-chain log code are often closed. Openness improves when the KMS software is released and multiple implementations can run the log." + p: "Plaintext is off-chain; commitments and access logs on-chain leak timing and counterparty pairs. Access-pattern privacy requires additional measures (proxy re-encryption, mixnet routing for log reads)." + s: "Settlement integrity rides on the host L2 and the periodic Merkle anchor. Disclosure integrity rides on the threshold KMS quorum and retention of encrypted records across regions." + +post_quantum: + risk: medium + vector: "Symmetric record encryption (AES-GCM) is PQ-safe; key wrapping under EC-based threshold schemes is broken by CRQC, with HNDL risk for long-retention archives." + mitigation: "Rotate wrapped keys using ML-KEM or hash-based threshold schemes before CRQC arrival. See [Post-Quantum Threats](../domains/post-quantum.md)." + +standards: [ERC-7573, EIP-4844, ERC-3643, EAS] + +related_patterns: + composes_with: [pattern-dvp-erc7573, pattern-regulatory-disclosure-keys-proofs, pattern-forced-withdrawal] + alternative_to: [pattern-private-shared-state-fhe, pattern-shielding] + see_also: [pattern-modular-privacy-stack, pattern-commit-and-prove] + +open_source_implementations: + - url: https://github.com/ethereum-attestation-service/eas-contracts + description: "Ethereum Attestation Service reference contracts for access-log attestations" + language: Solidity --- ## Intent -Run on a low-cost L2; put only **commitments/hashes** on-chain; store full facts in an **append-only encrypted log**. Anchor integrity on-chain; provide auditor access via **scoped keys**; DvP via ERC-7573. -## Ingredients -- **Standards**: ERC-7573 (DvP); EAS (access logs) -- **Infra**: L2 contracts (`AuditCommit(bytes32)`); hourly Merkle-root anchor -- **Off-chain**: Encrypted records (per-trade symmetric key wrapped to threshold authorities) +Run settlement on a low-cost L2, publish only commitments and hashes on chain, and keep the full transaction facts in an append-only encrypted log off chain. Integrity is anchored by periodic Merkle roots submitted on chain. Regulators and auditors receive scoped decryption keys or predicate proofs. Delivery-versus-payment is expressed through an atomic settlement standard. + +## Components -## Protocol (concise) -1. RFQ/match off-chain (optionally encrypted route). -2. Write encrypted record; compute commitment; emit `AuditCommit`. -3. Anchor Merkle root periodically. -4. Escrow legs; finalize atomically via ERC-7573. -5. Regulator receives scoped view key or predicate proof; log access via EAS. +- On-chain audit contract that accepts `AuditCommit(bytes32)` entries and records hourly Merkle roots over the off-chain log. +- Append-only encrypted log, replicated across regions, storing per-trade records keyed by a content address. +- Per-trade symmetric key, wrapped to a threshold set of authorities so that disclosure requires a quorum rather than a single custodian. +- Atomic settlement contract implementing cross-leg delivery-versus-payment over cash and asset legs. +- Access-logging attestations emitted on chain whenever a scoped key is issued or used. -## Guarantees -- Public sees identities + commitments only; no figures leak. -- Tamper-evident audit trail via anchored roots. -- Atomic DvP; selective, auditable disclosure. +## Protocol + +1. [user] Negotiate and match the trade off chain; optionally encrypt the routing metadata. +2. [operator] Write the encrypted record to the log, compute its commitment, and submit `AuditCommit` on chain. +3. [operator] Aggregate the window's commitments into a Merkle root and anchor it on chain at the configured cadence. +4. [contract] Escrow both legs and finalize atomically through the delivery-versus-payment contract. +5. [regulator] Receive a scoped decryption key or predicate proof for a specific record; the issuance is logged through an on-chain attestation. +6. [auditor] Replay the log against the anchored roots to confirm that no record has been rewritten after the fact. + +## Guarantees & threat model + +Guarantees: + +- Public observers see only commitments and hashes; amounts, identities, and positions remain off chain. +- Merkle anchoring makes the log tamper-evident: any silent rewrite breaks the on-chain root. +- Atomic delivery-versus-payment prevents one-sided settlement failure. +- Disclosure is scoped and logged, so access is auditable after the fact. + +Threat model: + +- Trust in operator availability and retention of the encrypted log; loss of ciphertext cannot be recovered from the chain alone. +- Threshold quorum of the key-wrapping authorities; a colluding quorum can decrypt records outside the disclosure process. +- Non-censoring sequencer on the host L2. Without a usable L1 escape hatch, a censoring sequencer can block settlement and audit commits. +- Access-pattern and timing side channels on the log remain visible to anyone hosting or monitoring the storage layer. ## Trade-offs -- Trust in off-chain availability/retention; mitigate with multi-region + anchors. -- Key governance overhead (rotation/re-encryption). -- L2 sequencer can censor transactions; users depend on L1 escape hatch for censorship resistance. -- **CROPS context (both)**: CR could reach `high` if an L1 escape hatch is enforced for withdrawal when the sequencer censors. OS improves to `yes` by releasing the threshold KMS implementation as an open-source library. Privacy could reach `full` by encrypting metadata such as access patterns and timing via threshold proxy re-encryption. Security could reach `high` by anchoring audit contracts on L1 to eliminate sequencer control over disclosure logs. In I2I, L1 escape hatches ensure neither counterparty can be locked out of settlement by a censoring sequencer. In I2U, end users benefit from metadata encryption that prevents observers from inferring transaction patterns or account activity from timing and access logs. + +- Operational overhead of running redundant encrypted storage across regions with retention and rotation policies. +- Key governance cost: rotating wrapped keys and re-encrypting archived records is non-trivial at scale. +- Cross-region replication and KMS coordination add latency to disclosure flows. +- Failure mode: log rewrite attempt is detected by Merkle reconciliation but recovery still requires access to earlier ciphertext; multi-region backups are the mitigation. ## Example -- A sells €5m to B; chain shows `commit` only. -- Root anchored hourly; ERC-7573 ties cash to asset. -- BaFin gets 24-hour key for that record; disclosure logged. + +A dealer sells a bond to an asset manager on the L2. The chain records only the commitment and the hourly Merkle root; full trade details sit encrypted in the log. Delivery-versus-payment finalizes atomically on chain. The national supervisor later receives a 24-hour scoped key for that record, and the issuance is attested on chain so the disclosure is itself auditable. ## See also -- pattern-dvp-erc7573.md · pattern-regulatory-disclosure-keys-proofs.md · pattern-confidential-erc20-fhe-l2-erc7573.md -## See also (external) -- ERC-7573 spec: https://ercs.ethereum.org/ERCS/erc-7573 -- EIP-4844 (blobs): https://eips.ethereum.org/EIPS/eip-4844 -- EAS docs: https://easscan.org/docs \ No newline at end of file +- [ERC-7573 spec](https://ercs.ethereum.org/ERCS/erc-7573) +- [EIP-4844 (blobs)](https://eips.ethereum.org/EIPS/eip-4844) +- [EAS docs](https://easscan.org/docs) diff --git a/patterns/pattern-l2-privacy-evaluation.md b/patterns/pattern-l2-privacy-evaluation.md index 1d780c6..d528ee2 100644 --- a/patterns/pattern-l2-privacy-evaluation.md +++ b/patterns/pattern-l2-privacy-evaluation.md @@ -1,202 +1,154 @@ --- title: "Pattern: L2 Privacy Evaluation Framework" status: draft -maturity: PoC +maturity: concept +type: standard layer: L2 -privacy_goal: Structured methodology for institutions to compare privacy-preserving L2 solutions -assumptions: L2 teams provide self-reported metrics with sources; independent verification where possible -last_reviewed: 2026-01-27 +last_reviewed: 2026-04-22 + works-best-when: - - Evaluating multiple privacy L2s for institutional deployment - - Comparing throughput, security, and censorship-resistance across systems - - Need consistent criteria across heterogeneous architectures + - Multiple privacy L2s must be compared for an institutional deployment decision. + - Throughput, security, and censorship resistance have to be placed side by side across heterogeneous architectures. + - A consistent, sourced methodology is needed so that procurement and risk teams can review the same evidence. avoid-when: - - Evaluating general-purpose L2s without privacy features - - Single-vendor evaluation (use vendor docs directly) -dependencies: [] -crops_profile: "n/a" ---- - -## Intent - -Provide institutions with a structured, vendor-neutral framework to compare privacy-preserving L2 solutions across performance, privacy/DA, and security dimensions. Enables apples-to-apples comparison despite architectural differences. - -## Ingredients - -- Self-reported metrics from L2 teams (with sources) -- Independent benchmarks where available (L2Beat, academic papers) -- Standardized workload definitions (Simple Value Transfer) -- Clear disclosure of what each metric measures - -## Protocol - -1. **Define workload**: Use [Simple Value Transfer](#simple-value-transfer) as baseline -2. **Collect metrics**: Request L2 teams fill in the three evaluation tables -3. **Verify sources**: Each claim must link to benchmark, docs, or paper -4. **Flag gaps**: Mark "Pending" for missing data, "N/A" for inapplicable metrics -5. **Compare**: Use tables to identify trade-offs relevant to your use case -6. **Re-evaluate**: Update as systems mature (hard forks, client updates) - -## Evaluation Criteria - -### 1. Performance & Cost - -| Metric | What is Measured | Discrete Metrics | -| :------------------------- | :---------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | -| **Max Throughput** | Maximum sustained TPS | Max theoretical TPS, Tested Peak TPS (with benchmark link). Report TPSPublic and TPSPrivate separately | -| **Transaction Cost** | Total cost per L2 transaction | Gas usage in `L1 gas units` + `L2 gas units` for Simple Value Transfer | -| **Bridging & Exit Costs** | Cost of L1↔L2 asset movement | L2→L1 withdrawal (gas units), Forced Exit to L1 (gas units) | -| **Economic Finality Time** | Time until L1 validation | `Soft Finality` (L2 inclusion), `Hard Finality` (L1 commitment + proof), `Challenge Period` | -| **Transaction Retrieval** | Bandwidth/time to retrieve incoming funds | Sync mechanism (`Trial decryption`, `Detection Keys`, `Server-side filtering`), Sync speed (e.g., "time to sync 10k blocks") | - -### 2. Privacy & Data Availability - -| Metric | What is Measured | Discrete Metrics | -| :------------------------ | :------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | -| **Level of Privacy** | Scope of hidden information | **What**: `Balance`, `Sender/Receiver`, `Amount`, `Code/Function`, `Contract Bytecode`. **Who sees**: `Public`, `Sequencer`, `Prover` | -| **DA Layer\*** | Where state reconstruction data is posted | `L1 Call Data`, `L1 Data Blobs (EIP-4844)`, `External DAC` | -| **DA Trust Assumption\*** | Parties user must trust for data access | `Trustless/L1-secured`, `Trusted DAC` | -| **Data Posted to L1\*** | Information broadcast for state verification | `Full Transaction Data`, `State Diff`, `Validity Proof Only` | -| **Compliance Features** | Selective disclosure mechanisms | `Incoming Viewing Key`, `Outgoing Viewing Key`, `Full History Viewing Key` | -| **Privacy Trust Model** | Fundamental privacy guarantee | **Base**: `Cryptographic`, `Threshold (MPC/FHE)`. **Collusion threshold**: m-of-n | -| **Network Privacy** | Transport layer metadata protection | RPC privacy options (`Tor/I2P`, `Oblivious HTTP`, `Mixnet`) | - -_`_` L2Beat direct match\* - -### 3. Security & Governance - -| Metric | What is Measured | Discrete Metrics | -| :----------------------------- | :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Sequencer Decentralization** | Decentralization of tx ordering | `Centralized`, `Permissioned Set`, `Decentralized Auction`, `Based (L1 Sequencing)` | -| **Censorship Resistance** | Mechanism to bypass censoring sequencer | **Mechanism**: `Force inclusion`, `Escape Hatch`, `Council`. **User burden**: `Stateless`, `Merkle Witness`, `Full State Reconstruction`. **Latency**: `Immediate`, `Challenge Period` | -| **Prover Mechanism** | Proof generation and verification | **Access**: `Whitelist`, `Permissionless`. **System**: `Plonk`, `Stark`, `FHE`, `Groth16` | -| **Upgrade Process** | L1 contract update mechanism | **Governance**: `Multisig (m-of-n)`, `Immutable`, `DAO Vote`. **Timelock**: delay in days/hours | -| **Client-Side Requirements** | End-user computational cost | **Client proving**: `Yes`/`No`. **Features**: `Mobile Proving`, `Trusted Delegation`, `Blind Delegation`. **Benchmark**: proof duration/size/memory for ERC-20 transfer | -| **Finality Security** | Validity guarantee type | `Validity (ZK)`, `Optimistic (Fraud Proofs)` | -| **Proof System Setup** | Initial setup requirement | `Trusted Ceremony`, `Transparent` | -| **Programmability** | Developer environment | **Language**: `EVM/Solidity`, `DSL`, `WASM`. **Deployment**: `Permissionless`, `Whitelisted` | -| **PQ Security** | Post-quantum vulnerability | Susceptible to HNDL attacks? (`Yes`/`No`) | - -## Simple Value Transfer - -A protocol-native payment where a sender transfers an ERC-20 amount to a single recipient, resulting in a valid state transition. - -**TPSPublic**: Transfer semantics publicly observable. Completion = L2 inclusion + validity. + - The L2 under review has no privacy features; use a general L2 scorecard instead. + - A single vendor is already chosen and only vendor docs need verification. -**TPSPrivate**: Full privacy mode (hiding sender, recipient, amount as applicable). Optional features excluded unless protocol-mandatory. +context: both +context_differentiation: + i2i: "Between institutions the framework is used by procurement, risk, and ops teams to weigh counterparty-aligned criteria such as force-inclusion SLAs, compliance features, and DA trust assumptions. Both sides can cross-review the filled table." + i2u: "For user-facing deployments the framework surfaces asymmetries that matter to end users: client proving cost, availability of forced exits without operator cooperation, and whether disclosure can be compelled unilaterally by the operator." -**Consistency requirement**: Features excluded when reporting TPS must not be implicitly assumed elsewhere. - -**Non-goals**: This definition does not equalize DA models, finality, confirmation UX, compliance features, or offchain coordination. - -## Guarantees +crops_profile: "n/a" -- Consistent comparison criteria across heterogeneous L2 architectures -- Separation of self-reported vs independently verified metrics -- Clear visibility into what each system hides from whom -- Traceable claims (all metrics require sources) +post_quantum: + risk: low + vector: "The framework itself is a methodology, not a cryptographic primitive. One of its rows (`PQ Security`) flags HNDL exposure in the evaluated systems." + mitigation: "Encourage each system to report post-quantum readiness in its row, and re-evaluate as systems migrate proof systems." -## Trade-offs +standards: [] -- Self-reported metrics may be optimistic; prefer independent benchmarks -- Some systems may not map cleanly to all criteria -- Metrics change as systems mature; requires periodic re-evaluation -- Does not capture all institutional requirements (legal, operational) +related_patterns: + see_also: [pattern-privacy-l2s, pattern-hybrid-public-private-modes, pattern-shielding, pattern-forced-withdrawal] -## Targeted Protocols +open_source_implementations: + - url: https://github.com/l2beat/l2beat + description: "L2Beat open dataset and risk methodology used as a baseline for independently verified metrics" + language: TypeScript +--- -**Privacy L2s**: Aztec, Miden, Intmax, Prividium, Scroll Cloak, EY Nightfall +## Intent -## Results (Public Data) +Give institutions a vendor-neutral, sourced methodology for comparing privacy-preserving L2 solutions across performance and cost, privacy and data availability, and security and governance. The framework defines a common workload so that self-reported metrics can be placed next to independent benchmarks on the same axes. -> Metrics below are from public documentation and independent sources. Empty cells indicate data not yet publicly available. +> Note: this card is an evaluation framework, not a reusable privacy primitive. `pattern-privacy-l2s` is the actual L2 pattern; this one documents how to compare privacy L2s. Candidate for relocation to `approaches/` or a methodology section in a follow-up. -### Deployment Model +## Components -| Protocol | Type | Description | -| :--------------- | :----------- | :------------------------------------------------------------ | -| **Aztec** | Public L2 | Hybrid public/private network with native privacy | -| **Miden** | Public L2 | Hybrid public/private network with optional delegated proving | -| **Intmax** | Public L2 | Stateless public network, client holds data | -| **Prividium** | AppChain SDK | Private Validium on ZKsync Stack for institutional deployment | -| **Scroll Cloak** | AppChain SDK | L3 validium appchain on Scroll/EVM chains | -| **EY Nightfall** | AppChain SDK | ZK-Rollup stack for enterprise deployment | +- Self-reported metric sheets collected from each L2 team, with a source link per cell. +- Independent benchmarks and risk reviews used to cross-check the self-reported values. +- A standardized workload (Simple Value Transfer) that fixes what a transaction means across heterogeneous architectures. +- A disclosure convention that records what each metric measures, what is excluded, and whether a value is `Pending` or `N/A`. -_AppChain SDKs have deployment-dependent assumptions (sequencer, DA, governance) that vary by operator._ +## Protocol -### Privacy & Architecture Overview +1. [evaluator] Adopt Simple Value Transfer as the baseline workload. +2. [evaluator] Request each L2 team to fill the three evaluation tables (performance, privacy and DA, security and governance). +3. [evaluator] Require a source link for every claim (benchmark run, docs page, or paper). +4. [evaluator] Mark `Pending` where data is missing and `N/A` where the metric does not apply to that architecture. +5. [evaluator] Produce the comparative view; highlight trade-offs that matter for the target use case. +6. [evaluator] Re-run the exercise on hard forks, client updates, or when a new benchmark is published. + +## Evaluation criteria + +### 1. Performance and cost + +| Metric | Discrete metrics | +| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | +| **Max Throughput** | Max theoretical TPS, tested peak TPS (with benchmark link). Report TPSPublic and TPSPrivate separately | +| **Transaction cost** | Gas usage in `L1 gas units` + `L2 gas units` for Simple Value Transfer | +| **Bridging and exit** | L2 to L1 withdrawal and forced exit cost (gas units) | +| **Finality time** | `Soft Finality` (L2 inclusion), `Hard Finality` (L1 commitment + proof), `Challenge Period` | +| **Transaction retrieval** | Sync mechanism (`Trial decryption`, `Detection Keys`, `Server-side filtering`) and sync speed | + +### 2. Privacy and data availability + +| Metric | Discrete metrics | +| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------ | +| **Level of privacy** | **What**: `Balance`, `Sender/Receiver`, `Amount`, `Code/Function`, `Contract Bytecode`. **Who sees**: `Public`, `Sequencer`, `Prover` | +| **DA layer** | `L1 Call Data`, `L1 Data Blobs (EIP-4844)`, `External DAC` | +| **DA trust** | `Trustless/L1-secured`, `Trusted DAC` | +| **Data posted to L1** | `Full Transaction Data`, `State Diff`, `Validity Proof Only` | +| **Compliance features** | `Incoming Viewing Key`, `Outgoing Viewing Key`, `Full History Viewing Key` | +| **Privacy trust model** | **Base**: `Cryptographic`, `Threshold (MPC/FHE)`. **Collusion threshold**: m-of-n | +| **Network privacy** | RPC privacy options (`Tor/I2P`, `Oblivious HTTP`, `Mixnet`) | + +### 3. Security and governance + +| Metric | Discrete metrics | +| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Sequencer decentralization** | `Centralized`, `Permissioned Set`, `Decentralized Auction`, `Based (L1 Sequencing)` | +| **Censorship resistance** | **Mechanism**: `Force inclusion`, `Escape Hatch`, `Council`. **User burden**: `Stateless`, `Merkle Witness`, `Full State Reconstruction`. **Latency**: `Immediate`, `Challenge Period` | +| **Prover mechanism** | **Access**: `Whitelist`, `Permissionless`. **System**: `Plonk`, `Stark`, `FHE`, `Groth16` | +| **Upgrade process** | **Governance**: `Multisig (m-of-n)`, `Immutable`, `DAO Vote`. **Timelock**: delay in days or hours | +| **Client-side requirements** | **Client proving**: `Yes`/`No`. **Features**: `Mobile Proving`, `Trusted Delegation`, `Blind Delegation` | +| **Finality security** | `Validity (ZK)`, `Optimistic (Fraud Proofs)` | +| **Proof system setup** | `Trusted Ceremony`, `Transparent` | +| **Programmability** | **Language**: `EVM/Solidity`, `DSL`, `WASM`. **Deployment**: `Permissionless`, `Whitelisted` | +| **PQ security** | Susceptible to HNDL attacks? (`Yes`/`No`) | -| Protocol | Type | Privacy Model | Proof System | DA Layer | Finality | -| :--------------- | :----------- | :----------------- | :----------------- | :---------------------- | :------- | -| **Aztec** | Public L2 | Cryptographic (ZK) | UltraHonk | L1 Blobs | Validity | -| **Miden** | Public L2 | Cryptographic (ZK) | STARK (Winterfell) | L1 Blobs | Validity | -| **Intmax** | Public L2 | Cryptographic (ZK) | Plonk/Gnark | Stateless (Client-Side) | Validity | -| **Prividium** | AppChain SDK | Cryptographic (ZK) | Boojum/Plonk | External (Private DB) | Validity | -| **Scroll Cloak** | AppChain SDK | Cryptographic (ZK) | Scroll zkEVM | Host chain | Validity | -| **EY Nightfall** | AppChain SDK | Cryptographic (ZK) | UltraPlonk | L1 Call Data | Validity | +## Simple Value Transfer -### Privacy Visibility Matrix +A protocol-native payment where a sender transfers an ERC-20 amount to a single recipient, resulting in a valid state transition. TPSPublic measures transfer semantics that are publicly observable (L2 inclusion plus validity). TPSPrivate measures a full privacy mode that hides sender, recipient, and amount as applicable; optional features are excluded unless they are mandatory in the protocol. Features excluded when reporting TPS must not be implicitly assumed elsewhere. The definition does not equalize DA models, finality, confirmation UX, compliance features, or off-chain coordination. -| Protocol | Balance | Sender | Receiver | Amount | Code/Function | -| :--------------- | :----------------: | :----------------: | :----------------: | :----------------: | :----------------: | -| **Aztec** | Hybrid1 | Hybrid1 | Hybrid1 | Hybrid1 | Hybrid1 | -| **Miden** | Hybrid1 | Hybrid1 | Hybrid1 | Hybrid1 | Hybrid1 | -| **Intmax** | Hidden | Hidden | Hidden | Hidden | Public2 | -| **Prividium** | Hidden | Hidden | Hidden | Hidden | Hidden | -| **Scroll Cloak** | Hidden | Hidden | Hidden | Hidden | Hidden | -| **EY Nightfall** | Hidden | Hidden | Hidden | Hidden | Limited | +## Guarantees & threat model -1 Both Aztec and Miden let the developer choose to store assets in Public (Account model) or in Private (UTXO note). +Guarantees: -2 Predicate is public; inputs/balances are stateless/hidden. Intmax only performs value transfers. +- Consistent comparison criteria across heterogeneous L2 architectures. +- Separation of self-reported metrics from independently verified metrics. +- Clear visibility into what each system hides and from whom. +- Traceable claims: every metric requires a source. -### Security & Governance +Threat model: -| Protocol | Sequencer | Censorship Resistance | Client Proving | Upgrade Mechanism | -| :--------------- | :-------------------------- | :-------------------- | :--------------------: | :------------------ | -| **Aztec** | Decentralized (Ignition) | Escape Hatch | Yes (heavy) | Multisig | -| **Miden** | Operator (Centralized) | TBD | Yes (can be delegated) | Multisig | -| **Intmax** | Decentralized (Aggregators) | Force Inclusion | Yes (light) | TBD | -| **Prividium** | Permissioned (Owner) | Operator-dependent | No (server) | Operator-controlled | -| **Scroll Cloak** | Permissioned (Owner) | Force Exit to host | No (prover service) | Operator-controlled | -| **EY Nightfall** | TBD | TBD | Yes | TBD | +- Self-reported metrics may be optimistic; the source link is what anchors them. +- Some systems do not map cleanly to every row; the `N/A` marker is load-bearing. +- Criteria drift over time; periodic re-evaluation is required. -**Client Proving**: "Yes (heavy)" = client-side ZK proof. "No (server)" = server proves. +## Trade-offs -### Compliance Features +- The exercise is labor-intensive; automation via a benchmark pipeline helps. +- Architectural heterogeneity makes equal-weight scoring misleading; use the tables as input to a weighted decision, not an output score. +- Frozen snapshots age quickly; timestamp every filled table and link back to source commits where possible. -| Protocol | Viewing Keys | Selective Disclosure | Audit Support | -| :--------------- | :----------: | :------------------: | :-------------------------- | -| **Aztec** | Yes | Yes | Incoming/Outgoing keys | -| **Miden** | Yes | Yes | Note-based disclosure | -| **Prividium** | TBD | TBD | TBD | -| **Scroll Cloak** | Yes | Access control | Operator + regulator access | -| **EY Nightfall** | Yes | Yes | Enterprise audit trail | +## Targeted systems -_Tables generated via LLM synthesis of sources below. Last updated: 2026-01-27_ +Privacy L2s currently in scope: Aztec, Miden, Intmax, Prividium, Scroll Cloak, EY Nightfall. The framework also applies to privacy app layers on existing chains (shielded pools, enterprise privacy layers, FHE coprocessors), which share DA but not sequencer assumptions. -**Sources**: [L2Beat](https://l2beat.com/), [Aztec Docs](https://docs.aztec.network/), [Miden VM](https://0xmiden.github.io/miden-vm/), [Intmax](https://intmax.io/), [Intmax2 Paper](https://eprint.iacr.org/2023/1082.pdf), [Prividium Docs](https://docs.zksync.io/zk-stack/prividium), [Cloak Docs](https://scroll-tech.github.io/cloak-documentation/), [Nightfall_4](https://github.com/EYBlockchain/nightfall_4_CE) +## Results snapshot -## Related: Privacy App Layers +Results below are drawn from public documentation and independent sources. Empty cells indicate data not yet publicly available; each published snapshot must be timestamped. -Privacy solutions for existing chains (no separate L2 state/sequencer): +| Protocol | Deployment | Privacy model | Proof system | DA | Client proving | Censorship resistance | +| :--------------- | :----------- | :----------------- | :----------------- | :---------------------- | :---------------------- | :-------------------- | +| **Aztec** | Public L2 | Cryptographic (ZK) | UltraHonk | L1 Blobs | Yes (heavy) | Escape Hatch | +| **Miden** | Public L2 | Cryptographic (ZK) | STARK (Winterfell) | L1 Blobs | Yes (can be delegated) | TBD | +| **Intmax** | Public L2 | Cryptographic (ZK) | Plonk/Gnark | Stateless (Client-Side) | Yes (light) | Force Inclusion | +| **Prividium** | AppChain SDK | Cryptographic (ZK) | Boojum/Plonk | External (Private DB) | No (server) | Operator-dependent | +| **Scroll Cloak** | AppChain SDK | Cryptographic (ZK) | Scroll zkEVM | Host chain | No (prover service) | Force Exit to host | +| **EY Nightfall** | AppChain SDK | Cryptographic (ZK) | UltraPlonk | L1 Call Data | Yes | TBD | -| Solution | Type | Description | -| :-------------------- | :--------------- | :------------------------------------ | -| **Railgun** | L1 Shielded Pool | Shielded transfers on Ethereum L1 | -| **Kaleido (Paladin)** | L1 Privacy Layer | Enterprise privacy on Ethereum L1 | -| **Zama fhEVM** | Coprocessor | FHE confidentiality for any EVM chain | +AppChain SDKs have deployment-dependent assumptions (sequencer, DA, governance) that vary by operator. Public L2s offering hybrid modes (Aztec, Miden) let the developer choose between a public account model and a private UTXO note model; stateless or validium designs (Intmax, Prividium, Scroll Cloak) hide balances and transfer data by default. -See [RFP: Living Benchmark Dashboard](../rfps/rfp-benchmark-dashboard.md). +Snapshot last refreshed 2026-01-27. Sources: [L2Beat](https://l2beat.com/), [Aztec Docs](https://docs.aztec.network/), [Miden VM](https://0xmiden.github.io/miden-vm/), [Intmax](https://intmax.io/), [Intmax2 Paper](https://eprint.iacr.org/2023/1082.pdf), [Prividium Docs](https://docs.zksync.io/zk-stack/prividium), [Cloak Docs](https://scroll-tech.github.io/cloak-documentation/), [Nightfall_4](https://github.com/EYBlockchain/nightfall_4_CE). ## Example -OTC settlement: filter by Cryptographic privacy, require Viewing Keys for audit, compare Client Proving vs trust, check Censorship Resistance SLAs. +An OTC settlement team filters the table for cryptographic privacy, requires viewing keys for audit support, compares client proving cost against trust assumptions, and reviews censorship-resistance SLAs before choosing between an AppChain SDK and a public privacy L2. ## See also -- [RFP: Living Benchmark Dashboard](../rfps/rfp-benchmark-dashboard.md) - Automated benchmark pipeline -- [L2Beat](https://l2beat.com/) - Independent L2 risk analysis -- [Pattern: Hybrid Public-Private Modes](pattern-hybrid-public-private-modes.md) -- [Pattern: Shielding](pattern-shielding.md) +- [RFP: Living Benchmark Dashboard](../rfps/rfp-benchmark-dashboard.md) - automated benchmark pipeline. +- [L2Beat](https://l2beat.com/) - independent L2 risk analysis. - [Post-Quantum Threats](../domains/post-quantum.md) diff --git a/patterns/pattern-lean-ethereum.md b/patterns/pattern-lean-ethereum.md index a789b7e..9c82f30 100644 --- a/patterns/pattern-lean-ethereum.md +++ b/patterns/pattern-lean-ethereum.md @@ -1,103 +1,102 @@ --- -title: Lean Ethereum +title: "Pattern: Lean Ethereum" status: draft -maturity: experimental +maturity: research +type: standard layer: L1 -privacy_goal: No direct privacy; consensus redesign enabling light client verification -assumptions: Post-quantum signatures, minimal zkVMs, 4-5 year research timeline, ~15 client teams -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 + works-best-when: - - Long-term Ethereum consensus redesign needed - - Solo validation accessibility matters + - A long-term redesign of Ethereum consensus is on the table. + - Solo-validator accessibility and light-client verifiability matter. + - Post-quantum resilience of the consensus layer is a design goal. avoid-when: - - Near-term deployment required (4–5 year horizon) -dependencies: [Post-quantum signatures, minimal zkVMs, P2P networking upgrades] + - Near-term deployment is required; the research horizon is multi-year. + - Only execution-layer scaling or transaction privacy is in scope. + context: both +context_differentiation: + i2i: "Between institutions the relevant properties are validator economics, finality guarantees, and post-quantum signature aggregation. Institutions running staking nodes benefit from lower hardware requirements and from formal verification of the signature scheme." + i2u: "For end users the relevant property is trustworthy light-client verification on minimal devices. A user who runs a mobile light client can verify consensus independently, without relying on a hosted RPC. Validator decentralization also reduces the risk that a small operator set can collude against users." + crops_profile: cr: high - os: yes - privacy: none - security: medium + o: yes + p: none + s: medium + +crops_context: + cr: "Lowering the solo-staking threshold and expanding the validator set raises censorship resistance at the consensus layer. Execution-layer CR still depends on the application stack above." + o: "Specifications and reference implementations are developed in the open across many client teams; formal verification artifacts (Lean 4) are public." + p: "The pattern does not add transaction privacy. Privacy is handled by separate execution-layer tracks that can run on top of a Lean consensus." + s: "Strength of the final construction depends on the cryptanalysis of the chosen post-quantum signature, the correctness of the minimal zkVM, and the stability of networking upgrades. Each of these is an open research question." + +post_quantum: + risk: low + vector: "The pattern itself targets post-quantum resilience by replacing EC signatures with hash-based multisignatures, so it reduces the core signature-layer PQ risk." + mitigation: "Hash-based multisignatures (XMSS/Winternitz-family candidates) aggregated via a minimal zkVM." + +standards: [] + +related_patterns: + see_also: [pattern-eil, pattern-focil-eip7805, pattern-native-account-abstraction] + +open_source_implementations: + - url: https://github.com/leanEthereum/leanSpec + description: "Lean specification repository with work-in-progress drafts across consensus, signatures, and networking" + language: Markdown --- ## Intent -A long-range redesign of Ethereum’s consensus layer aiming to enter in action around 2030. Lean consolidates multiple research tracks into a single major fork, reducing hardware requirements, improving validator accessibility, enabling fully verifying light clients on minimal devices, and preparing for a post-quantum world. - -## Ingredients - -- Specifications (in development) - - - Post-quantum hash-based multisignatures - - Minimal zkVMs for signature aggregation & proof compression - - Networking upgrades: Gossipsub v2, rateless set reconciliation - - Finality research (e.g., low-slot-count fast finality variants) - - Validator set expansion & economics (lower thresholds under discussion) - -- Infrastructure - - - ~15 client teams prototyping implementations across Rust, Zig, C, C++, Go, Java, .NET, TypeScript, Nim, Elixir - - Formal verification tooling (Lean 4) - - Cryptanalysis and protocol correctness research (Poseidon, hash-based schemes) - -- Research tracks - - - Post-quantum signature design & aggregation - - Minimal zkVM architecture - - Formal methods & proof automation - - Set reconciliation & P2P efficiency - -## Protocol (concise) - -1. Introduce post-quantum multisignatures - - - Hash-based multisig schemes explored (e.g., XMSS/Winternitz variants). - -2. Use minimal zkVMs for signature aggregation - - - Off-chain aggregation verified via succinct proofs. - - Exact workflow under active research. - -3. Expand validator participation +Plan a long-range redesign of the Ethereum consensus layer, targeting a single major fork around 2030 that consolidates several research tracks: post-quantum signatures, minimal zkVMs for signature aggregation and proof compression, reduced hardware and stake thresholds for validators, and networking upgrades that support a larger validator set. The goal is a consensus protocol that is stable for decades, resilient against quantum adversaries, and verifiable on minimal devices. - - Lower hardware & bandwidth requirements. - - Reduced stake requirements to 1 ETH. - - Tiered validator responsibilities under exploration. +## Components -4. Shorter slot times & faster finality +- Post-quantum hash-based multisignatures, with an aggregation scheme suited to large validator sets. +- Minimal zkVMs used to compress aggregated signatures and consensus proofs into succinct artifacts. +- Networking upgrades: Gossipsub v2 for throughput and DOS resilience, and rateless set reconciliation to support very large validator sets. +- Lower validator thresholds in hardware, bandwidth, and stake, making solo staking accessible on commodity devices. +- Formal verification tooling (Lean 4) used to prove key properties of the signature aggregation and consensus logic. +- Approximately fifteen client teams implementing the specification across Rust, Zig, C, C++, Go, Java, .NET, TypeScript, Nim, and Elixir. - - Targeting ~4s slot times (as explored in roadmap). - - Fast-finality schemes (e.g., 3-slot variants) under evaluation; parameters TBD. +## Protocol -5. Deploy upgraded networking +1. [researcher] Select and cryptanalyze a post-quantum hash-based multisignature scheme suited to aggregation. +2. [researcher] Design a minimal zkVM that verifies and compresses aggregated signatures. +3. [client-team] Prototype the consensus upgrade across independent client teams to stress-test the specification. +4. [validator] Run consensus at lower hardware and stake thresholds; participate with reduced bandwidth requirements. +5. [network] Deploy Gossipsub v2 and rateless set reconciliation to support the expanded validator set. +6. [light-client] Verify consensus proofs independently on mobile or IoT-class hardware. - - Gossipsub v2 for throughput and DOS-resilience. - - Rateless set reconciliation to support large validator sets. +## Guarantees & threat model -6. Enable full light-client verification on minimal devices +Guarantees: - - Small-footprint consensus proofs verifiable on mobile/IoT class hardware. +- Protocol stability: after the upgrade, consensus enters a phase of minimal change. +- Post-quantum resilience for the core signature layer. +- Lower barriers to solo validation, improving validator decentralization. +- Light-client verification of full consensus rules on minimal hardware. +- Clear scope: consensus only; execution-layer scaling and privacy are handled by separate tracks. -## Guarantees (intended outcomes) +Threat model: -- Protocol ossification, after the Lean fork, consensus enters long-term stability / minimal changes. -- Post-quantum resilience, core signatures hardened against quantum adversaries. -- Validator decentralization, vastly increased solo staking due to lower hardware & stake requirements. -- Universal light clients, full consensus verification without trust assumptions. - DOUBT -- Clear boundaries, lean modifies consensus _only_, execution-layer scaling & privacy handled by separate tracks. +- Cryptanalysis of the chosen hash-based multisignature and its aggregation must hold. +- The minimal zkVM must be sound and formally verified; a flaw compromises the compressed proofs. +- Networking upgrades must preserve liveness under large validator counts and adversarial churn. +- Coordination risk: if one research track fails to ship, the bundled fork is delayed. +- Out of scope: transaction privacy, execution scaling, MEV dynamics. ## Trade-offs -- Timeline risk: 4–5 year horizon with heavy reliance on open research questions -- Single large fork: Failure at any component delays entire bundle -- Research coupling: PQ signatures, zkVMs, and P2P upgrades must all reach production readiness -- Consensus-only scope: Does not address L1 execution scaling or transaction privacy -- **CROPS context (both)**: Privacy could reach `full` by incorporating post-quantum-safe ZK primitives for private validator participation and confidential state proofs. Security could reach `high` once formal verification of PQ signature aggregation and full cryptanalysis of hash-based schemes are completed. In I2I, post-quantum privacy primitives enable institutions to participate in validation without exposing staking positions to competitors. In I2U, formally verified consensus gives end users stronger guarantees that light-client proofs on minimal devices are trustworthy. +- Multi-year horizon with heavy dependence on open research questions across cryptography, proof systems, and networking. +- Single bundled fork means a failure in one component delays the entire upgrade. +- Consensus-only scope: does not address execution-layer scaling or transaction privacy. +- Coordination across many client teams adds engineering overhead but also resilience. -## Example (illustrative) +## Example -A consumer-grade laptop runs a solo validator at a much lower stake threshold. A minimal zkVM compresses committee signatures off-chain into a single proof verifiable in milliseconds. The network operates at ~4-second slots with low-slot-count fast finality. A mobile phone verifies the full consensus rules independently. After rollout, Ethereum’s consensus remains stable for decades. +A consumer-grade laptop runs a solo validator at a stake threshold around 1 ETH. A minimal zkVM compresses committee signatures off chain into a single proof that any node verifies in milliseconds. The network operates at roughly four-second slots with a fast-finality variant under evaluation. A mobile phone verifies the full consensus rules independently. ## See also diff --git a/patterns/pattern-mixnet-anonymity.md b/patterns/pattern-mixnet-anonymity.md index d04a9b6..ec1027a 100644 --- a/patterns/pattern-mixnet-anonymity.md +++ b/patterns/pattern-mixnet-anonymity.md @@ -1,86 +1,107 @@ --- title: "Pattern: Mixnet Anonymity" status: draft -maturity: PoC +maturity: testnet +type: standard layer: offchain -privacy_goal: Hide sender identity by batching, delaying, reordering, and padding messages with cover traffic -assumptions: Threshold trust across mix nodes; sufficient cover traffic and adoption to raise timing-correlation cost -last_reviewed: 2026-04-14 +last_reviewed: 2026-04-22 + works-best-when: - - The threat model includes a global passive adversary capable of traffic correlation - - Strongest possible anonymity guarantees are required - - Higher latency (seconds to minutes) is acceptable + - The threat model includes a global passive adversary capable of traffic correlation. + - Strong sender-anonymity guarantees are required against network-level observers. + - Latency of seconds to minutes is acceptable for the target workload. avoid-when: - - Low latency is critical (real-time DeFi, intraday trading) - - Bandwidth overhead from cover traffic is prohibitive - - Simpler approaches (onion routing, TEE-assisted) meet the threat model -dependencies: - - Mix node network (Nym, HOPR) - - Client-side cover-traffic generation + - Real-time latency is required (interactive DeFi, intraday trading). + - Bandwidth overhead from cover traffic is prohibitive for the deployment. + - A lower-overhead network-anonymity primitive already meets the threat model. + context: both +context_differentiation: + i2i: "Between institutions the mixnet hides query patterns and transaction timing from counterparty infrastructure and from network-level observers. Both parties can adopt the same routing discipline, and the anonymity set includes other institutional traffic." + i2u: "For user-facing deployments the operator of the RPC endpoint or the wallet backend is often the adversary. The mixnet reduces the operator's ability to correlate incoming queries with specific users by disrupting timing and ordering. Protection strength depends on cover traffic volume, adoption, and route quality, none of which the user can verify unilaterally." + crops_profile: cr: medium - os: partial - privacy: partial - security: medium + o: partial + p: partial + s: medium + +crops_context: + cr: "Operating a mix node typically requires staking, so the node set is gated by economic participation. On-chain censorship of mix-routed transactions is no easier than for direct transactions." + o: "Core mixnet stacks are open source, but live networks have governance constraints on who can operate mix nodes and how rewards are distributed." + p: "Sender-anonymity against traffic correlation is strong under sufficient cover volume. Content privacy must be handled by a separate layer; on-chain side channels also persist." + s: "Resistance to correlation depends on sustained cover traffic, correct network operation, and the anonymity-set size during the mixing window." + +post_quantum: + risk: medium + vector: "Sphinx packet encryption today uses EC-based key exchange; HNDL risk applies to anyone recording mix traffic." + mitigation: "Migrate the key-encapsulation step of the packet format to a post-quantum KEM such as ML-KEM." + +standards: [] + +related_patterns: + alternative_to: [pattern-onion-routing, pattern-tee-network-anonymity] + composes_with: [pattern-private-transaction-broadcasting, pattern-threshold-encrypted-mempool, pattern-shielding] + see_also: [pattern-network-anonymity, pattern-modular-privacy-stack] + +open_source_implementations: + - url: https://github.com/nymtech/nym + description: "Nym mixnet reference implementation (Sphinx packets, Loopix-style mixing)" + language: Rust + - url: https://github.com/hoprnet/hoprnet + description: "HOPR mixnet protocol stack" + language: Rust --- ## Intent -Hide *who* is sending transactions or querying state by routing messages through a network of mix nodes that batch, delay, reorder, and pad traffic with cover messages. Mixnets provide stronger anonymity than onion routing against global passive adversaries because timing correlation is defeated by design. This comes at the cost of higher latency and bandwidth overhead. +Hide who is sending a transaction or querying state by routing messages through a network of mix nodes that batch, delay, reorder, and pad traffic with cover messages. Mixnets provide stronger sender anonymity than onion routing against global passive adversaries because timing correlation is defeated by design, at the cost of higher latency and bandwidth overhead. + +## Components -## Ingredients +- Sphinx packet format: layered, constant-size encryption so that intermediate nodes cannot tell packets apart by size or content. +- Mix-and-shuffle discipline at each node: incoming packets are batched, reordered, delayed, and then forwarded. +- Cover traffic generated by clients and by the mix nodes themselves to keep traffic volume constant regardless of real demand. +- Client SDK or SOCKS5 proxy that wraps outgoing RPC or transaction traffic before submission. +- Mix node network with reward and slashing mechanics that gate participation and fund cover-traffic generation. -- Cryptographic: Sphinx packet format, cover traffic generation, mix-and-shuffle -- Infra: mix node network (Nym, HOPR), SOCKS5 proxy or SDK integration -- Standards: Loopix architecture, Sphinx packet specification +## Protocol -## Protocol (concise) +1. [user] Wrap the outbound message (RPC query or transaction) in a Sphinx packet with layered encryption. +2. [user] Send the packet to the entry mix node on a randomly chosen multi-hop route. +3. [mix-node] Collect incoming packets, add a random delay, reorder the batch, strip one encryption layer, and forward. +4. [mix-node] Inject cover packets at each hop to maintain constant traffic volume. +5. [exit-mix] Deliver the unwrapped message to its destination (RPC node, mempool, or application endpoint). +6. [user] Receive any response through a separate mixnet route. -1. Client wraps the message (RPC query or transaction) in a Sphinx packet with layered encryption. -2. Client sends the packet to the entry mix node in a randomly selected route. -3. Each mix node collects incoming packets, adds random delay, reorders the batch, and strips one encryption layer before forwarding. -4. Cover traffic (dummy packets) is injected at each hop to maintain constant traffic volume. -5. Final mix node delivers the message to the destination (RPC node, mempool). -6. Response returns through a separate mixnet route. +## Guarantees & threat model -## Guarantees +Guarantees: -- Under sufficient cover-traffic volume and wide adoption, mixnets substantially raise the cost of timing correlation and can resist global passive adversaries, threats that onion routing is vulnerable to. Guarantees degrade as cover traffic and anonymity-set size shrink. -- Anonymity set includes all clients active during the mixing window. -- Does not hide message content; pair with content-privacy patterns for full-stack privacy. -- **I2U**: the anonymity set is external to the institution. Even if the institution operates the RPC endpoint, mixnets reduce its ability to correlate incoming queries with specific users by disrupting timing and ordering signals; protection strength depends on cover volume, adoption, and route quality. -- **I2I**: institutions can hide query patterns and transaction timing from counterparty infrastructure and from network-level observers. +- Sender anonymity against timing correlation when cover traffic volume and anonymity-set size are sufficient. +- Anonymity set covers all clients active during the mixing window. +- The pattern does not hide message content; pair it with content-privacy patterns for a full stack. + +Threat model: + +- Global passive adversaries who record all links: mitigated by cover traffic and mixing delays, subject to enough active users. +- Active adversaries that compromise a full route of mix nodes; resistance comes from route diversity and from requiring the adversary to control every hop. +- Low-adoption regimes: when the anonymity set is small the effective guarantee degrades sharply. +- On-chain metadata (contract calls, account reuse, exit addresses) is out of scope and must be handled at other layers. ## Trade-offs -- Very high latency (seconds to minutes by design) makes mixnets unsuitable for real-time use cases. +- Latency is high by design, often in seconds to minutes; real-time use cases are not a fit. - Cover traffic adds bandwidth cost proportional to the desired anonymity level. -- Anonymity set size depends on actual usage volume; low adoption creates a chicken-and-egg problem. -- No production Ethereum-specific deployment as of 2026-04. Nym mainnet is live as a general-purpose mixnet as of 2026-04; blockchain integrations are in development. -- HOPR's RPCh (private RPC via mixnet) had a working prototype but [development is paused](https://github.com/Rpc-h/RPCh) as of 2026-04 (team redirected to [Gnosis VPN](https://gnosisvpn.com/)). -- CROPS: CR is `medium` because mix node participation requires staking. OS is `partial` (Nym and HOPR are open-source but the live networks have governance constraints). Privacy is `partial` because on-chain side channels persist. Security is `medium` because resistance to correlation depends on sustained cover traffic volume, adoption, and correct network operation. +- Effective anonymity depends on adoption; low-usage deployments face a chicken-and-egg problem. +- Ethereum-native integration is still maturing: live general-purpose mixnets exist but dedicated blockchain integrations are in development or paused. Some mixnet-based private RPC projects were prototyped and then paused as teams redirected effort to VPN-style products. ## Example -1. Compliance team at a custodian needs to query transaction histories for regulatory reporting without revealing which accounts they monitor. -2. Queries are routed through a 5-hop mixnet: each hop batches, delays, and reorders traffic. -3. Cover traffic ensures the RPC provider sees constant query volume regardless of actual activity. -4. RPC provider cannot determine when the custodian queried, which queries came from the same source, or how many real queries were made. -5. Latency (several seconds per query) is acceptable for batch compliance reporting. +A compliance team at a custodian needs to query transaction histories for regulatory reporting without revealing which accounts are being monitored. Queries are routed through a five-hop mixnet where each hop batches, delays, and reorders traffic. Cover traffic keeps the RPC provider's view of query volume constant. The provider cannot determine when the custodian queried, which queries came from the same source, or how many real queries were made. Several seconds of latency per query is acceptable for batch compliance reporting. ## See also -- [Network-Level Anonymity](pattern-network-anonymity.md) - umbrella pattern and approach comparison -- [Onion Routing](pattern-onion-routing.md) - lower latency but weaker against global adversaries -- [TEE-Assisted Network Anonymity](pattern-tee-network-anonymity.md) - low-latency alternative using hardware trust -- [Private Transaction Broadcasting](pattern-private-transaction-broadcasting.md) - complementary content-privacy pattern for mempool-level protection -- [Threshold Encrypted Mempool](pattern-threshold-encrypted-mempool.md) - complementary content-privacy pattern for pre-inclusion encryption -- [Modular Privacy Stack](pattern-modular-privacy-stack.md) - where network anonymity fits in the four-layer architecture - -## See also (external) - - Nym Network: https://nym.com/network -- Nym + Aztec partnership: https://nym.com/blog/nym-partners-with-aztec-to-provide-integral-infrastructure-privacy-in-ethereum-chains -- NymVPN dApp mode (wallet RPC routing): https://nym.com/blog/nymvpn-dapp-mode - HOPR protocol: https://hoprnet.org/ +- Loopix paper (mixnet design): https://www.usenix.org/conference/usenixsecurity17/technical-sessions/presentation/piotrowska diff --git a/patterns/pattern-modular-privacy-stack.md b/patterns/pattern-modular-privacy-stack.md index 2c00810..f10e382 100644 --- a/patterns/pattern-modular-privacy-stack.md +++ b/patterns/pattern-modular-privacy-stack.md @@ -1,120 +1,133 @@ --- title: "Pattern: Modular Privacy Stack" status: draft -maturity: PoC +maturity: concept +type: meta layer: hybrid -privacy_goal: Enable flexible privacy architecture where each layer can be independently selected and upgraded -assumptions: Clear layer boundaries, standardized interfaces between layers, institutional compliance requirements -last_reviewed: 2026-01-16 +last_reviewed: 2026-04-22 + works-best-when: - - Different privacy requirements exist for different transaction phases - - Organization needs flexibility to swap components without full redesign - - Hybrid deployments span multiple environments (L1, L2, off-chain) + - Different privacy requirements apply to different transaction phases. + - The organization needs to swap components without redesigning the full stack. + - Hybrid deployments span multiple environments (L1, L2, off-chain). avoid-when: - - Uniform end-to-end privacy is mandatory with single-vendor solution - - Simple single-domain use cases with minimal privacy needs - - Tight latency requirements preclude layer coordination overhead -dependencies: - - ERC-7573 - - ERC-3643 - - EAS - - EIP-4844 + - Uniform end-to-end privacy is mandatory under a single vendor contract. + - A single-domain use case has minimal privacy needs. + - Tight latency targets rule out layer coordination overhead. + context: both +context_differentiation: + i2i: "Between institutions the layered model lets counterparties agree on interfaces (data references, settlement proofs, disclosure artifacts) without locking the stack to one vendor per layer. Decentralized orchestration prevents any single provider from gatekeeping settlement." + i2u: "For user-facing deployments per-layer exit paths matter: a user must be able to withdraw assets even if one layer's operator becomes unresponsive. Disclosure controls should protect the user from forced correlation across layers." + crops_profile: cr: medium - os: partial - privacy: partial - security: medium + o: partial + p: partial + s: medium + +crops_context: + cr: "Reaches `high` when routing is permissionless and each layer offers an independent exit path. Drops when orchestration concentrates in a single operator or when a settlement layer uses permissioned sequencing." + o: "Improves to `yes` when reference implementations of each layer interface are published and orchestration logic is open source; today vendor SDKs dominate." + p: "Layer isolation contains data leaks, but cross-layer routing reveals timing and access patterns. Reaches `full` only with end-to-end encryption between layers and metadata scrubbing at routing boundaries." + s: "Depends on the weakest layer plus the orchestrator. Threshold cryptography for cross-layer key management and elimination of single-operator trust in orchestration raise this to `high`." + +post_quantum: + risk: medium + vector: "PQ exposure is inherited from the chosen primitives at each layer: EC-based ZK execution layers are HNDL-exposed; TEE attestations rely on vendor signing keys; DA blobs encrypted with classical KEMs are recordable." + mitigation: "Select PQ-resilient primitives per layer (STARK-based execution, hash-based signatures, ML-KEM for key encapsulation) and include PQ readiness in the cross-layer evaluation." + +standards: [ERC-7573, ERC-3643, EIP-4844, EAS] + +related_patterns: + composes_with: [pattern-privacy-l2s, pattern-commit-and-prove, pattern-dvp-erc7573, pattern-regulatory-disclosure-keys-proofs, pattern-tee-based-privacy, pattern-l2-encrypted-offchain-audit] + see_also: [pattern-shielding, pattern-l2-privacy-evaluation] + +sub_patterns: + - name: "Data layer" + pattern: pattern-l2-encrypted-offchain-audit + crops_summary: "Encrypted storage with DA anchoring; privacy depends on key management" + - name: "Execution layer (ZK)" + pattern: pattern-privacy-l2s + crops_summary: "Cryptographic privacy; HNDL risk on EC-based systems" + - name: "Execution layer (TEE)" + pattern: pattern-tee-based-privacy + crops_summary: "Hardware trust; mitigates prover cost but introduces vendor attestation dependency" + - name: "Settlement layer" + pattern: pattern-dvp-erc7573 + crops_summary: "Atomic cross-chain settlement anchored to L1 finality" + - name: "Disclosure layer" + pattern: pattern-regulatory-disclosure-keys-proofs + crops_summary: "View keys, ZK proofs, and attestations for scoped audit access" --- ## Intent -Define a four-layer privacy architecture where **Data**, **Execution**, **Settlement**, and **Disclosure** are distinct concerns, each addressable by different technologies. This enables institutions to select best-fit components per layer while maintaining interoperability and upgrade paths. - -## Ingredients - -### Standards -- **ERC-7573**: Atomic DvP settlement across networks -- **ERC-3643**: Compliant security tokens with identity hooks -- **EAS**: Ethereum Attestation Service for disclosure proofs -- **EIP-4844**: Blob transactions for data availability - -### Infrastructure by Layer - -| Layer | Responsibility | Options | -|-------|----------------|---------| -| **Data** | Store/retrieve encrypted data | Off-chain encrypted storage, DA layers (EigenDA, Celestia), L2 blobs, IPFS+encryption | -| **Execution** | Private computation | ZK (Aztec, Miden), FHE (Zama, Fhenix), TEE enclaves | -| **Settlement** | Finality, atomicity | Ethereum L1, Arbitrum, Optimism, ZKsync | -| **Disclosure** | Regulatory access | View keys, ZK proofs, threshold KMS, EAS attestations | - -### Off-chain Services -- Key management systems per layer -- Cross-layer routing and orchestration -- Audit log aggregation +Compose a privacy architecture from four distinct layers: Data, Execution, Settlement, and Disclosure. Each layer is addressed by an interchangeable technology so that institutions can select the best-fit primitive per layer, upgrade layers independently, and keep interoperability through standardized interfaces. -## Protocol (concise) +## Components -1. **Define layer boundaries** - Map each transaction phase to a layer. Identify which data stays in Data layer, what computation runs in Execution, where finality occurs (Settlement), and who needs access (Disclosure). +- **Data layer** stores and retrieves encrypted payloads. Options include off-chain encrypted storage, data-availability layers, L1 blob data, and content-addressed networks with encryption. +- **Execution layer** runs private computation. Options include zero-knowledge execution environments, fully homomorphic encryption, and trusted execution environments. +- **Settlement layer** provides finality and atomicity. Options include L1, validity-proof rollups, optimistic rollups, and cross-chain atomic swap protocols. +- **Disclosure layer** exposes scoped access for audit and compliance. Options include viewing keys, zero-knowledge proofs of properties, threshold key management, and on-chain attestations. +- **Interface contracts** define what each layer consumes and emits: encrypted reads and writes for Data, state transitions for Execution, proofs and signed transactions for Settlement, and disclosure artifacts for Disclosure. +- **Orchestration service** routes references and coordinates cross-layer flows; it aggregates audit logs across layers. -2. **Configure layer interfaces** - Establish standardized APIs between layers: Data layer exposes encrypted reads/writes, Execution layer consumes data references and produces state transitions, Settlement layer accepts proofs or signed transactions. +If a component is itself a pattern in this map (see `sub_patterns` and `related_patterns`), link it rather than describe it in depth. -3. **Route data to storage** - Encrypt sensitive transaction data and store via the Data layer. Return content-addressed references (hashes, blob IDs) for downstream layers to consume. +## Protocol -4. **Execute private computation** - The Execution layer retrieves encrypted data references, performs computation (ZK proof generation, FHE operations, or TEE execution), and outputs a verifiable state transition or proof. +1. [architect] Map each transaction phase to a layer: what data stays in Data, what runs in Execution, where finality happens, and who needs scoped access. +2. [architect] Pin the interface between each pair of layers: content-addressed references at Data, state-transition objects at Execution, proof or signed-transaction envelopes at Settlement. +3. [user] Encrypt sensitive inputs and submit them to the Data layer; receive a content-addressed reference. +4. [executor] Retrieve the reference, run the private computation, and emit a state transition or proof. +5. [contract] Verify the proof or signed transaction on the Settlement layer; commit state atomically across legs when needed. +6. [user] Emit disclosure artifacts (viewing keys, proofs of properties, attestations) for the Disclosure layer and grant scoped access to authorized parties. +7. [auditor] Reconstruct the cross-layer audit trail from data hashes, execution proofs, settlement transaction identifiers, and disclosure events. -5. **Settle on target chain** - Submit the execution proof or transaction to the Settlement layer. Settlement may be on L1 for maximum security or L2 for lower cost. ERC-7573 enables atomic multi-leg settlement. +## Guarantees & threat model -6. **Generate disclosure artifacts** - Produce disclosure proofs, view keys, or attestations as required by the Disclosure layer. These enable authorized parties (regulators, auditors, counterparties) to verify or inspect specific data. +Guarantees: -7. **Log cross-layer audit trail** - Record layer transitions and references in an audit log. Each layer contributes its own audit data (data hashes, execution proofs, settlement txids, disclosure events). +- Layer isolation: a compromise or failure in one layer does not expose plaintext held by another, provided interfaces are honored. +- Upgradability: a layer can be replaced without redesigning the others, as long as the interface contract holds. +- Cross-layer audit: the combined trail is reconstructible from per-layer evidence. +- Failure containment: when Execution fails, Settlement reverts without affecting stored Data. -## Guarantees +Threat model: -- **Layer isolation**: Compromise or failure in one layer does not expose data in others. Data layer encryption persists regardless of execution layer state. -- **Composability**: Layers can be independently upgraded or swapped (e.g., migrate from TEE execution to ZK without changing settlement). -- **Auditability**: Cross-layer audit trail enables reconstruction of transaction flow for compliance. -- **Failure containment**: Settlement layer defines atomicity; if execution fails, settlement reverts without affecting stored data. +- Interface assumption: the guarantees hold only when each layer honors its interface contract. A misbehaving adapter between layers can bridge data from one to another. +- Orchestrator trust: a malicious orchestrator can correlate references and disclose timing and access patterns even when payloads stay encrypted. +- Metadata leakage: cross-layer routing discloses timing and size patterns; these are out of scope for the individual layers and must be addressed at the orchestration layer or with network-anonymity primitives. +- Key management: if disclosure keys are held by a single operator, the Disclosure layer inherits that operator's trust profile. +- Weakest-layer bound: the privacy guarantee is the minimum of what each layer provides for its part of the flow. ## Trade-offs -- **Coordination complexity**: Multiple layers require orchestration logic, increasing system complexity and operational overhead. -- **Latency accumulation**: Each layer adds processing time; four layers compound delays compared to monolithic solutions. -- **Interface rigidity**: Standardized interfaces may constrain layer-specific optimizations or require adaptation layers. -- **Tooling fragmentation**: Different vendors per layer means multiple SDKs, monitoring tools, and support relationships. -- **Metadata leakage**: Even with encrypted data, cross-layer routing can reveal timing, access patterns, and transaction graph information. -- **CROPS context (both)**: CR could reach `high` if layer routing is permissionless with decentralized orchestration nodes and independent exit paths per layer. OS improves to `yes` by releasing reference implementations for each layer interface. Privacy could reach `full` by mandating end-to-end encryption between layers with no metadata cleartext at routing boundaries. Security could reach `high` by eliminating single-operator trust in orchestration and using threshold cryptography for cross-layer key management. In I2I, decentralized orchestration prevents any single infrastructure provider from gatekeeping settlement between counterparties. In I2U, permissionless exit paths per layer ensure end users can withdraw assets even if one layer's operator becomes unresponsive or adversarial. +- Coordination complexity: the orchestration logic adds operational surface and more moving parts than a monolithic stack. +- Latency accumulation: four layers in sequence compound delays relative to an integrated solution. +- Interface rigidity: stable interfaces can constrain layer-specific optimizations and may need adapter layers over time. +- Tooling fragmentation: multiple SDKs, monitoring stacks, and support relationships follow from mixing vendors per layer. +- Metadata leakage at routing boundaries is the residual risk even when all per-layer payloads are encrypted. ## Example -**Institutional bond settlement with modular stack:** +A tokenized-bond issuance uses a modular stack: -- **Data layer**: Bond terms and investor details encrypted with AES-256, stored in off-chain encrypted storage. Content hash published to DA layer for availability guarantees. -- **Execution layer**: Aztec private contracts compute allocation and verify investor eligibility via ZK proofs. Execution produces a settlement instruction with proof of valid state transition. -- **Settlement layer**: ERC-7573 atomic DvP on Ethereum L1. Bond tokens transfer to buyer, payment token transfers to seller, or both revert. -- **Disclosure layer**: Issuer provides view keys to the regulator via EAS attestation. Regulator can decrypt bond terms and verify investor eligibility proofs without accessing the full transaction graph. +- Bond terms and investor details are encrypted and stored off-chain with a content hash published to a data-availability layer. +- A zero-knowledge execution environment verifies investor eligibility and computes the allocation, emitting a settlement instruction with a validity proof. +- Atomic delivery-versus-payment settles on L1: bond tokens move to the buyer and payment tokens to the seller, or both legs revert. +- The issuer grants scoped viewing keys to the regulator through an on-chain attestation. The regulator decrypts bond terms and verifies eligibility proofs without observing the full transaction graph. -This configuration allows the issuer to: -- Upgrade from Aztec to Miden for execution without changing settlement -- Add a new regulator by issuing additional view keys -- Move settlement to an L2 for cost reduction while maintaining the same privacy guarantees +The issuer can later swap the execution environment for a different ZK system, add a regulator by issuing additional viewing keys, or move settlement to a rollup for cost reduction, without rebuilding the stack. ## See also -- [Private L2s](pattern-privacy-l2s.md) - Execution layer option -- [Commit and Prove](pattern-commit-and-prove.md) - Cross-layer coordination pattern -- [Atomic DvP via ERC-7573](pattern-dvp-erc7573.md) - Settlement layer standard -- [Selective Disclosure](pattern-regulatory-disclosure-keys-proofs.md) - Disclosure layer mechanisms -- [L2 Encrypted Off-chain Audit](pattern-l2-encrypted-offchain-audit.md) - Data + disclosure combination -- [TEE-based Privacy](pattern-tee-based-privacy.md) - Execution layer option -- [Aztec](../vendors/aztec.md) - ZK execution vendor -- [Zama](../vendors/zama.md) - FHE execution vendor -- [Miden](../vendors/miden.md) - ZK VM execution vendor -- [Railgun](../vendors/railgun.md) - Privacy infrastructure +- [Aztec](../vendors/aztec.md) +- [Zama](../vendors/zama.md) +- [Miden](../vendors/miden.md) +- [Railgun](../vendors/railgun.md) +- [ERC-7573](https://eips.ethereum.org/EIPS/eip-7573) +- [ERC-3643](https://eips.ethereum.org/EIPS/eip-3643) +- [Ethereum Attestation Service](https://attest.sh/) diff --git a/patterns/pattern-mpc-custody.md b/patterns/pattern-mpc-custody.md index a2e4b52..0973883 100644 --- a/patterns/pattern-mpc-custody.md +++ b/patterns/pattern-mpc-custody.md @@ -2,74 +2,122 @@ title: "Pattern: MPC Custody and Transaction Control" status: draft maturity: production +type: standard layer: offchain -privacy_goal: Protect private keys via threshold distribution; no on-chain privacy of transactions -assumptions: Threshold ECDSA/EdDSA infrastructure, MPC nodes in TEE/HSM, policy engine -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 + works-best-when: - - Institutions require regulated-grade custody for digital assets - - Key material must never exist in one place, but transactions must be orchestrated quickly + - An institution needs regulated-grade custody for digital assets. + - Key material must never exist in one place while signing must still be quick. + - Policy-based approvals (role, limit, allowlist) are required before signing. avoid-when: - - Use cases demand non-custodial self-sovereign key management - - Full privacy of transaction metadata is required (MPC does not shield ledger data) -dependencies: [Threshold ECDSA, EdDSA, HSM/KMS] + - The workflow requires non-custodial self-sovereign key management. + - Transaction-metadata privacy is required; threshold signing does not shield ledger data. + - A single hardware security module already satisfies the threat model at lower cost. + context: both +context_differentiation: + i2i: "Between institutions the threshold-signing quorum typically maps to internal roles (operations, compliance, treasury) and to counterparty approvals. Forced L1 exit paths matter so that assets remain recoverable if the custody operator is adversarial or insolvent." + i2u: "For user-facing custody the operator is asymmetric to the user: the operator can refuse to co-sign. The user needs an independent exit path, typically an L1 timelock or a pre-signed transaction, and should be able to verify that the signing protocol is faithfully open source." + crops_profile: cr: low - os: partial - privacy: none - security: medium + o: partial + p: none + s: medium + +crops_context: + cr: "A quorum of signers can refuse to co-sign, so censorship resistance is low by default. Reaches `high` only with a forced L1 exit path (timelocked withdrawal or consensus-backed fallback multisig) alongside threshold key refresh." + o: "Core threshold-signing libraries exist in open source, but production custody stacks bundle proprietary policy engines, orchestration, and monitoring. Improves when the signing protocol and policy evaluator are published and independently auditable." + p: "The pattern does not add on-chain privacy; signed transactions carry full metadata. Pair with transaction-privacy patterns (shielding, private broadcast) when confidentiality matters." + s: "Depends on the soundness of the threshold scheme, the quality of the TEE or HSM that protects each share, and proactive key refresh. Verifiable threshold signing and periodic share rotation move this toward `high`." + +post_quantum: + risk: high + vector: "Threshold ECDSA and EdDSA are broken by a cryptographically relevant quantum computer. HNDL pressure is limited because signatures are public, but long-lived custody keys are exposed on migration day." + mitigation: "Adopt post-quantum threshold signatures (ML-DSA variants or hash-based schemes) and plan a migration with proactive share refresh. See [Post-Quantum Threats](../domains/post-quantum.md)." + +standards: [] + +related_patterns: + alternative_to: [pattern-tee-key-manager] + composes_with: [pattern-safe-proof-delegation, pattern-dvp-erc7573, pattern-private-iso20022] + see_also: [pattern-tee-zk-settlement, pattern-forced-withdrawal] + +open_source_implementations: + - url: https://github.com/ZenGo-X/multi-party-ecdsa + description: "Threshold ECDSA reference implementation (Gennaro-Goldfeder family)" + language: Rust + - url: https://github.com/taurusgroup/multi-party-sig + description: "Threshold signing library covering CMP, FROST, and related protocols" + language: Go + - url: https://github.com/LFDT-Lockness/cggmp21 + description: "CGGMP21 threshold ECDSA implementation" + language: Rust --- ## Intent -Provide secure custody and controlled execution of digital asset transactions by distributing key shares across MPC nodes. Eliminates single points of compromise while enabling policy-based transaction approvals for institutional workflows. +Provide custody and controlled execution of digital-asset transactions by distributing key shares across a set of signers that jointly produce a valid signature without ever reconstructing the private key. The pattern eliminates single points of key compromise and enforces policy-based approvals before any signature is released. + +## Components -## Ingredients +- **Threshold signature scheme** such as threshold ECDSA or threshold EdDSA; an `m`-of-`n` quorum produces a signature indistinguishable from a single-key signature. +- **Signing nodes** run inside hardened environments (trusted execution environments or hardware security modules) and hold one key share each. +- **Policy engine** validates each signing request against transaction limits, destination allowlists, and role-based approvals before releasing the signing request to the nodes. +- **Orchestration API** exposes request submission, approval workflow, audit events, and status queries to client applications. +- **Key-generation ceremony** creates the shares without ever materializing the full key; proactive key refresh rotates shares while keeping the public key stable. +- **Audit log** records signing attempts, approvals, denials, and share-refresh events for compliance review. +- **Target chain** (L1 or L2) that ultimately receives the signed transaction. -- Threshold signing algorithms (e.g., threshold ECDSA, EdDSA) -- MPC infrastructure (nodes run in TEEs or HSM-backed environments) -- Orchestration APIs for approval policies and transaction initiation -- Underlying L1/L2 networks (Ethereum, Polygon, permissioned ledgers) -- Optional registry/KYC integration for compliance +## Protocol -## Protocol (concise) +1. [institution] Define the custody policy: quorum `m`-of-`n`, role approvals, allowlists, and transaction limits. +2. [operator] Run a distributed key generation so that each signing node receives a share; no node ever holds the full private key. +3. [user] Submit a signing request through the orchestration API. +4. [policy-engine] Validate the request against the policy (limits, allowlists, required approvals) and either release it to the signing nodes or reject it. +5. [signing-node] Participate in the threshold-signing protocol with the other nodes; each node contributes a partial signature using its share. +6. [orchestrator] Combine partial signatures into a valid signature and broadcast the signed transaction to the target chain. +7. [auditor] Consult the audit log to verify policy evaluation, the quorum that signed, and any refused requests. -1. Institution defines custody policy (signing quorum, role approvals). -2. Private key is generated in shares across MPC nodes; no single node holds full key. -3. Transaction request initiated via API. -4. Policy engine validates request (limits, whitelists, approvals). -5. MPC nodes run threshold signing protocol to produce valid signature. -6. Transaction broadcast to underlying network. -7. Audit logs and ops signals generated for compliance review. +## Guarantees & threat model -## Guarantees +Guarantees: -- **Key privacy**: private key never reconstructed in a single place. -- **Control**: fine-grained policies enforce who/what can sign. -- **Auditability**: full ops trail for regulatory compliance. -- **Finality**: signature validity guaranteed if quorum threshold met. +- Key privacy: the private key is never reconstructed at a single location. +- Access control: a signature is released only when the quorum approves and the policy evaluates to true. +- Auditability: an end-to-end operations trail records approvals, denials, and signing events. +- Signature validity: if the quorum threshold is met, the resulting signature is verifiable by any chain that accepts the underlying scheme. + +Threat model: + +- Quorum compromise: if `m` nodes collude, the key is compromised; choose `m` and `n` accordingly and isolate nodes across operational domains. +- Policy-engine trust: a compromised or misconfigured policy engine can release signatures that violate the intended rules; combine with offline approvals for high-value flows. +- Operator censorship: a malicious or unresponsive operator can refuse to co-sign and freeze assets; an L1 exit path is required to mitigate this. +- Side channels: nodes that run in shared hardware or leaky TEEs can leak share material; rotate shares proactively and use attested enclaves. +- Out of scope: transaction-graph privacy and on-chain metadata protection. Signed transactions carry their usual public footprint. ## Trade-offs -- **Performance**: threshold signing introduces latency vs. HSM signing. -- **Cost**: requires distributed infra + MPC coordination. -- **Failure modes**: node outage can block signing if quorum not met. -- **Trust assumptions**: relies on vendor’s MPC infrastructure and orchestration. -- **Operator censorship**: MPC operator or policy engine can refuse to co-sign; no unilateral user exit path. -- **CROPS context (both)**: CR could reach `high` if consensus-backed multi-sig with forced exit via L1 timelock is implemented alongside threshold key refresh. OS improves to `yes` by open-sourcing the core MPC signing protocol. Privacy could reach `full` by adding threshold encryption of transactions before policy evaluation. Security could reach `high` by adopting verifiable threshold signing with proactive key refresh. In I2I, forced L1 exit paths ensure institutions can recover assets even if the MPC operator becomes adversarial or insolvent. In I2U, open-source signing protocols let end users verify that custody providers cannot unilaterally access or freeze their assets. -- **Post-quantum exposure**: threshold ECDSA/EdDSA is broken by CRQC (not HNDL-urgent — signatures are public). Mitigation: ML-DSA or hash-based threshold schemes. See [Post-Quantum Threats](../domains/post-quantum.md). +- Performance: threshold signing adds latency relative to a single HSM; interactive protocols require several network rounds among the signing nodes. +- Cost: distributed infrastructure and continuous monitoring cost more than a single HSM deployment. +- Failure modes: if fewer than `m` nodes are reachable, no signature can be produced; geographic and operational diversity trade availability against quorum safety. +- Vendor trust: many production deployments rely on a vendor's signing protocol, policy engine, and attested hardware; open-source alternatives exist but often lack equivalent operational tooling. +- Operator censorship remains the core residual risk: without a forced exit path the custody operator can refuse to co-sign and freeze assets. ## Example -- Bank A wants to issue a tokenized bond on Ethereum. -- Custody policy: 2-of-3 signing nodes (compliance, operations, treasury). -- Operations desk initiates transfer; compliance approves via dashboard. -- MPC nodes collectively sign without revealing full private key. -- Transaction is broadcast, bond tokens move to investor’s address. +A bank issues a tokenized bond on Ethereum under a 2-of-3 custody policy across compliance, operations, and treasury. + +- The operations desk initiates a transfer through the orchestration API. +- The policy engine checks the destination allowlist and the transaction limit, then notifies compliance for approval. +- Compliance approves via the dashboard; the two signing nodes run the threshold-signing protocol and emit a combined signature. +- The signed transaction is broadcast; bond tokens move to the investor address. +- The audit log records the approval path, the quorum members that signed, and the resulting transaction hash. ## See also -- Pattern: [TEE-ZK Settlement](../patterns/pattern-tee-zk-settlement.md) -- Pattern: [Private ISO20022](../patterns/pattern-private-iso20022.md) -- Pattern: [DvP ERC-7573](../patterns/pattern-dvp-erc7573.md) +- [Fireblocks](../vendors/fireblocks.md) +- [FROST specification](https://datatracker.ietf.org/doc/draft-irtf-cfrg-frost/) +- [CGGMP21 paper](https://eprint.iacr.org/2021/060) +- [Post-Quantum Threats](../domains/post-quantum.md) diff --git a/patterns/pattern-native-account-abstraction.md b/patterns/pattern-native-account-abstraction.md index 7591aa7..7e15c1b 100644 --- a/patterns/pattern-native-account-abstraction.md +++ b/patterns/pattern-native-account-abstraction.md @@ -1,66 +1,98 @@ --- title: "Pattern: Native Account Abstraction (EIP-8141)" status: draft -maturity: draft -layer: L1 | L2 -privacy_goal: Programmable account validation enabling auth agility, gas sponsorship, and privacy-preserving transaction submission -assumptions: EIP-8141 adoption, wallet ecosystem support, transaction frame model -last_reviewed: 2026-03-18 +maturity: concept +type: standard +layer: L1 +last_reviewed: 2026-04-22 + works-best-when: - - Multiple signature schemes must coexist (ECDSA, PQ, passkeys) - - Stealth address or shielded pool recipients need gas without pre-funding - - Protocol must support future cryptographic migrations without address changes + - Multiple signature schemes must coexist (ECDSA, post-quantum, passkeys). + - Stealth address or shielded pool recipients need gas without pre-funding. + - Protocol must support future cryptographic migrations without address changes. avoid-when: - - Current EOA + ECDSA model is sufficient - - No PQ or auth agility requirements -dependencies: [EIP-8141] + - Current EOA and ECDSA model is sufficient. + - No post-quantum or auth agility requirements. + context: both +context_differentiation: + i2i: "Institutions can mandate organisation-wide validation policies (for example, post-quantum-only signatures, multi-party approvals, per-role gas budgets) on accounts they control. Both parties retain legal recourse for operational failures and counterparties can audit validation code." + i2u: "End users choose their own validation logic (passkeys, multisig, post-quantum signatures) without institutional lock-in. Crucially, native gas sponsorship removes the trusted relayer that today links stealth-address recipients to a funding account, so users are not forced to trust an operator to transact." + crops_profile: cr: high - os: yes - privacy: partial - security: high + o: yes + p: partial + s: high + +crops_context: + cr: "High on L1 because transactions flow through the regular mempool. Eliminates the ERC-4337 bundler bottleneck and the relayer dependency that today gates stealth-address and shielded-pool withdrawals." + o: "EIP process is open; reference implementations will be open-source. Validation code is per-account and forkable." + p: "Does not itself hide transaction content. Privacy gains come indirectly by removing relayer centralisation, enabling gas sponsorship without linking entry and exit addresses, and letting accounts rotate to post-quantum signatures without moving funds." + s: "Strong when validation code is audited or drawn from standardised libraries. Shifts auditing burden from protocol developers to account owners; bugs in custom validation can lock or drain accounts." + +post_quantum: + risk: low + vector: "Per-account validation decouples the signature scheme from the address. Accounts can rotate ECDSA to ML-DSA or SLH-DSA without redeploying or moving funds." + mitigation: "Direct enabler of post-quantum migration on the execution layer. See [Post-Quantum Threats](../domains/post-quantum.md)." + +standards: [EIP-8141] + +related_patterns: + composes_with: [pattern-stealth-addresses, pattern-shielding] + see_also: [pattern-permissionless-spend-auth, pattern-lean-ethereum] + +open_source_implementations: + - url: https://eips.ethereum.org/EIPS/eip-8141 + description: "EIP-8141 specification (draft)" + language: "Specification" --- ## Intent -Make every Ethereum account natively programmable: replace the hardcoded ECDSA `ecrecover` check with user-defined validation logic at the protocol level. Unlike ERC-4337 (which routes transactions through bundlers and a separate mempool), EIP-8141 processes transactions through the regular mempool using transaction frames that separate validation from execution. This eliminates bundler dependency, enables native gas sponsorship, and unlocks privacy patterns that today require trusted relayers. +Make every Ethereum account natively programmable by replacing the hardcoded ECDSA `ecrecover` check with user-defined validation logic at the protocol level. Transactions are processed through the regular mempool using transaction frames that separate validation from execution. The design removes bundler and relayer dependencies, enables native gas sponsorship, and unlocks privacy patterns that currently require trusted off-protocol infrastructure. -## Ingredients +## Components -- **Standards**: EIP-8141 (native account abstraction via Frame Transactions) -- **Account validation code**: per-account logic executed in VERIFY frames; can verify any signature scheme (ECDSA, ML-DSA, SLH-DSA, passkeys, multisig) or ZK proofs, and must call the `APPROVE` opcode to authorize the transaction -- **Frame model**: ordered list of frames per transaction, each with a mode (VERIFY, SENDER, DEFAULT), target, gas limit, and data. Frames execute sequentially with independent gas metering -- **APPROVE opcode**: called within VERIFY frames to authorize execution (`0x0`), payment (`0x1`), or both (`0x2`). Payment approval determines who pays gas at runtime, enabling separation in authorising execution of the transaction and gas payment. +- **Frame transaction**: ordered list of frames per transaction. Each frame specifies a mode (`VERIFY`, `SENDER`, `DEFAULT`), target address, gas limit, and data. Frames execute sequentially with independent gas metering. +- **Account validation code**: per-account logic executed inside `VERIFY` frames. It can validate any signature scheme (ECDSA, ML-DSA, SLH-DSA, passkeys, multisig) or any ZK proof. +- **`APPROVE` opcode**: called inside `VERIFY` frames to authorise execution (`0x0`), payment (`0x1`), or both (`0x2`). Payment approval decides who pays gas at runtime, decoupling authorisation of execution from gas payment. +- **Regular mempool**: carries frame transactions alongside legacy transactions. No separate mempool or bundler network. ## Protocol -1. **Frame transaction.** User submits `Frame` Transaction containing an ordered list of frames. Each frame specifies a mode (`VERIFY`, `SENDER`, or `DEFAULT`), a target address, a gas limit, and data. The transaction goes to the regular mempool, no bundler or separate mempool needed. -2. **Validation (VERIFY frame).** One or more VERIFY frames execute the account's validation logic as static calls. Each VERIFY frame must call the `APPROVE` opcode with a scope: `0x0` (authorize execution), `0x1` (authorize payment), or `0x2` (both). If no frame approves payment, the transaction is invalid. -3. **Execution (SENDER / DEFAULT frames).** After validation, SENDER-mode frames execute with the transaction sender as caller (requires prior execution approval). DEFAULT-mode frames execute with the protocol entry point as caller. +1. [user] Sign and submit a frame transaction containing an ordered list of frames to the regular mempool. +2. [contract] Execute `VERIFY` frames as static calls. Each must call `APPROVE` with a scope (`0x0` execution, `0x1` payment, `0x2` both). If no frame approves payment, the transaction is invalid. +3. [contract] After validation passes, execute `SENDER`-mode frames with the sender as caller, and `DEFAULT`-mode frames with the protocol entry point as caller. +4. [contract] Charge gas to whichever account approved payment, which may differ from the sender. + +## Guarantees & threat model + +Guarantees: + +- Auth agility: accounts migrate between signature schemes without changing address or moving assets. +- No bundler dependency: transactions use the regular mempool, preserving censorship resistance. +- Native gas sponsorship: stealth-address recipients and shielded-pool withdrawals can transact immediately without pre-funded ETH and without a trusted relayer. Fresh addresses are not linkable via gas-funding transactions. +- Privacy improvement: removes the relayer and paymaster centralisation vector that exists with ERC-4337 and out-of-protocol gas sponsorship. -## Guarantees +Threat model: -- **Auth agility**: accounts migrate between signature schemes without changing addresses or moving assets. Allows key rotation, makes Ethereum execution more resilient. -- **No bundler dependency**: transactions use the regular mempool, preserving censorship resistance. -- **Native gas sponsorship**: stealth address recipients and shielded pool withdrawals can transact immediately without ETH pre-funding or trusted relayers. -- **Privacy/CR improvement**: eliminates the relayer/paymaster centralization vector. Fresh addresses are not linkable via gas funding transactions. -- **I2I**: institutions can mandate PQ-only validation for their accounts, as well as customise acces/authorisation level of accounts within an organisation, with granular rules on managing gas spending. -- **I2U**: end users choose their own security model (passkeys, multisig, PQ sigs) without institutional lock-in. +- Bugs in per-account validation code can lock funds or allow unauthorised spends. Auditing burden shifts to account owners or standardised library authors. +- A malicious sponsor approving payment for a transaction they did not submit is still constrained by the `APPROVE` semantics; however, gas griefing through failed validation needs careful fee handling at the protocol level. +- Does not hide transaction content. Network-level metadata (IP, timing) remains a separate concern. ## Trade-offs -- **Draft status**: the EIP is being discussed as a potential headliner for a future fork but is not yet finalized. -- **Migration plan**: still needs a clear migration path for existing EOAs and broader ecosystem adoption (wallets, dApps, tooling). -- **Validation code risk**: bugs in custom validation logic can lock or drain accounts. Auditing burden shifts to account owners (or to standardized validation code libraries). +- Draft status: EIP-8141 is being discussed as a potential headliner for a future fork but is not finalised. Production use is not available. +- Migration path: wallets, dApps, indexers, and tooling must be updated. Existing EOAs need an upgrade path. +- Validation code risk: custom validation logic introduces a new class of account-level vulnerabilities. Standardised, audited libraries mitigate this. +- Mempool propagation: nodes need to validate frame transactions before relaying, which slightly increases propagation cost compared to legacy transactions. ## Example -- Alice receives funds to a stealth address. With native AA, a sponsor (or Alice's main account) pays gas for the stealth address's first transaction, no relayer, no paymaster, no on-chain link between Alice's main account and the stealth address. Alice's stealth account uses passkey validation. Later, she upgrades to ML-DSA validation for PQ safety, same address, same funds. +- A user receives funds at a stealth address. A sponsor (or the user's main account) approves payment for the stealth account's first transaction. No relayer, no paymaster, and no on-chain link between the stealth address and the funding account. The stealth account uses passkey validation initially. Later, the user rotates validation logic to ML-DSA for post-quantum safety: same address, same funds, new signature scheme. ## See also -- [Stealth Addresses](pattern-stealth-addresses.md) — native AA eliminates relayer dependency for stealth address gas -- [Permissionless Spend Auth](pattern-permissionless-spend-auth.md) — application-layer auth agility for shielded pools -- [Lean Ethereum](pattern-lean-ethereum.md) — consensus-layer PQ migration -- [Post-Quantum Threats](../domains/post-quantum.md) — execution-layer migration path +- [EIP-8141 draft](https://eips.ethereum.org/EIPS/eip-8141) +- [Post-Quantum Threats](../domains/post-quantum.md) diff --git a/patterns/pattern-network-anonymity.md b/patterns/pattern-network-anonymity.md index cdb5cf1..fa1bed0 100644 --- a/patterns/pattern-network-anonymity.md +++ b/patterns/pattern-network-anonymity.md @@ -1,103 +1,104 @@ --- title: "Pattern: Network-Level Anonymity" status: draft -maturity: PoC +maturity: concept +type: meta layer: offchain -privacy_goal: Hide sender identity (IP, timing, query patterns) at the transport layer -assumptions: Network observer is a threat; content-layer privacy is handled separately -last_reviewed: 2026-04-14 +last_reviewed: 2026-04-22 + works-best-when: - - Metadata leakage (IP, timing, query patterns) is a threat model concern - - Content privacy alone is insufficient; "who" matters as much as "what" - - Both read privacy (RPC queries) and write privacy (transaction submission) are needed + - Metadata leakage (IP, timing, query patterns) is a threat model concern. + - Content privacy alone is insufficient; who matters as much as what. + - Both read privacy (RPC queries) and write privacy (transaction submission) are needed. avoid-when: - - Threat model does not include network-level observers - - On-chain content privacy is the only requirement -dependencies: - - Transport-layer tooling (Tor, Nym, or TEE-assisted stack) - - External relay or mix-node infrastructure + - Threat model does not include network-level observers. + - On-chain content privacy is the only requirement. + context: both -crops_profile: - cr: medium - os: partial - privacy: partial - security: medium +context_differentiation: + i2i: "Institutions typically run dedicated nodes or relays, so the metadata threat surface is inter-institutional rather than user-to-institution. Network anonymity hides query patterns and settlement-transaction submission from counterparty infrastructure." + i2u: "The institution itself is often the network observer: it operates the RPC endpoint, sequencer, or relay through which users submit transactions and query state. Transport-layer protection is a precondition for meaningful user privacy, even when content-layer privacy (encrypted balances, shielded transfers) is already in place." + +crops_profile: n/a + +sub_patterns: + - name: "Onion routing" + pattern: pattern-onion-routing + crops_summary: "Medium CR, partial privacy, medium latency. Large external anonymity set; vulnerable to global passive adversaries." + - name: "Mixnet anonymity" + pattern: pattern-mixnet-anonymity + crops_summary: "Medium CR, partial privacy, very high latency. Strongest resistance to traffic correlation via cover traffic." + - name: "TEE-assisted network anonymity" + pattern: pattern-tee-network-anonymity + crops_summary: "Medium CR, partial privacy, low latency. Hardware trust assumption relaxes the anonymity trilemma." + +related_patterns: + composes_with: [pattern-private-transaction-broadcasting, pattern-threshold-encrypted-mempool] + see_also: [pattern-user-controlled-viewing-keys, pattern-forced-withdrawal, pattern-modular-privacy-stack] + +open_source_implementations: + - url: https://pse.dev/projects/tor-js + description: "Tor-in-WASM library for browser-side onion routing from dApps" + language: "TypeScript, WASM" + - url: https://gitlab.torproject.org/tpo/core/arti + description: "Rust implementation of the Tor protocol" + language: "Rust" + - url: https://github.com/nymtech/nym + description: "Mixnet with cover traffic" + language: "Rust" --- ## Intent -Hide _who_ is sending transactions or querying state at the network layer. Content-privacy patterns (ZK, FHE, MPC) hide _what_ is in a transaction but not _who_ submitted it -- IP addresses, timing, and query patterns still leak sender identity. Network-level anonymity complements content privacy to close the metadata gap. - -In I2U contexts, the institution itself is often the network observer: it operates the RPC endpoint, sequencer, or relay through which users submit transactions and query state. Transport-layer protection is therefore a precondition for meaningful user privacy, even when content-layer privacy (encrypted balances, shielded transfers) is present. +Hide who is sending transactions or querying state at the network layer. Content-privacy patterns (ZK, FHE, MPC) hide what is in a transaction but not who submitted it: IP addresses, timing, and query patterns still leak sender identity. Network-level anonymity complements content privacy to close the metadata gap. -This is an umbrella pattern. Multiple approaches exist, each with different trade-offs along the **anonymity trilemma**: anonymity set size, latency, and bandwidth overhead. No single approach dominates; the right choice depends on the institution's latency tolerance, threat model, and infrastructure constraints. +This is a meta-pattern. Multiple sub-patterns exist, each with different trade-offs along the anonymity trilemma (anonymity set size, latency, bandwidth overhead). No sub-pattern dominates; the right choice depends on the deployment's latency tolerance, threat model, and infrastructure constraints. -## Ingredients +## Components -- Cryptographic: onion encryption, mix-and-shuffle, secret sharing, cover traffic (varies by approach) -- Hardware: client-side TEE (TEE-assisted approach) -- Infra: relay or mix node network, or anonymity server cluster; private RPC endpoint +- **Transport anonymity layer**: a relay network, mix network, or hardware-assisted cluster that strips or obscures sender metadata before the message reaches the destination. +- **Client routing or submission library**: prepares the message for the chosen anonymity layer (layered encryption, mix encoding, or secret sharing). +- **Destination**: RPC endpoint, sequencer, or transaction mempool. The anonymity layer sits between the client and the destination. -## Protocol (concise) +Each sub-pattern instantiates these components differently. See `sub_patterns` in frontmatter. -1. Client prepares transaction or RPC query for submission. -2. Client routes message through chosen anonymity layer (relay network, mixnet, or TEE cluster). -3. Anonymity layer strips or obscures sender metadata (IP, timing, query pattern). -4. Message reaches destination (RPC node, mempool) without attribution to sender. -5. Response returns through the same or separate anonymous channel. +## Anonymity trilemma -See sub-patterns for approach-specific protocols: [Onion Routing](pattern-onion-routing.md), [Mixnet Anonymity](pattern-mixnet-anonymity.md), [TEE-Assisted](pattern-tee-network-anonymity.md). +Any network anonymity system trades off between three properties: -## Anonymity Trilemma +- Anonymity set size: how many users your traffic blends with. +- Latency: delay introduced by the anonymity mechanism. +- Bandwidth overhead: cover traffic or padding required. -Any network anonymity system must trade off between three properties: +Pure-cryptographic approaches (onion routing, mixnets) must sacrifice at least one. Hardware-assisted approaches (TEE) relax the trilemma by offloading verification to hardware, but introduce a hardware trust assumption. -- **Anonymity set size**: how many users your traffic blends with -- **Latency**: delay introduced by the anonymity mechanism -- **Bandwidth overhead**: cover traffic or padding required +| Approach | Latency | Anonymity strength | Trust assumption | +| --- | --- | --- | --- | +| Onion routing | Moderate (100-500ms) | Strong | No single relay sees full path | +| Mixnet | High (seconds to minutes) | Strongest | Threshold mix nodes and cover traffic | +| TEE-assisted | Low | Medium | Client TEE and server majority | -Pure-cryptographic approaches (onion routing, mixnets) must sacrifice at least one. Hardware-assisted approaches (TEE) relax the trilemma by offloading verification to hardware but introduce a hardware trust assumption. +## Guarantees & threat model -## Approaches +Guarantees: -| Approach | Latency | Anonymity strength | Trust assumption | Maturity | Pattern | -| ------------------------------------------------ | --------------------------- | ------------------ | ----------------------------------- | -------- | ----------------------------- | -| [Onion Routing](pattern-onion-routing.md) | Moderate (~100-300ms typical, up to 500ms) | Strong | No single relay sees full path | PoC | Tor relay network, PSE tor-js | -| [Mixnet Anonymity](pattern-mixnet-anonymity.md) | Very high (seconds-minutes) | Strongest | Threshold mix nodes + cover traffic | PoC | Nym, HOPR | -| [TEE-Assisted](pattern-tee-network-anonymity.md) | Low | Medium | Client TEE + server majority | PoC | Flashbots Flashnet | +- Hides sender IP, timing correlation, and query-to-identity mapping. Strength varies by sub-pattern. +- Complements content-privacy patterns. Together they hide both what and who. -## Guarantees +Threat model: -- Hides sender IP, timing correlation, and query-to-identity mapping (strength varies by approach). -- Complements content-privacy patterns -- together they hide both _what_ and _who_. -- Does not hide message content; pair with ZK, FHE, or MPC patterns for full-stack privacy. -- **I2U**: prevents the institution from correlating user IP addresses with on-chain activity, even when the institution operates the RPC endpoint or sequencer. -- **I2I**: institutions typically run dedicated nodes or relays, reducing the metadata threat surface to inter-institutional network observers. +- Pure-cryptographic approaches are vulnerable to a global passive adversary capable of correlating traffic at both ends of a circuit. Mixnets mitigate this via cover traffic; onion routing does not. +- Hardware-assisted approaches depend on TEE attestation integrity and are exposed to side-channel attacks on the underlying hardware. +- Does not hide message content. Pair with ZK, FHE, or MPC patterns for full-stack privacy. +- No Ethereum execution client natively supports any network anonymity layer as of 2026-04, unlike Bitcoin Core which has had built-in Tor support since 2016. Integration requires external tooling. ## Trade-offs -- No approach simultaneously achieves strong anonymity, low latency, and low bandwidth (anonymity trilemma). -- Stronger anonymity generally means higher latency -- institutional latency requirements constrain the choice. -- All pure-cryptographic approaches are vulnerable to a sufficiently powerful global passive adversary (mixnets mitigate this best via cover traffic, which carries its own tradeoffs). -- Operational complexity varies: onion routing has mature tooling (Tor); mixnet integration remains non-trivial; TEE-assisted is research-stage. -- No Ethereum execution client natively supports any network anonymity layer as of 2026-04. - -## Example - -- Fund manager needs to query 50 token balances to value a portfolio. The RPC provider sees all queried addresses, revealing holdings and strategy. -- Onion routing: queries traverse 3 relays before reaching the RPC endpoint (~300ms added, acceptable for end-of-day valuation). -- Mixnet: queries are batched and reordered (seconds of delay, strongest anonymity guarantee). -- TEE-assisted: queries are secret-shared across servers (low latency, suitable for intraday checks). -- See sub-patterns for detailed examples. +- Stronger anonymity generally means higher latency; institutional latency requirements constrain the choice. +- Operational complexity varies: onion routing has mature tooling; mixnet integration remains non-trivial; TEE-assisted is research-stage. +- Coverage must be end-to-end. Mixing network anonymity for writes with a plain-HTTPS RPC provider for reads reintroduces the metadata gap. ## See also -- [Onion Routing](pattern-onion-routing.md) -- Tor-based multi-hop relay approach -- [Mixnet Anonymity](pattern-mixnet-anonymity.md) -- batching, reordering, and cover traffic approach -- [TEE-Assisted Network Anonymity](pattern-tee-network-anonymity.md) -- low-latency hardware-assisted approach -- [Private Transaction Broadcasting](pattern-private-transaction-broadcasting.md) -- content privacy for writes (complementary) -- [Threshold Encrypted Mempool](pattern-threshold-encrypted-mempool.md) -- content privacy via threshold encryption -- [User-Controlled Viewing Keys](pattern-user-controlled-viewing-keys.md) -- complementary I2U protection at the data access layer -- [Forced Withdrawal](pattern-forced-withdrawal.md) -- complementary I2U protection for asset recovery -- [RFP: Private Reads](../rfps/rfp-private-reads.md) -- read-side privacy gap -- [Modular Privacy Stack](pattern-modular-privacy-stack.md) -- where network anonymity fits in the four-layer architecture +- [Modular Privacy Stack](pattern-modular-privacy-stack.md): where network anonymity fits in the four-layer architecture. +- [RFP: Private Reads](../rfps/rfp-private-reads.md): read-side privacy gap. diff --git a/patterns/pattern-noir-private-contracts.md b/patterns/pattern-noir-private-contracts.md index 97e294f..da6ce97 100644 --- a/patterns/pattern-noir-private-contracts.md +++ b/patterns/pattern-noir-private-contracts.md @@ -1,136 +1,116 @@ --- -title: "Pattern: Aztec Noir Private Contracts" +title: "Pattern: Noir Private Contracts" status: ready -maturity: pilot +maturity: production +type: standard layer: L2 -privacy_goal: Enable composable private and public state in single contracts via ZK proofs -assumptions: Aztec rollup infrastructure, client-side proving capability (8GB RAM), Barretenberg prover -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 + works-best-when: - - Applications need composable private and public state in a single contract - - Developers want privacy without abandoning familiar programming paradigms - - Use cases require selective privacy layers around existing DeFi protocols + - Applications need composable private and public state in a single contract. + - Developers want a privacy-focused DSL without abandoning familiar paradigms. + - Use cases require selective privacy layers around existing DeFi protocols. avoid-when: - - Application requires low-latency execution (client-side proving adds overhead) - - Team lacks capacity to adopt new tooling and non-Solidity development - - Simple shielding or anonymity is sufficient (lighter alternatives exist) -dependencies: [Aztec Protocol, Noir, Barretenberg Prover] + - Application requires low-latency execution; client-side proving adds overhead. + - Team lacks capacity to adopt new tooling and non-Solidity development. + - Simple shielding or anonymity is sufficient; lighter alternatives exist. + context: both +context_differentiation: + i2i: "Institutions can co-deploy contracts that hide positions and trade details from competitors while exposing public logic for counterparty verification. Both parties rely on the sequencer and the validity proof pipeline for liveness; legal recourse is symmetric." + i2u: "End users execute private functions locally and only submit proofs, so the sequencer and observers cannot see inputs, outputs, or log contents. The deployment must still guarantee forced-withdrawal paths and decentralised sequencing so users are not held hostage by an operator." + crops_profile: cr: medium - os: yes - privacy: full - security: medium + o: yes + p: full + s: medium + +crops_context: + cr: "Medium while sequencer election is centralised. Reaches `high` once sequencing becomes permissionless." + o: "Contracts, DSL, and prover backend are open-source. Client-side proving lets anyone run the stack locally." + p: "Private state, private function inputs, and private logs are hidden from sequencers and observers. Public state and function calls remain transparent by design. Selective disclosure is supported through viewing keys or ZK proofs." + s: "Rides on the soundness of the ZK proof system and the validity-proof pipeline that settles to L1. Could reach `high` by replacing admin keys with DAO-governed upgrade paths." + +post_quantum: + risk: high + vector: "PLONK-family backends (Barretenberg) rely on EC pairings and KZG commitments, broken by CRQC. HNDL risk is high for encrypted notes." + mitigation: "Hash-based commitments and STARK-based proving. See [Post-Quantum Threats](../domains/post-quantum.md)." + +standards: [ERC-20] + +related_patterns: + composes_with: [pattern-shielding, pattern-co-snark, pattern-privacy-l2s] + see_also: [pattern-forced-withdrawal, pattern-regulatory-disclosure-keys-proofs] + +open_source_implementations: + - url: https://github.com/AztecProtocol/aztec-packages + description: "Aztec Network with Noir DSL, Barretenberg backend, and private execution runtime" + language: "Noir, Rust, TypeScript" + - url: https://github.com/noir-lang/noir + description: "Noir language compiler and standard library" + language: "Rust" + - url: https://github.com/noir-lang/awesome-noir + description: "Curated catalogue of Noir libraries and example circuits" + language: "Noir" --- ## Intent -Noir is the DSL developed by Aztec, enable developers to write Ethereum-compatible smart contracts that blend transparent public logic with confidential private computations, using a Rust-like language that compiles to zero-knowledge circuits verified on Aztec's privacy-preserving rollup. +Give developers a privacy-focused DSL to write smart contracts that blend public logic with confidential private computation in the same contract. Private functions execute client-side and produce ZK proofs; public functions execute on the sequencer transparently. Private and public state can be composed in a single application. -## Ingredients +## Components -- Aztec Protocol (private rollup) -- ACIR (Abstract Circuit Intermediate Representation) -- Aztec Sandbox or Testnet node (Docker-based), Ethereum L1 for settlement -- Noir DSL for contract logic, TypeScript for client-side integration via `@aztec/aztec.js` -- Proving Backend: Barretenberg (ZK backend, modular and backend-agnostic) -- `aztec` CLI, `nargo` CLI for Noir project management, Node.js/Yarn for dApp development -- Client-side proof generation (CPU-intensive, 8GB RAM minimum recommended) +- **Private contract DSL**: Rust-inspired language for authoring functions, compiling to a circuit intermediate representation. +- **Circuit intermediate representation**: backend-agnostic IR that the prover backend compiles into proving and verification keys. +- **Client-side prover**: generates proofs for private-function executions on the user's machine (typically 8 GB RAM recommended). +- **Privacy rollup**: private execution runtime, public execution VM, note-discovery infrastructure, and validity-proof pipeline to Ethereum L1. +- **Encrypted logs**: note discovery mechanism; only the holders of decryption keys can read log contents. ## Protocol -1. Write Contract: Developer writes smart contract in Noir (`.nr` files) with both private and public functions -2. Compile to ACIR: Noir compiler translates contract logic into Abstract Circuit Intermediate Representation -3. Deploy to Aztec: Contract deployed to Aztec rollup (testnet or mainnet) -4. Client Execution: User executes private function locally, generating zero-knowledge proof of correct execution -5. Submit Proof: Client submits proof and public inputs to Aztec sequencer -6. Verification: Aztec rollup verifies proof on-chain using Barretenberg verifier -7. State Update: Private state updated in encrypted form, public state updated transparently -8. L1 Settlement: Batch of transactions periodically settled to Ethereum L1 with validity proof - -## Guarantees - -**Privacy:** +1. [user] Write a contract in the DSL with private and public functions. Compile to the circuit intermediate representation. +2. [user] Deploy the contract to the privacy rollup. +3. [user] Execute a private function locally, generating a ZK proof of correct execution over private inputs and state. +4. [user] Submit the proof and any public inputs to the sequencer. +5. [sequencer] Verify the proof, update the encrypted private state, and apply any public state changes. +6. [sequencer] Batch transactions periodically and settle to Ethereum L1 with a validity proof. +7. [user] Scan encrypted logs to discover incoming notes and decrypt them with local keys. -- Private state remains encrypted and hidden from sequencers and observers -- Private function logic and inputs/outputs are not revealed on-chain -- Public and private logic can be composed in the same contract +## Guarantees & threat model -**Correctness:** +Guarantees: -- Zero-knowledge proofs guarantee computational integrity without revealing private data -- Validity proofs ensure state transitions follow contract rules +- Private state stays encrypted and hidden from sequencers and observers. Private function inputs and outputs are not revealed on-chain. +- Public state, public function calls, and contract source remain transparent and auditable. +- Validity proofs ensure state transitions follow contract rules; L1 finality comes via periodic batch settlement. +- Selective disclosure to auditors is possible through viewing keys or targeted ZK proofs. +- Encrypted event logs enable note discovery without leaking content to the public. -**Atomicity:** +Threat model: -- Transactions are atomic within the Aztec rollup execution environment -- L1 finality achieved through periodic batch settlement with validity proofs - -**Audit & Observability:** - -- Public state and function calls remain transparent and auditable -- Private state can support selective disclosure through viewing keys or ZK proofs -- Contract logic is open-source and auditable in Noir -- Private logs enable encrypted event emission for note discovery and auditing - -**Private Logs** - -- Encrypted logs enable private event emission and while maintaining confidentiality -- Recipients scan encrypted onchain logs to identify private transactions meant for them. This is known as **note discovery**. -- Only parties with decryption keys can read log contents; observers see encrypted data only +- Soundness of the ZK proof system and the circuit compiler. +- Non-censoring sequencer set. A censoring sequencer can stall user transactions; forced-withdrawal paths to L1 are required to bound this. +- Client-side key management: compromise of local proving or viewing keys exposes the user's private state. +- Note discovery relies on scanning; a malicious or buggy indexer can cause notes to be missed, though funds are not lost. ## Trade-offs -**Performance:** - -- Client-side proving is CPU-intensive, adding latency compared to Solidity execution -- Proof generation time depends on circuit complexity and hardware capabilities -- Barretenberg optimizations and parallel proving are reducing this overhead - -**Developer Experience:** - -- Requires learning Noir DSL (though syntax is Rust-inspired and developer-friendly) -- Cannot directly reuse Solidity contracts or tooling -- Standard Ethereum functions must be reimplemented in Noir or imported from community libraries - -**Ecosystem Maturity:** - -- Noir ecosystem is rapidly growing but less mature than Solidity -- Some primitives and libraries still need to be built or ported -- Limited production deployments compared to established L2s - -**Mitigations:** - -- Use Aztec as privacy bridge to existing DeFi without full rewrites -- Leverage growing [Awesome Noir](https://github.com/noir-lang/awesome-noir) ecosystem for shared libraries -- Start with selective privacy layers, expand as tooling matures -- Optimize circuit design to minimize proving time -- **CROPS context (both)**: CR could reach `high` if sequencer election shifts to a permissionless model. Security could reach `high` by replacing admin keys with DAO-governed upgrade paths. In I2I, censorship resistance matters for ensuring no counterparty can block settlement transactions. In I2U, decentralized sequencing protects end users from unilateral transaction exclusion. -- **Post-quantum exposure**: Barretenberg (PLONK variant with EC commitments) is broken by CRQC; HNDL risk is high for encrypted notes. Mitigation: hash-based commitments and STARK-based proving. See [Post-Quantum Threats](../domains/post-quantum.md). +- Performance: client-side proving is CPU-intensive and adds latency compared to transparent L2 execution. Proof generation time depends on circuit complexity and hardware. +- Developer experience: requires learning a new DSL. Solidity contracts cannot be reused directly, and standard library coverage is still maturing. +- Ecosystem maturity: DSL and tooling are improving quickly, but primitive and library coverage is thinner than for Solidity. +- Failure modes: a bug in a private-state update path can burn notes irrecoverably because replay from encrypted logs requires the original sender's cooperation. ## Example -**Private Corporate Stablecoin Transfer:** - -1. Bank A shields $10M USDC on Aztec, receiving private notes -2. Bank A pays Bank B $2M privately - client generates ZK proof of sufficient balance -3. Transaction emits encrypted log; only Bank B can decrypt and discover the payment -4. Aztec network verifies proof and updates balances - observers only see verification occurred, not amounts or parties -5. Bank B can now spend their $2M privately; Bank A's remaining $8M position stays hidden +- A corporate treasury shields stablecoins into a private contract, receiving private notes. +- It pays a supplier privately; the client generates a ZK proof of sufficient balance and note ownership. +- The transaction emits an encrypted log; only the supplier can decrypt and discover the payment. +- The rollup verifies the proof, updates balances in encrypted form, and includes the transaction in a batch settled to L1. Observers see that a valid transaction occurred but not amounts or parties. +- The supplier can then spend the received notes privately; the treasury's remaining position stays hidden. ## See also -- [Pattern: Privacy L2s](pattern-privacy-l2s.md) - General privacy rollup architectures -- [Pattern: Shielding](pattern-shielding.md) - Shielded ERC-20 transfers and balance privacy -- [Pattern: Co-SNARK](pattern-co-snark.md) - Multi-party ZK proofs for compliance -- [Vendor: Aztec Network](../vendors/aztec.md) - Aztec protocol details -- [Approach: Private Bonds](../approaches/approach-private-bonds.md) - Tokenized securities with privacy -- [Approach: Private Derivatives](../approaches/approach-private-derivatives.md) - Private derivatives trading - -**Links:** - -- [Aztec Documentation](https://docs.aztec.network) -- [Noir Language](https://noir-lang.org) -- [Aztec.js SDK](https://www.npmjs.com/package/@aztec/aztec.js) -- [Awesome Noir](https://github.com/noir-lang/awesome-noir) -- [Nethermind's Noir Deep Dive](https://www.nethermind.io/blog/our-first-deep-dive-into-noir-what-zk-auditors-learned) +- [Aztec](../vendors/aztec.md) +- [Approach: Private Bonds](../approaches/approach-private-bonds.md) +- [Approach: Private Derivatives](../approaches/approach-private-derivatives.md) diff --git a/patterns/pattern-oif.md b/patterns/pattern-oif.md index aa98949..272c3ef 100644 --- a/patterns/pattern-oif.md +++ b/patterns/pattern-oif.md @@ -1,72 +1,103 @@ --- title: "Pattern: Open Intent Framework (OIF)" status: draft -maturity: pilot +maturity: production +type: standard layer: hybrid -privacy_goal: No transaction privacy; intents visible to solvers during discovery -assumptions: Active solver network, cross-chain messaging layer, price oracles -last_reviewed: 2026-01-14 -rollout-plan: ready to build solvers +last_reviewed: 2026-04-22 + works-best-when: - - Cross-chain settlement needed - - Intent-based execution preferred - - Permissionless solver participation desired + - Cross-chain settlement is needed. + - Intent-based execution is preferred over step-by-step transactions. + - Permissionless solver participation is desired. avoid-when: - - Single-chain operations sufficient - - Transaction privacy required (intents visible to solvers) + - Single-chain operations are sufficient. + - Transaction privacy is required; intents are visible to solvers by default. + context: both +context_differentiation: + i2i: "Intents broadcast assets, chains, amounts, and deadlines to the solver network, exposing institutional trading strategy to competing solvers. Institutions may need permissioned solver sets or encrypted intents to protect order flow." + i2u: "Unencrypted user intents are a clear front-running vector against retail order flow. A user-facing deployment must combine OIF with encrypted or committed intents and a sealed-bid auction before the intent becomes visible." + crops_profile: cr: high - os: yes - privacy: none - security: medium + o: yes + p: none + s: medium + +crops_context: + cr: "High because any solver meeting the protocol can participate; no centralised solver set is required." + o: "Reference contracts, solver implementation, and the underlying intent standard are open-source and composable with alternative settlement, oracle, and messaging layers." + p: "None by default. Intents are visible during solver discovery. Could reach `full` by adopting encrypted intent encoding with sealed-bid commitments via threshold encryption, revealed only after solver execution and L1 finality." + s: "Medium while cross-chain atomicity depends on external settlement and oracle assumptions. Reaches `high` once settlement atomicity and oracle integrity are hardened." + +standards: [ERC-7683] + +related_patterns: + composes_with: [pattern-threshold-encrypted-mempool, pattern-pretrade-privacy-encryption] + see_also: [pattern-cross-chain-privacy-bridge, pattern-private-transaction-broadcasting] + +open_source_implementations: + - url: https://github.com/openintentsframework/oif-contracts + description: "Contracts for input collection, output delivery, oracle, messaging, and settlement" + language: "Solidity" + - url: https://github.com/openintentsframework/oif-solver + description: "Solver implementation for intent discovery and cross-chain execution" + language: "TypeScript, Rust" --- ## Intent -OIF enables cross-chain intent-based settlement where users express desired outcomes and solvers compete to execute them across chains permissionlessly. +Enable cross-chain intent-based settlement where users express desired outcomes and permissionless solvers compete to execute them across chains. The framework separates user intent (what) from execution strategy (how) and plugs into external settlement, oracle, and messaging layers. + +## Components + +- **Intent contracts**: input-collection and output-delivery entry points that escrow user assets, record intent parameters, and release funds on proof of fulfilment. +- **Solver**: off-chain service that indexes intents, computes execution routes (swaps, bridges, liquidity routing), and submits fulfilment transactions. +- **Cross-chain messaging layer**: transports proofs of fulfilment between origin and destination chains. +- **Oracle or proof mechanism**: verifies that outputs have been delivered before the origin contract releases inputs. +- **Settlement module**: finalises the intent and handles refund or cancellation on failure. -## Ingredients +## Protocol -- [OIF contracts](https://github.com/openintentsframework/oif-contracts) for input collection, output delivery, oracle/messaging/settlement -- [OIF solver](https://github.com/openintentsframework/oif-solver) for intent discovery, execution path optimization, cross-chain settlement -- Infrastructure: Cross-chain messaging layer, price oracles +1. [user] Sign and submit an intent (for example, sell X on chain A, receive Y on chain B) to the origin contract. +2. [contract] Record the intent and escrow the input asset. +3. [operator] Solvers monitor the contracts, index new intents, and compute candidate execution routes across chains and liquidity sources. +4. [operator] The selected solver executes the required cross-chain operations: swaps, bridging, and destination-chain transfers. +5. [contract] The oracle or proof mechanism verifies that the output has been delivered per the intent. +6. [contract] The settlement module marks the intent complete and releases locked inputs to the solver; on failure or missed deadline, it refunds or cancels per the configured policy. -## Protocol (concise) +## Guarantees & threat model -1. User signs/submits an intent to the smart contract (e.g., “sell X on chain A, deliver Y on chain B”). -2. Solver network monitors the contract(s), indexes new intents and identifies candidate fulfilment opportunities. -3. Solvers compute optimal execution route(s) across chains/bridges/liquidity pools given the intent. -4. The selected solver executes the required cross-chain operations (swaps, messaging, transfers) and uses the settlement layer to ensure final delivery. -5. An oracle or proof mechanism confirms that the output asset has been delivered per intent; the contract (or settlement module) marks the intent complete and releases locked input assets (or refunds if non-fulfilled). -6. If the solver fails or deadline is missed, the system supports cancellation or refund flows (depending on governance/implementation). +Guarantees: -## Guarantees +- Permissionless execution: any solver meeting the protocol can participate. +- Modularity: settlement, oracle, and messaging layers can be swapped while keeping the intent-based front-end. +- Intent-level abstraction: users focus on outcomes; solvers deal with routing and bridging complexity. -- **Permissionless execution**: any solver that meets the protocol can participate; the framework does not enforce a centralized solver set. -- **Modularity and composability**: developers can swap in different settlement, oracle or messaging layers while still using the intent-based front-end. -- **Higher-level intent abstraction**: users focus on what they want, not how to achieve it; solvers deal with routing/bridging complexity. -- **Transparency (and trade-off)**: intent details (assets, chains, amounts) are visible to solvers during discovery, exposing some MEV/visibility risk. +Threat model: -- _Note_: Cross-chain atomicity is a goal but depends on the settlement layer’s guarantees. Developers should design flows (escrows, resource locking) appropriately to approximate atomic delivery. +- Intent visibility exposes order flow to MEV and strategy leakage during solver discovery. +- Cross-chain atomicity is approximated via escrow and settlement logic; it is not guaranteed at the protocol level and depends on the chosen messaging and settlement modules. +- Oracle and messaging failures can stall withdrawals or cause disputed fulfilment. Escrow and resource-locking design must bound the blast radius. +- Solver liveness: if no solver picks up an intent, the user falls back to cancellation or refund flows. ## Trade-offs -- Solver network must be active and sufficiently liquid for intents to be fulfilled in a timely way. -- Cross-chain operations inherently carry higher latency and complexity vs. single-chain flows. -- Multi-step cross-chain settlement increases attack surface (messaging proofs, oracle delays). -- Intent visibility -- **CROPS context (both)**: Privacy could reach `full` by adopting encrypted intent encoding with sealed-bid commitments via threshold encryption, revealable only after solver execution and L1 finality. Security could reach `high` by strengthening cross-chain settlement atomicity guarantees and hardening oracle assumptions. In I2I, intent visibility exposes institutional trading strategies to competing solvers. In I2U, unencrypted intents allow front-running of retail order flow. +- Solver network must be active and sufficiently liquid for timely fulfilment. +- Cross-chain flows inherently carry higher latency and more failure modes than single-chain transactions. +- Multi-step settlement increases the attack surface (messaging proofs, oracle delays, bridge compromise). +- Intent visibility is a systemic drawback: strategy leakage and front-running are the price of permissionless solver competition. -## Example: Cross-Chain Stablecoin Settlement +## Example -1. Bank A submits intent: “Transfer 5 M USDC on Ethereum, receive 5 M USDT on Arbitrum”. -2. Solver network discovers the intent and computes execution path (e.g., USDC bridge to Arbitrum → swap to USDT). -3. Winning solver executes the required steps: USDC moved, USDT delivered. -4. Settlement layer verifies delivery and marks the intent complete; Bank A receives 5 M USDT on Arbitrum. -5. If execution fails or misses deadline, the fallback mechanism refunds or cancels the intent. +- A corporate treasury submits the intent "transfer 5 M USDC on Ethereum, receive 5 M USDT on Arbitrum". +- The solver network indexes the intent and computes an execution path (bridge USDC to Arbitrum, swap to USDT). +- The winning solver executes the steps: USDC is moved, USDT is delivered to the treasury's destination address. +- The settlement layer verifies delivery, the origin contract releases escrowed funds to the solver, and the intent is marked complete. +- On failure or missed deadline, the fallback mechanism refunds the treasury. ## See also -- ERC‑7683 — the intent standard supported by OIF and enabling cross-protocol intent interoperability. -- Privacy-preserving intent approaches (for situations where you need intent confidentiality and cannot expose details to solvers). +- [ERC-7683: Cross-Chain Intents Standard](https://eips.ethereum.org/EIPS/eip-7683) +- [Open Intents Framework documentation](https://github.com/openintentsframework) diff --git a/patterns/pattern-onion-routing.md b/patterns/pattern-onion-routing.md index 47d7274..cf32114 100644 --- a/patterns/pattern-onion-routing.md +++ b/patterns/pattern-onion-routing.md @@ -1,84 +1,112 @@ --- title: "Pattern: Onion Routing" status: draft -maturity: PoC +maturity: testnet +type: standard layer: offchain -privacy_goal: Hide sender IP by routing traffic through multiple relay nodes, each peeling one encryption layer -assumptions: No single relay sees both sender and destination; vulnerable to global passive adversary -last_reviewed: 2026-04-14 +last_reviewed: 2026-04-22 + works-best-when: - - Metadata leakage (IP, timing) is a threat model concern - - Higher latency is acceptable (batch queries, end-of-day valuations) - - A large external anonymity set is desirable (Tor's global relay network) + - Metadata leakage (IP, timing) is a threat model concern. + - Higher latency is acceptable (batch queries, end-of-day valuations, non-real-time flows). + - A large external anonymity set is desirable. avoid-when: - - Sub-second latency is required (DeFi trading, real-time pricing) - - The threat model includes a global passive adversary with traffic correlation capability - - Users cannot run additional software or route through external networks -dependencies: - - Tor relay network (or equivalent onion-routing overlay) - - Client-side routing library (PSE tor-js, Arti) + - Sub-second latency is required (DeFi trading, real-time pricing). + - The threat model includes a global passive adversary capable of traffic correlation. + - Users cannot run additional software or route through external networks. + context: both +context_differentiation: + i2i: "Institutions querying counterparty state or submitting settlement transactions can hide their IP from counterparty infrastructure. Both sides typically run their own relays or nodes, and the external anonymity set is not under either party's control." + i2u: "When the institution operates the RPC endpoint or sequencer, onion routing prevents it from correlating user IPs with on-chain activity. The anonymity set is external, so the institution cannot shrink it. Does not address censorship at the RPC or sequencer layer; see forced-withdrawal." + crops_profile: cr: medium - os: yes - privacy: partial - security: medium + o: yes + p: partial + s: medium + +crops_context: + cr: "Medium overall. Reaches `high` when paired with direct P2P or decentralised RPC access because no single entity gates requests. Drops to `low` when routed through a centralised RPC provider that can block exit-node IPs." + o: "Both the Tor protocol and Rust reimplementations are open-source. Clients and relays are forkable." + p: "Hides sender IP and which RPC endpoint was queried. On-chain side channels (transaction timing, gas patterns, address reuse) persist even when IP is hidden." + s: "Vulnerable to a global passive adversary performing end-to-end traffic correlation. Strong against single relay observers and local network adversaries." + +post_quantum: + risk: medium + vector: "Circuit establishment uses ECDH-based key exchange that a CRQC can break. HNDL risk exists for recorded circuit handshakes, allowing retrospective deanonymisation." + mitigation: "Tor is adopting hybrid post-quantum key exchange; deployments should track and enable it as it becomes available." + +standards: [] + +related_patterns: + alternative_to: [pattern-mixnet-anonymity, pattern-tee-network-anonymity] + composes_with: [pattern-private-transaction-broadcasting, pattern-threshold-encrypted-mempool] + see_also: [pattern-network-anonymity, pattern-modular-privacy-stack] + +open_source_implementations: + - url: https://gitlab.torproject.org/tpo/core/arti + description: "Rust reimplementation of the Tor protocol" + language: "Rust" + - url: https://pse.dev/projects/tor-js + description: "Tor-in-WASM library for browser-side onion routing from dApps (EF PSE)" + language: "TypeScript, WASM" + - url: https://docs.flashbots.net/flashbots-protect/quick-start + description: "Public .onion endpoint for private transaction submission" + language: "Service" --- ## Intent -Hide *who* is sending transactions or querying state by routing traffic through a chain of relay nodes. Each relay peels one layer of encryption, so no single relay sees both the sender's IP and the destination. Onion routing closes the metadata gap left by content-privacy patterns (ZK, FHE, MPC), which hide *what* is in a transaction but not *who* submitted it. +Hide who is sending transactions or querying state by routing traffic through a chain of relay nodes. Each relay peels one layer of encryption, so no single relay sees both the sender's IP and the destination. Onion routing closes the metadata gap left by content-privacy patterns, which hide what is in a transaction but not who submitted it. + +## Components -## Ingredients +- **Circuit of relays**: three or more nodes selected from a relay directory, each holding one encryption layer. +- **Layered (onion) encryption**: the client wraps the message once per relay, outermost layer decryptable only by the first hop. +- **Client routing library**: negotiates the circuit, applies the encryption layers, and exposes a local proxy (SOCKS5 or WASM) to the dApp or wallet. +- **Exit relay**: decrypts the last layer and forwards the message to the destination (RPC node, mempool, .onion service). -- Cryptographic: layered (onion) encryption, circuit establishment -- Infra: relay network (Tor), SOCKS5 proxy or WASM-embedded client -- Standards: Tor protocol specification, Arti (Rust implementation) +## Protocol -## Protocol (concise) +1. [user] Select a circuit of three or more relay nodes from the relay directory. +2. [user] Wrap the message (RPC query or signed transaction) in one encryption layer per relay. +3. [relayer] Each relay decrypts its layer, learns the next hop, and forwards the message. No relay sees both the sender and the destination. +4. [relayer] The exit relay decrypts the final layer and delivers the message to the destination. +5. [user] The response returns through the same circuit in reverse. -1. Client selects a circuit of 3+ relay nodes from the Tor directory. -2. Client wraps the message (RPC query or transaction) in multiple encryption layers, one per relay. -3. Each relay decrypts its layer, learns the next hop, and forwards the message. -4. Exit relay delivers the message to the destination (RPC node, mempool). -5. Response returns through the same circuit in reverse. +## Guarantees & threat model -## Guarantees +Guarantees: -- Hides sender IP from the destination (RPC provider, block builder). +- Hides the sender's IP from the destination (RPC provider, block builder, mempool peer). - No single relay sees both sender identity and message content. -- Draws from a large, external anonymity set (global Tor network) that neither the institution nor RPC provider controls. -- Does not hide message content; pair with content-privacy patterns for full-stack privacy. -- **I2U**: prevents the institution (when it operates the RPC endpoint) from correlating user IPs with on-chain activity. The anonymity set is external to the institution, so the institution cannot shrink it. -- **I2I**: institutions querying counterparty state or submitting settlement transactions can hide their IP from the counterparty's infrastructure. +- Draws from a large external anonymity set that neither the institution nor the RPC provider controls. + +Threat model: + +- A global passive adversary able to observe both ends of a circuit can correlate traffic and deanonymise sessions. +- Exit relays see the final unencrypted payload unless transport-layer encryption (HTTPS, .onion service) is used. +- RPC providers that block exit-node IPs degrade the guarantee; pair with decentralised or P2P RPC access. +- Does not hide message content. Pair with content-privacy patterns for full-stack privacy. +- No Ethereum execution client natively supports onion routing as of 2026-04, unlike Bitcoin Core. Integration requires external tooling. ## Trade-offs -- High latency (3+ hops, ~200-500ms added per request) makes it unsuitable for latency-sensitive DeFi. -- Exit relays can observe unencrypted traffic; HTTPS to the RPC endpoint mitigates this. -- Vulnerable to traffic correlation attacks by a well-resourced adversary who can observe both ends of the circuit. -- No native Tor support in any Ethereum execution client (Geth, Erigon, Reth) as of 2026-04, unlike Bitcoin Core which has had built-in Tor since 2016. Integration requires external tooling. -- CROPS: CR is `medium` overall: when paired with direct P2P or decentralized RPC access, censorship resistance is strong (no single entity gates requests). When routed through a centralized RPC provider, CR drops because the provider can block Tor exit node IPs. OS is `yes` (Tor and Arti are open-source). Privacy is `partial` because on-chain side channels (transaction timing, gas patterns) persist even when IP is hidden. Security is `medium` due to vulnerability to global passive adversaries performing traffic correlation. +- High latency: three or more hops add ~100-500 ms per request, making it unsuitable for latency-sensitive DeFi. +- Exit-relay visibility: plaintext traffic is observable at the exit. HTTPS to the RPC endpoint or .onion services mitigate this. +- Operational complexity: running a reliable circuit requires relay discovery, retry logic, and health checks. +- On-chain side channels (timing, gas patterns, address reuse) persist and must be addressed separately. ## Example -1. Fund manager needs to query 50 token balances to value a portfolio at end of day. -2. Without network anonymity, the RPC provider sees all queried addresses, revealing holdings and strategy. -3. Fund manager routes queries through Tor: each query traverses 3 relays before reaching the RPC endpoint. -4. RPC provider sees requests arriving from a Tor exit relay, not the fund manager's IP. -5. Added latency (~300ms per query) is acceptable for end-of-day valuation. +- A fund manager needs to query 50 token balances to value a portfolio at end of day. +- Without network anonymity, the RPC provider sees all queried addresses, revealing holdings and strategy. +- With onion routing, each query traverses three relays before reaching the RPC endpoint. +- The RPC provider sees requests arriving from an exit relay, not the fund manager's IP. +- The added latency (~300 ms per query) is acceptable for end-of-day valuation. ## See also -- [Network-Level Anonymity](pattern-network-anonymity.md) - umbrella pattern and approach comparison -- [Mixnet Anonymity](pattern-mixnet-anonymity.md) - stronger anonymity guarantees but higher latency -- [TEE-Assisted Network Anonymity](pattern-tee-network-anonymity.md) - low-latency alternative using hardware trust -- [Private Transaction Broadcasting](pattern-private-transaction-broadcasting.md) - complementary content-privacy pattern for mempool-level protection -- [Threshold Encrypted Mempool](pattern-threshold-encrypted-mempool.md) - complementary content-privacy pattern for pre-inclusion encryption -- [Modular Privacy Stack](pattern-modular-privacy-stack.md) - where network anonymity fits in the four-layer architecture - -## See also (external) - -- PSE tor-js: https://pse.dev/projects/tor-js (Tor-in-WASM for Ethereum dApps, EF team) -- Flashbots Protect .onion endpoint: https://docs.flashbots.net/flashbots-protect/quick-start -- Arti (Tor Project Rust implementation): https://gitlab.torproject.org/tpo/core/arti +- [Network-Level Anonymity](pattern-network-anonymity.md): meta-pattern and sub-pattern comparison. +- [Tor Project Arti](https://gitlab.torproject.org/tpo/core/arti) diff --git a/patterns/pattern-origin-locked-confidential-ledger.md b/patterns/pattern-origin-locked-confidential-ledger.md index f4b780c..d1dda33 100644 --- a/patterns/pattern-origin-locked-confidential-ledger.md +++ b/patterns/pattern-origin-locked-confidential-ledger.md @@ -1,80 +1,114 @@ --- -title: "Origin-Locked Cross-Chain Confidential Layer" +title: "Pattern: Origin-Locked Cross-Chain Confidential Ledger" status: draft -maturity: PoC -layer: hybrid privacy -privacy_goal: Amount/balance confidentiality for origin-chain assets (no fund bridge), with selective disclosure -assumptions: Origin-chain locking contract + confidentiality execution layer (encrypted ledger + ZK verification) + verifiable cross-chain messaging (light client/ IBC-style) + wallet/KMS integration -last_reviewed: 2026-03-06 +maturity: testnet +type: standard +layer: hybrid +last_reviewed: 2026-04-22 + works-best-when: - - Need amount and balance confidentiality for existing ERC-20 assets without changing token contracts or migrating liquidity. + - Amount and balance confidentiality is needed for existing ERC-20 assets, without changing token contracts or migrating liquidity. - Counterparties are known by default (not anonymous) and selective disclosure is required. - - Want to avoid single-TEE trust models, MPC honest-majority assumptions, or off-chain coprocessor dependency. + - The design must avoid single-TEE trust models, MPC honest-majority assumptions, or off-chain coprocessor dependency. avoid-when: - - Need default anonymity/identity encryption or large anonymity sets. - - Need single-domain designs where all logic and settlement must occur on Ethereum L1/L2. -dependencies: ERC-20, Verifiable cross-chain messaging, Selective disclosure (view keys / proofs) + - Default anonymity or large anonymity sets are required. + - A single-domain design is preferred, with all logic and settlement on Ethereum L1 or a single L2. + context: both +context_differentiation: + i2i: "Between known counterparties, amount privacy is the primary goal. Both sides participate in selective disclosure for audit and KYC. Custody remains on the origin chain, which preserves existing regulatory treatment of the underlying ERC-20." + i2u: "When institutions hold encrypted balances on behalf of users, the user must retain their own ElGamal private key and have a guaranteed withdrawal path on the origin chain. Without user-held keys and forced withdrawal, the confidentiality layer becomes an operator-controlled ledger over user funds." + crops_profile: cr: medium - os: partial - privacy: partial - security: high + o: partial + p: partial + s: high + +crops_context: + cr: "Medium. Origin-chain withdrawal is enforceable through the locking contract, which bounds operator power. Availability still depends on the confidentiality layer and messaging relayers." + o: "Partial. Contract designs are open, but specific confidentiality-layer implementations vary in openness and reproducibility of the encrypted state." + p: "Partial. Amounts and balances are encrypted, but sender and receiver addresses can remain visible unless combined with an identity-obfuscation pattern." + s: "High for custody: funds stay on the origin chain under a minimal locking contract, so cross-chain messaging issues affect availability rather than custody." + +post_quantum: + risk: high + vector: "ElGamal homomorphic encryption over elliptic curves is broken by CRQC. HNDL risk is high for on-chain encrypted balances and transfer ciphertexts." + mitigation: "Lattice-based additively homomorphic PKE or hybrid schemes. See [Post-Quantum Threats](../domains/post-quantum.md)." + +standards: [ERC-20] + +related_patterns: + composes_with: [pattern-regulatory-disclosure-keys-proofs, pattern-user-controlled-viewing-keys, pattern-forced-withdrawal] + alternative_to: [pattern-cross-chain-privacy-bridge, pattern-privacy-l2s] + see_also: [pattern-shielding] + +open_source_implementations: + - url: https://docs.fairblock.network/docs/confidential_transfers/technical_overview + description: "Technical overview of a confidential-transfer design with IBC-style messaging" + language: "Documentation" + - url: https://ibcprotocol.org/ + description: "Light-client-based cross-chain messaging specification" + language: "Specification" --- ## Intent -Provide **confidential balances and transfers for an existing ERC-20 on an origin EVM chain**, while keeping the asset **locked and settled on the origin chain**, and executing confidentiality logic on a separate confidentiality execution layer that maintains an encrypted ledger and verifies ZK-proven state transitions. - -This differs from a privacy bridge and from privacy L2s. Here, the “confidential layer” is **cross-chain**, but **funds never bridge**. +Provide confidential balances and transfers for an existing ERC-20 on an origin EVM chain, while keeping the asset locked and settled on the origin chain. Confidentiality logic runs on a separate execution layer that maintains an encrypted ledger and verifies ZK-proven state transitions. Unlike a privacy bridge or a privacy rollup, funds never leave the origin chain. -## Ingredients +## Components -- **Origin chain (EVM):** - - Minimal locking contract for deposits/withdrawals - - User-facing entrypoint for “deposit/private transfer/withdraw” -- **Confidential execution layer:** - - **Public encrypted ledger:** Per-account balances are stored as ElGamal ciphertext under the account holder’s key. - - ZK verification for valid state transitions (no overspend, conservation, etc.) - - Balances update via ElGamal homomorphic addition/subtraction plaintext balances are never revealed and the ledger is not maintained by any external party. -- **Cross-chain messaging (verifiable):** - - IBC-style / light-client verification to transport packets - - Relayers move packets but are not trusted for correctness -- **Disclosure layer (optional but typical):** - - Scoped viewing keys / selective disclosure - - Optional attestations/audit log of disclosure events +- **Origin locking contract**: minimal contract on the origin EVM chain that escrows deposits and releases withdrawals. It is the only place user funds live. +- **Encrypted ledger**: per-account balances stored as ElGamal ciphertext under the account holder's key on a separate confidentiality execution layer. +- **ZK verifier**: validates state transitions on the encrypted ledger (no overspend, conservation of value, correct key usage) without decrypting balances. +- **Homomorphic update logic**: encrypted balances update via ElGamal additive homomorphism; plaintext balances are never reconstructed by any component. +- **Verifiable cross-chain messaging**: light-client or IBC-style messaging between the origin chain and the confidentiality layer. Relayers move packets but are not trusted for correctness. +- **Disclosure layer** (optional): scoped viewing keys or per-transaction audit keys generated via MPC, so a designated auditor can decrypt specific transactions under review. ## Protocol -1. **Deposit (lock → credit):** User deposits ERC-20 into the origin locking contract; contract emits a message to the confidentiality layer; confidentiality layer verifies and **credits an encrypted balance**. -2. **Confidential transfer (prove → update):** User submits `(ciphertext amount, ZK proof, recipient)` to the origin contract; message relayed to confidentiality layer; confidentiality layer verifies proof and **updates encrypted balances** (homomorphic +/-), then returns an ack. -3. **Withdraw (debit → unlock):** User submits a withdrawal request plus ZK proof; confidentiality layer debits encrypted balance and acks; origin contract **unlocks** the corresponding ERC-20 back to the user. -4. **Selective disclosure (optional):** Under a deployment defined policy, authorized parties receive scoped decryption rights or proofs for specific accounts/transactions; log access events if required. +1. [user] Deposit ERC-20 into the origin locking contract. +2. [contract] Emit a cross-chain message crediting the user's encrypted balance on the confidentiality layer. +3. [user] Submit a confidential transfer: ciphertext amount, ZK proof of correctness, and recipient identifier. +4. [relayer] Carry the transfer packet to the confidentiality layer. +5. [operator] The confidentiality layer verifies the proof and homomorphically updates encrypted balances of sender and receiver. +6. [user] Submit a withdrawal request with a ZK proof of sufficient encrypted balance. +7. [contract] On receipt of the debit acknowledgement, unlock the corresponding ERC-20 to the user on the origin chain. +8. [auditor] Under a deployment-defined policy, receive a scoped decryption key or proof for a specific account or transaction; access events are logged if required. + +## Guarantees & threat model + +Guarantees: + +- Amounts and balances are encrypted from the public. ElGamal private keys stay with the account holder; no protocol component stores them. +- Underlying ERC-20 issuance and liquidity remain on the origin chain. No wrapped token, no fund bridge, no mirror supply. +- Custody is governed by the origin locking contract. Cross-chain messaging failures affect availability and withdrawal latency, not custody. +- Selective disclosure is controlled: audit keys are generated per transaction through an MPC network, and a verified auditor can decrypt only the specific transaction under review. -## Guarantees +Threat model: -- **Encrypts:** Amounts and balances from the public. -- **Preserves asset reality:** Underlying ERC-20 issuance and liquidity stay on the origin chain (no wrapped token required; no fund bridge). -- **Limits failure blast radius:** Cross-chain messaging issues primarily impact **availability/UX** (e.g. delayed withdrawals), while custody remains governed by the origin locking contract. -- **Supports auditability:** Selective disclosure can reveal what is required, when required. -- **User-controlled encryption keys:** Each account’s ElGamal private key is held by the account holder; the protocol, relayers, or any other network component do not manage or store these keys. -- **Controlled audit access:** Audit keys are generated per transaction through a multi-party computation (MPC) network. A verified auditor can use the generated key to decrypt the specific transaction under review. +- Sender and receiver addresses can remain transparent unless combined with identity-obfuscation patterns. This pattern alone does not deliver counterparty privacy. +- Relayers and the messaging layer can delay or drop packets, stalling transfers and withdrawals. Contract-level timeouts and retries bound the impact. +- Soundness of the ZK verifier and correctness of the homomorphic update logic are critical; a bug can mint or burn encrypted balances. +- MPC-based audit key generation relies on its participant honesty threshold; a compromised threshold can leak arbitrary transactions to the auditor. ## Trade-offs -- **Identity privacy is not default:** Sender/receiver addresses can remain transparent unless combined with separate identity/relationship-obfuscation patterns. -- **Operational overhead:** Requires monitoring relayers/messaging, retries, and clear failure-handling for delayed acks. -- **Post-quantum exposure**: ElGamal homomorphic encryption relies on ECDLP broken by CRQC; HNDL risk is high for on-chain encrypted balances. Mitigation: lattice-based PKE. See [Post-Quantum Threats](../domains/post-quantum.md). +- Operational overhead: deployments must monitor relayers and messaging, implement retry logic, and expose clear failure handling for delayed acknowledgements. +- Identity privacy is not default: pair with stealth addresses or a shielding layer for counterparty privacy. +- Two-chain design adds latency: every transfer involves at least one cross-chain round trip before completion. +- Upgrade coordination: changes to the confidentiality layer's circuits or messaging format must be coordinated with the origin contract to avoid locking funds. ## Example -- A corporate treasury uses USDC on an EVM chain: - - Locks USDC into the origin contract, receives an encrypted balance. - - Executes private vendor payouts (amounts encrypted; counterparties known). - - When a vendor wants liquidity, they withdraw back to underlying transparent USDC on the origin chain. - - If audited, the treasury discloses the relevant invoices or transactions. +- A corporate treasury uses USDC on an origin EVM chain. +- It locks USDC into the origin contract and receives an encrypted balance on the confidentiality layer. +- It executes private vendor payouts: amounts are encrypted, counterparties are known. +- When a vendor wants liquidity, they withdraw, which unlocks transparent USDC back on the origin chain. +- If audited, the treasury discloses the relevant invoices or transactions through the audit-key mechanism. -## References +## See also -- Fairblock docs: [Technical Overview](https://docs.fairblock.network/docs/confidential_transfers/technical_overview) -- IBC overview: [light-client-based messaging](https://ibcprotocol.org/) +- [IBC: light-client-based messaging](https://ibcprotocol.org/) +- [Fairblock technical overview](https://docs.fairblock.network/docs/confidential_transfers/technical_overview) +- [Fairblock](../vendors/fairblock.md) diff --git a/patterns/pattern-permissioned-ledger-interoperability.md b/patterns/pattern-permissioned-ledger-interoperability.md index b750e20..d651753 100644 --- a/patterns/pattern-permissioned-ledger-interoperability.md +++ b/patterns/pattern-permissioned-ledger-interoperability.md @@ -1,74 +1,116 @@ --- title: "Pattern: Permissioned Ledger Interoperability" status: draft -maturity: pilot +maturity: testnet +type: standard layer: offchain -privacy_goal: Cross-ledger atomicity with counterparty-only visibility of transaction state -assumptions: Canton/DAML or similar sync protocol, harmonized governance, selective disclosure for regulators -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 + works-best-when: - - Multiple financial institutions each operate their own permissioned ledger but require atomic cross-ledger settlement - - Regulatory constraints prevent moving all participants onto a single shared chain + - Multiple financial institutions each operate their own permissioned ledger but require atomic cross-ledger settlement. + - Regulatory constraints prevent moving all participants onto a single shared chain. + avoid-when: - - Use cases require fully open participation on public blockchains - - Applications depend on composability with EVM/ZK ecosystems -dependencies: [DAML, ISO20022, EAS, custom sync protocols] + - Use cases require fully open participation on public blockchains. + - Applications depend on composability with EVM or ZK ecosystems. + context: i2i + crops_profile: cr: none - os: partial - privacy: partial - security: medium + o: no + p: partial + s: low + +crops_context: + cr: "Each ledger operator controls participation, so CR is structurally `none` for non-members. Could reach `medium` if validators join permissionlessly via bonding with protocol-enforced exit rights." + o: "Sync protocols exist as open specifications (e.g., Canton Network) but core implementations are often proprietary or tightly coupled to a vendor stack. Reaches `yes` when the full protocol and reference implementation are published under permissive or copyleft licenses." + p: "Counterparty-only visibility of transaction payloads between the two transacting domains. Cross-domain messages reveal the existence of interactions. Reaches `full` with end-to-end encryption of cross-domain messages and scoped view keys for regulators." + s: "Rides on each domain's local consensus and on the sync protocol's commit coordination. Reaches `high` with proven Byzantine consensus liveness under partition and honest-minority thresholds on the sync coordinator." + +post_quantum: + risk: medium + vector: "Sync protocols rely on classical signatures (ECDSA, EdDSA) for cross-domain attestations. HNDL risk on encrypted cross-domain payloads if stored long-term." + mitigation: "Migrate cross-domain signing to hash-based or lattice-based schemes; encrypt long-lived payloads with hybrid PQ-secure transport." + +visibility: + counterparty: [amounts, identities, terms] + chain: [] + regulator: [full_tx with scoped disclosure] + public: [] + +standards: [DAML, ISO-20022, EAS, ERC-7573] + +related_patterns: + composes_with: [pattern-dvp-erc7573, pattern-private-iso20022, pattern-crypto-registry-bridge-ewpg-eas] + alternative_to: [pattern-privacy-l2s] + see_also: [pattern-regulatory-disclosure-keys-proofs] + +open_source_implementations: + - url: https://github.com/digital-asset/daml + description: "Digital Asset's DAML smart contract language and Canton runtime" + language: "Scala, DAML" + - url: https://github.com/hyperledger/besu + description: "Enterprise EVM client with permissioned networking and privacy groups" + language: "Java" --- ## Intent -Enable atomic transactions and data exchange across distinct permissioned ledgers, so that institutions can interoperate without exposing all contract state or migrating to a single ledger. +Enable atomic transactions and data exchange across distinct permissioned ledgers, so that institutions can interoperate without exposing all contract state or migrating to a single ledger. Each domain keeps its own consensus and governance; a coordination protocol synchronizes commits across domains. + +## Components + +- **Permissioned ledger domains**, each with its own consensus, identity set, and privacy boundary. +- **Synchronization protocol** that coordinates commits across domains (two-phase or view-based atomic commit). +- **Smart contract language** with explicit participant visibility controls, so contract state is replicated only to actual stakeholders. +- **Governance model** for validator or participant node admission, rotation, and exit. +- **Selective disclosure mechanism** for supervisors and auditors to access relevant state without full replication. + +## Protocol -## Ingredients +1. [operator] Deploy applications or contracts on separate permissioned ledgers, one domain per participant group. +2. [contract] Each ledger operates its own local consensus and privacy domain independently. +3. [operator] A synchronization protocol links ledgers for cross-domain transactions, typically via relayers or a coordinator committee. +4. [user] Parties agree off-chain on transaction terms (e.g., bond delivery versus cash payment). +5. [contract] Each domain validates locally, then exchanges commitments or proofs with the counterparty domain. +6. [contract] The sync protocol ensures atomic commit: either all domains finalize or all abort. +7. [regulator] Supervisors access relevant state via scoped disclosure keys or attestations. -- Permissioned ledgers (e.g., Canton domains, Corda networks, Hyperledger Fabric instances) -- Synchronization protocol to coordinate transaction commits across domains -- Smart contract language (DAML or equivalent) -- Governance model for validator/participant nodes -- Selective disclosure mechanisms for regulators +## Guarantees & threat model -## Protocol (concise) +Guarantees: -1. Parties deploy applications/contracts on separate permissioned ledgers. -2. Each ledger operates its own consensus and privacy domain. -3. A synchronization protocol links ledgers for cross-domain transactions. -4. Parties agree on transaction terms (e.g., bond delivery vs. cash payment). -5. Domains validate locally, then exchange commitments. -6. Protocol ensures atomic commit: either all domains finalize or none do. -7. Regulators can access relevant state via scoped disclosure. +- Atomicity: cross-ledger operations settle consistently or abort. +- Counterparty privacy: only transacting parties see payload state; other domains observe only commitment envelopes. +- Regulatory audit: scoped access for supervisory entities via dedicated disclosure paths. -## Guarantees +Threat model: -- **Atomicity**: cross-ledger operations settle consistently or abort. -- **Privacy**: only counterparties see transaction state; other domains are unaware. -- **Regulatory audit**: scoped access for supervisory entities. +- Honesty of the sync coordinator or relayer set. A malicious coordinator can stall commits but cannot unilaterally fabricate state. +- Each domain's local consensus. A compromised domain can produce inconsistent views to counterparties. +- Operator control over admission. Each ledger operator retains the ability to deny access, freeze assets, or refuse to process transactions within its domain. +- Cross-chain atomicity under partition is out of scope for simple two-phase commit; stronger protocols are needed when domains lose connectivity mid-commit. ## Trade-offs -- **Performance**: synchronization adds latency vs. single-ledger settlement. -- **Complexity**: requires harmonization of governance and protocol standards. -- **Interoperability limits**: not natively composable with public-chain DeFi. -- **Failure modes**: stalled domain halts atomic settlement. -- **Operator censorship**: each ledger operator controls participation; can deny access, freeze assets, or refuse to process transactions. -- **CROPS context (i2i)**: CR could reach `medium` if validators can join permissionlessly via bonding with protocol-enforced exit rights. OS improves to `yes` by open-sourcing the sync protocol under copyleft. Privacy could reach `full` by encrypting cross-domain messages end-to-end with scoped view keys. Security could reach `high` by proving Byzantine consensus liveness under partition. Operator control over access and asset freezes is the primary censorship risk; decentralized validator admission mitigates this. +- Performance: synchronization adds latency versus single-ledger settlement, particularly under two-phase commit. +- Complexity: requires harmonization of governance, participant identity, and protocol versions across domains. +- Interoperability limits: not natively composable with public-chain DeFi or Ethereum L2 tooling. +- Failure modes: a stalled domain halts atomic settlement for any transaction touching it; timeouts and rollback paths must be specified. +- Operator censorship: each ledger operator controls participation within its domain; decentralized validator admission mitigates but does not eliminate this. ## Example -- Bank A issues a bond on Ledger X. -- Investor B holds cash tokens on Ledger Y. -- Both ledgers participate in a Canton synchronization protocol. -- Transaction: Investor B buys €10m of bonds, payment vs. delivery. -- Ledger X transfers bond tokens, Ledger Y transfers cash tokens. -- Atomic commit finalizes on both ledgers, with regulators able to view audit trail. +- Bank A issues a bond on Ledger X (its domain). +- Investor B holds cash tokens on Ledger Y (its domain). +- Both ledgers participate in a shared synchronization protocol. +- Transaction: Investor B buys 10m euro of bonds, payment versus delivery. +- Ledger X transfers bond tokens and Ledger Y transfers cash tokens under a single atomic commit. +- Supervisors access the audit trail via scoped disclosure on both domains. ## See also -- Pattern: [DvP ERC-7573](../patterns/pattern-dvp-erc7573.md) -- Pattern: [Private ISO20022](../patterns/pattern-private-iso20022.md) -- Pattern: [Crypto-Registry Bridge eWpG-EAS](../patterns/pattern-crypto-registry-bridge-ewpg-eas.md) +- [Canton Network overview](https://www.canton.network/) +- [DAML documentation](https://docs.daml.com/) +- [Hyperledger Besu privacy groups](https://besu.hyperledger.org/) diff --git a/patterns/pattern-permissionless-spend-auth.md b/patterns/pattern-permissionless-spend-auth.md index 89bfc9f..40c4dfc 100644 --- a/patterns/pattern-permissionless-spend-auth.md +++ b/patterns/pattern-permissionless-spend-auth.md @@ -1,108 +1,103 @@ --- title: "Pattern: Permissionless Spend Auth" status: draft -maturity: PoC +maturity: concept +type: standard layer: L1 -privacy_goal: Extensible authentication without fragmenting anonymity sets -assumptions: Ownership/auth split, outer/inner circuit model, Merkleized auth policy registry, ZK proof system -last_reviewed: 2026-03-16 -context: both -crops_profile: - cr: high - os: yes - privacy: full - security: high +last_reviewed: 2026-04-22 + works-best-when: - - Multiple auth methods must coexist in one shielded pool (ECDSA, P-256, post-quantum). + - Multiple auth methods must coexist in one shielded pool (ECDSA, P-256, post-quantum schemes). - Switching auth methods should not require migrating funds. - Auth method choice itself must remain private. -avoid-when: - - Single auth scheme is sufficient and will not change. - - Pool is app-level and already hardcodes one verification key. -dependencies: - - ZK proof system (recursive verification) - - Merkle tree (auth policy registry) - - EIP-8182 (draft) ---- -## Intent +avoid-when: + - A single auth scheme is sufficient and will not change. + - The pool is app-level and already hardcodes one verification key. -This pattern has two layers. One is a security-model decision: separate note ownership from spend authorization. The other is an implementation choice: use a recursive inner/outer circuit architecture so that multiple auth methods can coexist without fragmenting the anonymity set. +context: both +context_differentiation: + i2i: "Institutions rotate credentials over multi-year timelines (signing key compromise, HSM migration, post-quantum readiness). Separating ownership from auth lets one counterparty rotate signers without moving shielded positions, which would signal portfolio changes to the other side. Both counterparties still have legal recourse if an auth bug strands funds." + i2u: "End users depend on auth method privacy to avoid being de-anonymized by their wallet choice. A user-held ownership secret protects against operator coercion: even if the wallet provider is compelled to rotate or revoke auth credentials, the user retains the ability to spend as long as they hold the ownership secret. Forced withdrawal guarantees must not depend on any specific auth method." -## Layer 1: Ownership / auth split +crops_profile: + cr: high + o: yes + p: full + s: high -In most shielded pool designs, a note's owner field is the auth credential itself — typically a public key. Ownership and authentication are the same thing. Changing your key changes your identity, and existing notes are stranded. +crops_context: + cr: "On L1 permissionless pools with open submission paths. Drops to `medium` if only whitelisted inner circuits are accepted, since auth method diversity would then require protocol-level approval." + o: "Outer circuit is a fixed protocol artifact. Inner circuits can be authored and deployed permissionlessly, so the auth layer is natively open and forkable. Reaches `partial` only if the registry itself is gated." + p: "`innerVkHash` is a private witness in the outer proof, so on-chain observers cannot tell which auth method was used. Unifies the anonymity set across all supported methods. Metadata leakage at the network and registry layers is out of scope for this pattern." + s: "Outer circuit independently enforces ownership and value conservation, so a bug in an inner circuit can only affect users of that specific method, not the whole pool. Rides on the soundness of the recursive proof system." -This pattern separates the two. Notes commit to an ownership secret (e.g., a hash of a private key) that is independent of any particular auth credential. To spend a note, you must prove two things: that you own it (knowledge of the ownership secret) and that you authorized this specific transaction (a valid credential). These are checked independently. +post_quantum: + risk: medium + vector: "Outer circuit uses EC-based proof systems (Groth16, PLONK/KZG) vulnerable to CRQC. Classical auth inner circuits (ECDSA, EdDSA) are equally exposed." + mitigation: "Hash-based outer circuit (STARK-style) plus lattice-based inner circuits. The recursive architecture makes it possible to add a post-quantum inner circuit alongside classical ones without migrating existing notes." -**Why separate them:** +standards: [EIP-8182] -- **Privacy loss ≠ fund loss.** Ownership and authorization are different capabilities. A leaked ownership secret reveals what you own and lets an attacker track your spending, but it doesn't let them take your money — they still need to pass auth. In a monolithic design where ownership = auth, one leaked key loses everything. -- **Privacy loss can be bounded; fund loss can't.** Because privacy and spending are controlled by different secrets, systems can be designed to limit privacy exposure to past transactions (e.g., by rotating secrets that control future derivations). Fund theft is instant and total. Separating the two means the recoverable failure mode (privacy) and the catastrophic one (funds) don't share a single point of failure. -- **Richer auth policies.** Auth can be a simple signature, a multisig threshold, a time-locked policy, or a spending limit. The ownership layer stays a simple secret. Authorization logic can be arbitrarily complex without changing the note format. -- **Non-custodial delegation.** A third-party prover needs the ownership secret to build the witness, but can't spend without passing auth. This is what makes safe proof delegation possible (see [Safe Proof Delegation](pattern-safe-proof-delegation.md)). +related_patterns: + requires: [pattern-shielding] + composes_with: [pattern-safe-proof-delegation, pattern-stealth-addresses] + see_also: [pattern-user-controlled-viewing-keys, pattern-forced-withdrawal] -## Layer 2: Recursive permissionless auth architecture +open_source_implementations: [] +--- -Given that ownership and auth are separate, the question is how to support multiple auth methods without fragmenting the pool. +## Intent -One approach: deploy a separate circuit for each auth method. Each circuit handles both ownership and its specific auth scheme. This works, but every new auth method means a new verification key, which means transactions are distinguishable by auth method on-chain (anonymity set fragmentation), and adding a method requires a protocol upgrade or governance action to register the new circuit. +Separate note ownership from spend authorization in a shielded pool, and use a recursive inner-outer circuit architecture so that multiple auth methods can coexist without fragmenting the anonymity set. Users can rotate or add auth methods without moving funds, and observers cannot tell which method authorized a given spend. -The recursive approach avoids both problems: +## Components -- A stable **outer circuit** (protocol-managed) proves ownership and enforces pool invariants. -- A permissionless **inner circuit** (anyone can write and deploy) proves authorization and outputs a fixed public vector: a fixed public vector identifying who authorized, what credentials were used, and what was authorized. -- The outer circuit recursively verifies the inner circuit's proof. On-chain, the result is a single proof — observers cannot tell which inner circuit was used. +- **Ownership secret**: a per-user secret (e.g., a nullifier key) committed in each note via its hash. Not derived from any auth credential. +- **Auth policy registry**: on-chain Merkleized registry binding `(userIdentifier, innerVkHash)` to credentials. Separate from the note tree so auth updates do not touch note state. +- **Outer circuit (stable)**: proves ownership, enforces pool invariants (value conservation, nullifier correctness), and recursively verifies the inner proof. +- **Inner circuit (permissionless)**: proves authorization for a registered auth policy. Anyone can author and deploy a new inner circuit type. +- **Recursive verifier**: the outer circuit verifies the inner circuit's proof inline, producing a single on-chain proof format. -**What the recursive model gives you:** +The shielded pool this plugs into is described in `pattern-shielding`. -- **One note tree, one nullifier set.** All auth methods share the same pool state. -- **Auth-method privacy at transaction time.** `innerVkHash` is a private witness. Transactions look identical regardless of auth method. -- **No fund migration when switching auth.** Because ownership and auth are separate and all auth methods share the same pool, switching methods is just a registry update — no need to transfer notes to a new identity. -- **No protocol upgrade per auth method.** New inner circuits are deployed permissionlessly. Users register an auth policy and start using it. -- **No per-auth-method pools or circuit IDs.** The base protocol has one outer circuit. Auth diversity lives in the registry. +## Protocol -## Ingredients +1. [user] Register an auth policy by writing `(userIdentifier, innerVkHash)` to the on-chain registry. Multiple entries per owner are allowed (e.g., ECDSA plus passkey). +2. [prover] The inner circuit takes private witness data (signature, key material) and outputs a fixed public vector identifying who authorized, what credentials were used, and what was authorized. +3. [prover] The outer circuit proves the spender knows the ownership secret committed in the note, recursively verifies the inner proof, and checks that the inner outputs match the registry and the transaction data. +4. [contract] The outer proof is submitted to the shielded pool contract, which verifies it and updates the commitment and nullifier sets. +5. [user] Observers see one uniform proof format. `innerVkHash` remains a private witness inside the outer proof, so the auth method stays hidden. +6. [user] To change auth methods, add a new registry entry. Existing notes remain spendable with any registered method. -- **Ownership secret**: a per-user secret (e.g., `nullifierKey`) committed in each note via its hash. Not derived from any auth credential. -- **Auth policy registry**: on-chain Merkleized registry binding `(userIdentifier, innerVkHash)` to credentials. Separate from the note tree. -- **Outer circuit** (stable): proves ownership and enforces pool invariants. -- **Inner circuit** (permissionless): proves authorization for a registered auth policy. -- **Recursive verifier**: outer circuit verifies the inner circuit's proof inline. +## Guarantees & threat model -## Protocol +Guarantees: -1. **Register auth policy.** User writes `(userIdentifier, innerVkHash)` to the on-chain registry. Multiple entries per owner allowed (e.g., ECDSA + passkey). -2. **Inner circuit proves authorization.** The inner circuit takes private witness data (signature, key material) and outputs a fixed public vector identifying who authorized, what credentials were used, and what was authorized. -3. **Outer circuit proves ownership and verifies auth.** The outer circuit proves the spender knows the ownership secret committed in the note, recursively verifies the inner proof, and checks that the inner outputs match the registry and the transaction data. -4. **Auth method stays hidden.** `innerVkHash` is a private witness inside the outer proof. On-chain observers see one uniform proof format. -5. **Switch without migration.** To change auth methods, the user adds a new registry entry. Existing notes remain spendable. +- Unified anonymity set. All auth methods share one note tree; spends using different methods are indistinguishable on-chain. +- Auth method privacy. Observers cannot determine which inner circuit was used. +- No fund migration. Changing or adding auth methods does not require moving notes. +- Ownership isolation. A bug in an inner circuit cannot forge ownership; it can produce false authorization claims but nothing else. The outer circuit independently enforces ownership, value conservation, and nullifier correctness. -## Guarantees +Threat model: -- **Unified anonymity set.** All auth methods share one note tree — ECDSA spends are indistinguishable from passkey spends on-chain. -- **Auth method privacy.** Observers cannot determine which inner circuit was used. -- **No fund migration.** Changing or adding auth methods does not require moving notes. -- **Ownership isolation.** A bug in an inner circuit cannot forge ownership — it can produce false authorization claims but nothing else. The outer circuit independently enforces ownership, value conservation, and nullifier correctness. +- Soundness of the recursive proof system. +- Soundness of each deployed inner circuit. A faulty inner circuit puts users of that specific method at risk but does not affect other methods or the ownership layer. +- Registry integrity. If the registry can be rewritten without user consent, auth policies can be stolen; the registry must be append-only or governed by the user's ownership secret. +- Ownership secret custody. Loss of the ownership secret is permanent fund loss regardless of registered auth methods. ## Trade-offs -- **Recursive proof cost.** Inner proof verification inside the outer circuit increases proving time and circuit complexity. -- **Outer circuit rigidity.** Adding new inner circuit types is permissionless, but the outer circuit interface is fixed. Changing it requires a protocol upgrade. -- **Inner circuit trust.** A faulty inner circuit could let an unauthorized party prove "auth" — funds at risk for users of that specific method, though other methods and the ownership layer are unaffected. -- **Separate ownership secret.** Users must manage an ownership secret that is independent of their auth credentials. Loss of this secret is permanent fund loss, regardless of which auth methods are registered. +- Recursive proof cost. Inner proof verification inside the outer circuit increases proving time and circuit complexity. +- Outer circuit rigidity. Adding new inner circuit types is permissionless, but the outer circuit interface is fixed. Changing it requires a protocol upgrade. +- Separate ownership secret. Users must manage an ownership secret independent of their auth credentials. This is a new key-management burden. +- Registry gas costs. Registering or rotating auth policies is an on-chain write. ## Example -- Alice registers ECDSA auth. Later she adds a P-256 passkey as a second method. She spends a note using her passkey; on-chain, the transaction looks identical to any ECDSA spend. When she later rotates to a post-quantum scheme, her existing notes remain spendable — no withdrawal and re-deposit needed. - -## Implementation note - -EIP-8182 implements this pattern using Ethereum addresses as the owner identifier and `nullifierKeyHash` as the ownership commitment in each note. The auth policy registry maps `(address, innerVkHash)` to credentials. Other implementations could use different owner identifier schemes while preserving the same ownership/auth split. +- A user registers ECDSA auth. Later they add a P-256 passkey as a second method. They spend a note using the passkey; on-chain, the transaction looks identical to any ECDSA spend. When they later rotate to a post-quantum scheme, existing notes remain spendable with no withdrawal and re-deposit required. ## See also -- [Shielding](pattern-shielding.md) - the shielded pool this auth pattern plugs into -- [Safe Proof Delegation](pattern-safe-proof-delegation.md) - intent-based delegation that composes with this circuit model -- [EIP-8182 (draft)](https://github.com/ethereum/EIPs/pull/11373) +- [EIP-8182 draft](https://github.com/ethereum/EIPs/pull/11373) - [Post-Quantum Threats](../domains/post-quantum.md) diff --git a/patterns/pattern-plasma-stateless-privacy.md b/patterns/pattern-plasma-stateless-privacy.md index 0d4b0b7..29bf14c 100644 --- a/patterns/pattern-plasma-stateless-privacy.md +++ b/patterns/pattern-plasma-stateless-privacy.md @@ -1,85 +1,121 @@ --- title: "Pattern: Stateless Plasma Privacy" status: draft -maturity: PoC +maturity: testnet +type: standard layer: L2 -privacy_goal: Private transfers with client-side proving and minimal on-chain footprint -assumptions: Client-side proof generation, block producer availability, user data custody -last_reviewed: 2026-01-27 +last_reviewed: 2026-04-22 + works-best-when: - - High transaction volume with privacy requirements - - Users can manage their own transaction data (institutional clients with infrastructure) - - Minimal L1 data footprint is critical for cost or privacy + - High transaction volume with privacy requirements. + - Users can manage their own transaction data (institutional clients with infrastructure). + - Minimal L1 data footprint is critical for cost or privacy. + avoid-when: - - Users cannot reliably store/backup their own state - - Real-time settlement finality required (Plasma exits have delay) - - Complex smart contract logic needed (stateless model limits programmability) -dependencies: [ZK proofs, Merkle commitments, L1 anchor contract] + - Users cannot reliably store or back up their own state. + - Real-time settlement finality is required (Plasma exits have delay). + - Complex smart-contract logic is needed (stateless model limits programmability). + context: both +context_differentiation: + i2i: "Institutions already run reliable off-chain infrastructure, so data custody is a known cost. The value of stateless Plasma at I2I scale is minimal L1 footprint and no shared pool state, which avoids revealing portfolio sizes via gas patterns or commitment volumes. Forced exits via the L1 anchor let either counterparty settle unilaterally if the block producer stalls." + i2u: "End users cannot reliably custody their own data long-term. This pattern is only safe for user-facing deployments when paired with redundant self-hosted or trust-minimized data availability. Forced withdrawal is critical: the L1 anchor must accept unilateral exit proofs so a censoring block producer cannot freeze user funds." + crops_profile: cr: medium - os: partial - privacy: full - security: medium + o: partial + p: full + s: medium + +crops_context: + cr: "Reaches `high` when the L1 anchor enforces forced exits via cryptographic proof-based withdrawals that bypass block producer liveness. Drops to `low` if the only withdrawal path depends on a single block producer's cooperation." + o: "Reaches `yes` when the block producer software, circuit code, and client software are all published under permissive or copyleft licenses in forkable repositories." + p: "Transaction amounts, sender, and receiver are hidden from chain observers; only block commitments and per-block sender lists are visible on L1. Network-layer metadata (IP, timing against the block producer) remains out of scope." + s: "Rides on L1 security for deposit and exit, on the ZK proof system for transfer validity, and on the user's ability to preserve their own data. Reaches `high` with post-quantum hash-based ZK primitives and robust self-hosted data availability." + +post_quantum: + risk: medium + vector: "Depends on the proof system. FRI-based systems (e.g., Plonky2) are hash-based and already PQ-leaning; KZG-based systems inherit elliptic-curve exposure. BLS signature aggregation on block producers is classically broken by CRQC." + mitigation: "FRI or STARK-based transfer validity proofs plus hash-based or lattice-based signature aggregation on the block producer." + +visibility: + counterparty: [amounts, identities] + chain: [block_commitments, sender_lists] + regulator: [full_tx with user-provided viewing material] + public: [block_commitments] + +standards: [ERC-20] + +related_patterns: + requires: [pattern-shielding] + alternative_to: [pattern-privacy-l2s] + see_also: [pattern-forced-withdrawal, pattern-l2-encrypted-offchain-audit] + +open_source_implementations: + - url: https://github.com/ethereum/iptf-pocs/tree/master/pocs/private-payment/plasma + description: "IPTF PoC scaffolding an Intmax2-style stateless Plasma private-payment stack" + language: "Rust, Solidity" --- ## Intent -Use stateless Plasma architecture to enable private token transfers where transaction data remains with users (client-side), only commitments are posted on-chain, and validity is proven via zero-knowledge proofs. This provides strong privacy (no on-chain transaction graph) with L2 scalability. +Use a stateless Plasma architecture to enable private token transfers where transaction data stays with users client-side, only commitments are posted on-chain, and validity is proven via zero-knowledge proofs. This provides strong transaction-graph privacy with L2 scalability, at the cost of moving data-availability responsibility to users. + +## Components -## Ingredients +- **L1 anchor contract**: stores block commitments (Merkle roots of transaction hashes) and handles deposits, withdrawals, and forced exits. +- **Block producer**: aggregates transactions, collects signatures, and posts the block commitment to L1. Stateless with respect to transaction contents. +- **Client-side prover**: users generate ZK balance and transfer proofs locally (e.g., recursive FRI-based proofs). +- **User-held data availability**: users custody their own note and transfer history. Optional trust-minimized DA layer for redundancy. +- **Forced-exit mechanism**: L1 contract accepts exit proofs independently of the block producer, bypassing liveness failure. -- **L1 Anchor Contract**: Stores Merkle roots of valid state; handles deposits/withdrawals -- **Block Producer**: Aggregates transactions, generates inclusion proofs, posts commitments -- **Client-Side Prover**: Users generate ZK proofs for their transactions locally -- **Data Availability**: Users custody their own transaction data (or use optional DA layer) -- **Standards**: ERC-20 for deposits; ZK circuit for transfer validity +## Protocol -## Protocol (concise) +1. [user] Deposit an ERC-20 to the L1 anchor contract, which credits a balance commitment on L2. +2. [user] Generate a ZK proof of a valid transfer client-side; send the proof and an encrypted note to the recipient. +3. [operator] The block producer collects signatures and proofs, builds a Merkle tree of the new state, and verifies correctness. +4. [operator] The block producer posts the state root to L1 as a minimal block commitment. +5. [user] The recipient stores the received note locally and can spend it in future transactions. +6. [user] To exit, generate an exit proof showing ownership and initiate L1 withdrawal (subject to a challenge period). +7. [contract] If the block producer stalls, any user can initiate forced exit against the L1 anchor using their own locally held proofs. -1. **Deposit**: User locks ERC-20 on L1; receives corresponding balance commitment on L2. -2. **Transfer**: Sender generates ZK proof of valid transfer; sends proof + encrypted note to recipient. -3. **Aggregate**: Block producer collects proofs, verifies, builds Merkle tree of new state. -4. **Commit**: Block producer posts state root to L1 (minimal data: just the root hash). -5. **Receive**: Recipient stores received note locally; can spend in future transactions. -6. **Withdraw**: User generates exit proof showing ownership; initiates L1 withdrawal (with challenge period). +## Guarantees & threat model -## Guarantees +Guarantees: -- **Privacy**: Transaction amounts, sender, and recipient hidden from chain observers; only commitments visible -- **Validity**: ZK proofs ensure no double-spend or inflation without revealing transaction details -- **Self-Custody**: Users control their own data; no operator can freeze or censor specific balances -- **L1 Security**: Funds secured by L1; users can always exit with valid proof +- Transaction amounts, sender, and receiver are hidden from chain observers; only commitments and per-block sender lists are visible. +- ZK proofs ensure no double-spend or inflation without revealing transaction details. +- Users control their own data; no operator can freeze specific balances if forced exit is implemented. +- Funds are secured by L1; users can always exit with a valid proof. + +Threat model: + +- Soundness of the ZK proof system. +- Correct implementation of the L1 anchor, especially the forced-exit path. +- User data loss. A user who loses their local transaction history loses access to their funds; there is no protocol-level recovery. +- Block producer liveness. A stalled producer halts new transactions; users can still exit unilaterally with their own proofs. +- Network-layer metadata (timing, IP against the block producer) is out of scope for the pattern. ## Trade-offs -- **User Responsibility**: Users must backup their transaction data; loss means loss of funds -- **Exit Delay**: Plasma withdrawals have challenge period (typically 7 days) for fraud proofs -- **Limited Programmability**: Stateless model restricts complex contract interactions -- **Block Producer Trust**: Liveness depends on block producer; censorship possible (but not theft) -- **Client Compute**: Proof generation requires client-side resources (acceptable for institutions) -- **CROPS context (both)**: CR could reach `high` if protocol-enforced forced exits via the L1 anchor allow cryptographic proof-based withdrawals that bypass block producer liveness. OS improves to `yes` by publishing all circuit code in a forkable repository under a permissive open-source license. Security could reach `high` by adopting post-quantum hash-based ZK primitives. In I2I, forced exit guarantees ensure no block producer can hold institutional funds hostage. In I2U, self-sovereign withdrawal rights protect end users from operator censorship. +- User responsibility for data backup. Institutions can absorb this cost; individual users often cannot without additional infrastructure. +- Exit delay. Plasma withdrawals have a challenge period (typically around 7 days) to allow fraud proofs. +- Limited programmability. The stateless model restricts complex contract interactions compared with privacy rollups. +- Block producer trust for liveness. Censorship is possible even if theft is not. +- Client compute. Proof generation requires client-side resources, which is acceptable for institutions but may be demanding for end-user devices. ## Example -**Private Stablecoin Onboarding** - -1. Institution A deposits 1M USDC to Plasma L1 contract; receives private balance commitment. -2. Institution A transfers 500K privately to Institution B; generates proof locally, sends encrypted note. -3. Block producer includes transaction in block; posts only Merkle root to L1. -4. Institution B receives note, verifies proof, stores locally. -5. On-chain observers see only: "some deposit occurred" and "state root updated" — no amounts, no parties. -6. Institution B can later withdraw to any L1 address, breaking link to original depositor. +- Institution A deposits 1m stablecoin to the L1 anchor and receives a private balance commitment. +- Institution A transfers 500k privately to Institution B, generates the proof locally, and sends an encrypted note. +- The block producer includes the transaction in a block and posts only the Merkle root to L1. +- Institution B receives the note, verifies the proof, and stores it locally. +- On-chain observers see only that a deposit occurred and that a state root was updated; no amounts and no parties. +- Institution B can later withdraw to any L1 address, breaking the link to the original depositor. ## See also -- [Privacy L2s](pattern-privacy-l2s.md) — Alternative: native privacy rollups (Aztec) -- [Shielding](pattern-shielding.md) — Alternative: L1 shielding pools -- [L2 Encrypted Offchain Audit](pattern-l2-encrypted-offchain-audit.md) — Audit trail for compliance +- [Plasma original paper](https://plasma.io/) +- [Plasma-free paper (eprint 2023/1670)](https://eprint.iacr.org/2023/1670) +- [Intmax2 paper (eprint 2025/021)](https://eprint.iacr.org/2025/021) - [Post-Quantum Threats](../domains/post-quantum.md) - -## References - -- Intmax (stateless Plasma): https://www.intmax.io/ -- Plasma Free paper: https://eprint.iacr.org/2023/1670 -- Original Plasma: https://plasma.io/ diff --git a/patterns/pattern-pretrade-privacy-encryption.md b/patterns/pattern-pretrade-privacy-encryption.md index ab8b491..804d1f4 100644 --- a/patterns/pattern-pretrade-privacy-encryption.md +++ b/patterns/pattern-pretrade-privacy-encryption.md @@ -1,55 +1,128 @@ --- -title: "Pattern: Pre-trade privacy (Shutter/SUAVE/private RFQ)" +title: "Pattern: Pre-trade Privacy (Encrypted Order Flow)" status: ready -maturity: pilot +maturity: testnet +type: meta layer: hybrid -privacy_goal: Prevent front-running and information leakage via encrypted order submission -assumptions: Encrypted mempool (Shutter) or private builders (SUAVE), allow-listed counterparties -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 + +sub_patterns: + - name: "Threshold-encrypted mempool" + pattern: pattern-threshold-encrypted-mempool + crops_summary: "Medium CR via committee, partial privacy (decrypted post-inclusion), low-medium security (committee collusion risk)." + - name: "Private transaction broadcasting" + pattern: pattern-private-transaction-broadcasting + crops_summary: "Low-medium CR via private relay, partial privacy pre-inclusion, relies on builder honesty." + - name: "Shielded settlement" + pattern: pattern-shielding + crops_summary: "Medium CR, full privacy on amounts/counterparties post-inclusion." + works-best-when: - - RFQ/secondary trading must not leak intent, size, or price pre-inclusion. + - RFQ or secondary trading must not leak intent, size, or price pre-inclusion. + - Order flow needs protection from both the public mempool and builders that could front-run. + avoid-when: - - You accept public mempool visibility of orders. -dependencies: - - Encrypted mempool (Shutter) or private builders (SUAVE) - - RFQ service + - Public mempool visibility of orders is acceptable. + - Latency budgets cannot accommodate threshold-encryption or private builder round-trips. + context: both +context_differentiation: + i2i: "Institutional block trades signal portfolio intent long before settlement. Encrypting RFQ and quote flow until inclusion prevents counterparties, intermediaries, and builders from adverse selection or front-running. Both sides have legal recourse if an intermediary leaks, so the threat is reputational and economic rather than adversarial." + i2u: "Retail orders are extracted by builders, searchers, and private relays with operator-controlled visibility. Encrypted or threshold-encrypted submission removes the builder's ability to unilaterally front-run, but requires the user's tooling to integrate with the encrypted path. Without a fallback to an unencrypted route, a stalled decryption committee can effectively censor." + crops_profile: cr: low - os: partial - privacy: partial - security: low + o: partial + p: partial + s: low + +crops_context: + cr: "Depends on who can submit to the encrypted path. Reaches `high` only if the encrypted mempool committee is selected permissionlessly via stake-weighted rotation and includes a fallback to the standard mempool when decryption stalls." + o: "Some encryption and decryption implementations are open; some private builder stacks are proprietary. Reaches `yes` when all components, including the committee software and key-release logic, are open-source under permissive or copyleft licenses." + p: "Hides order intent, size, and price from the public mempool and (with threshold encryption) from any individual committee member. Metadata (timing, wallet connection, submission path) remains visible unless additionally shielded." + s: "Rides on committee honesty for threshold-encrypted paths or on operator honesty for private-builder paths. Reaches `high` with hardened collusion resistance and key compartmentalization across independent operators." + +post_quantum: + risk: medium + vector: "Threshold encryption and commit-reveal schemes often rely on pairings (BLS) or curve-based encryption broken by CRQC." + mitigation: "Lattice-based threshold encryption or hash-based commit-reveal with post-quantum VRFs for committee selection." + +visibility: + counterparty: [quote_contents] + chain: [settlement_events] + regulator: [full_order_lifecycle via audit path] + public: [] + +standards: [] + +related_patterns: + composes_with: [pattern-threshold-encrypted-mempool, pattern-private-transaction-broadcasting, pattern-shielding] + see_also: [pattern-private-pvp-stablecoins-erc7573, pattern-dvp-erc7573] + +open_source_implementations: + - url: https://github.com/shutter-network/shutter + description: "Threshold-encrypted mempool reference implementation" + language: "Rust, Go" + - url: https://github.com/flashbots/suave-geth + description: "Private builder and confidential compute environment for order flow" + language: "Go" --- ## Intent -Prevent **front-running and information leakage** by routing quotes/orders via **encrypted/private submission**; then settle with confidential tokens. -## Ingredients -- **Infra**: Shutter/SUAVE, allow-listed counterparties -- **Off-chain**: RFQ broker, audit of quote requests +Prevent front-running and information leakage by routing quotes and orders via encrypted or private submission paths so intent, size, and price stay hidden until inclusion. Settlement then proceeds on a shielded pool or confidential rail so the executed amounts also remain private. -## Protocol (concise) -1. Buyer emits RFQ off-chain; quotes returned privately. -2. Winning order submitted via encrypted route for inclusion. -3. Settlement occurs on privacy L2/L1 pool; amounts remain hidden. +## Components -## Guarantees -- No public mempool leakage of intent/size/price. -- Auditable RFQ lifecycle. +- **Encrypted submission path**: either a threshold-encrypted mempool (committee holds key shares; ciphertext is decrypted only after ordering is committed) or a private-builder stack (confidential execution environment that sees the order but commits to ordering honesty). +- **RFQ broker**: off-chain service that routes quote requests to allow-listed counterparties and records the quote lifecycle for audit. +- **Settlement rail**: shielded pool or privacy L2 where the winning order settles with amounts hidden. +- **Fallback path**: unencrypted submission route invoked if the encrypted path stalls or fails. +- **Audit trail**: signed or committed record of every RFQ, quote, and settlement for compliance review. + +The encrypted mempool details are covered in `pattern-threshold-encrypted-mempool`; the settlement layer in `pattern-shielding` or `pattern-privacy-l2s`. + +## Protocol + +1. [user] A buyer emits an RFQ off-chain. The request is routed to allow-listed counterparties via the RFQ broker. +2. [user] Counterparties return quotes privately to the broker, who relays them only to the requestor. +3. [user] The requestor selects a winning quote and submits the corresponding order via the encrypted path (threshold-encrypted ciphertext or private builder). +4. [operator] The committee or private builder includes the order in a block without revealing its contents pre-inclusion. +5. [contract] Settlement executes on the shielded rail: amounts, sender, and receiver stay hidden. +6. [auditor] The broker and committee produce an auditable record of the RFQ lifecycle for compliance review. + +## Guarantees & threat model + +Guarantees: + +- No public mempool leakage of intent, size, or price pre-inclusion. +- Auditable RFQ lifecycle available to regulators via scoped access. +- Settled amounts remain private when the settlement rail is shielded. + +Threat model: + +- Honesty of the threshold committee or private builder. A colluding quorum can decrypt early or leak selectively. +- Liveness of the encrypted path. A stalled committee or builder forces the fallback path, where orders become visible again. +- RFQ broker trust. A malicious broker can leak quote flow to non-participants even if the on-chain path is encrypted. +- Counterparty allow-list correctness. Mis-listed counterparties can exfiltrate order intent legally but undesirably. ## Trade-offs -- Additional infra dependency; fallback path required. -- Latency/availability tied to privacy routing. -- **CROPS context (both)**: CR could reach `high` if threshold committee selection becomes permissionless via stake-weighted rotation. OS improves to `yes` by open-sourcing all encryption and decryption logic under copyleft. Privacy could reach `full` by encrypting quotes end-to-end until settlement confirmation, not just during the pre-trade phase. Security could reach `high` by hardening collusion resistance through key compartmentalization across independent operators. In I2I, encrypted order flow prevents counterparties and intermediaries from front-running institutional block trades. In I2U, threshold encryption protects retail orders from MEV extraction by builders or relayers. -- **Post-quantum exposure**: threshold encryption schemes (Shutter/commit-reveal) may rely on pairings broken by CRQC. Mitigation: lattice-based threshold encryption. See [Post-Quantum Threats](../domains/post-quantum.md). + +- Latency and availability are tied to the privacy routing. A slow committee or builder can miss inclusion windows. +- Additional infra dependency. Both the encrypted mempool and the RFQ broker are new services that must be operated and monitored. +- Fallback paths reintroduce public mempool visibility; protocol design must make fallback rare and auditable. +- Allow-listed counterparties create a two-sided trust boundary that must be governed. ## Example -- Three quotes received; best quote settles; unfilled quotes remain undisclosed. + +- Three quotes are received for a block trade. +- The winning quote is submitted via the encrypted path. +- The losing quotes remain undisclosed to the public and to competing market makers. +- Settlement finalizes on a shielded pool. On-chain observers see only the settlement event, not the price or size. ## See also -- pattern-confidential-erc20-fhe-l2-erc7573.md · pattern-secondary-market-rfq-batched-settlement.md -## See also (external) -- Shutter docs: https://docs.shutter.network/docs/shutter/research/the_road_towards_an_encrypted_mempool_on_ethereum -- Flashbots · SUAVE overview: https://writings.flashbots.net/the-future-of-mev-is-suave -- Flashbots docs hub: https://docs.flashbots.net/ \ No newline at end of file +- [Shutter Network docs](https://docs.shutter.network/docs/shutter/research/the_road_towards_an_encrypted_mempool_on_ethereum) +- [SUAVE overview](https://writings.flashbots.net/the-future-of-mev-is-suave) +- [Flashbots documentation](https://docs.flashbots.net/) +- [Post-Quantum Threats](../domains/post-quantum.md) diff --git a/patterns/pattern-privacy-l2s.md b/patterns/pattern-privacy-l2s.md index 8cc1b44..00a9d68 100644 --- a/patterns/pattern-privacy-l2s.md +++ b/patterns/pattern-privacy-l2s.md @@ -1,73 +1,130 @@ --- -title: "Pattern: Private L2s" +title: "Pattern: Privacy L2s" status: draft -maturity: PoC +maturity: production +type: standard layer: L2 -privacy_goal: Execute financial logic with private state enabling confidential value and unlinkable identity -assumptions: Privacy-native rollup (ZK or FHE), L1 bridge contracts, viewing key infrastructure -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 + works-best-when: - - Strong privacy is required beyond value-hiding: identity unlinkability, programmable access. - - Institutions want to embed compliance hooks (view keys, audit proofs). + - Strong privacy is required beyond value-hiding, including identity unlinkability and programmable access controls. + - Institutions want to embed compliance hooks (view keys, audit proofs) directly into the execution environment. + avoid-when: - - You need conservative, battle-tested infra on Ethereum L1 today. - - Overhead is unjustified if only minimal value privacy is needed. -dependencies: - - L1 bridge contracts - - Viewing key infra / off-chain attestations + - A conservative, battle-tested L1 deployment path is required today. + - Only minimal value privacy is needed and bridging overhead is unjustified. + context: both +context_differentiation: + i2i: "Institutions can absorb bridging friction and centralized-sequencer risk as known operational costs. The primary value is programmable private state: confidential contract logic, private balances with DvP hooks, and selective disclosure integrated at the protocol level. Both counterparties share a legal framework, so temporary sequencer centralization is a liveness concern, not an existential one." + i2u: "End users face asymmetric exposure to the sequencer. A centralized sequencer can unilaterally exclude user transactions; without forced withdrawal via the L1 bridge, user funds can be stranded. Permissionless sequencer selection and forced-exit guarantees are prerequisites before this pattern is safe for user-facing deployments." + crops_profile: cr: medium - os: partial - privacy: full - security: medium + o: partial + p: full + s: medium + +crops_context: + cr: "Most privacy rollups today use centralized sequencing with no public censorship proofs. Reaches `high` when sequencer selection becomes permissionless leader election with enforceable L1 fallback. Drops to `low` on operator-controlled deployments with no forced-exit path." + o: "Some privacy L2 stacks are open source; others rely on proprietary provers or closed coprocessors. Reaches `yes` when the full node, prover, and circuit code are published under permissive or copyleft licenses with binding commitments against proprietary prover dependencies." + p: "Native privacy for amounts, sender, and receiver within the L2. Metadata (bridge activity, L1 anchoring timing) is visible on L1 and must be covered separately if metadata privacy matters." + s: "Rides on L1 security for the bridge, on the rollup's proof or FHE correctness, and on sequencer availability. Reaches `high` with committee-based state attestation (randomly selected validators signing each checkpoint) and decentralized sequencing." + +post_quantum: + risk: high + vector: "EC-based proof systems (Groth16, PLONK/KZG) dominate privacy rollup stacks and are broken by CRQC. FHE-based L2s depend on lattice hardness and are PQ-leaning, but the surrounding bridge and signature schemes are typically classical." + mitigation: "STARK-based rollups with hash commitments for PQ-secure proofs; hybrid PQ-secure bridges for cross-layer messages." + +visibility: + counterparty: [amounts, identities] + chain: [state_root_anchors] + regulator: [full_state with viewing key or disclosure proof] + public: [L1_anchor_commitments] + +standards: [ERC-20, ERC-3643, ERC-7573] + +related_patterns: + composes_with: [pattern-shielding, pattern-regulatory-disclosure-keys-proofs, pattern-dvp-erc7573, pattern-erc3643-rwa] + alternative_to: [pattern-plasma-stateless-privacy] + see_also: [pattern-forced-withdrawal, pattern-l2-privacy-evaluation, pattern-user-controlled-viewing-keys] + +open_source_implementations: + - url: https://github.com/AztecProtocol/aztec-packages + description: "Aztec Network: privacy L2 with native shielding" + language: "Noir, Rust, TypeScript" + - url: https://github.com/0xMiden/miden-node + description: "Miden zkVM client-side proving rollup" + language: "Rust" + - url: https://github.com/zama-ai/fhevm + description: "fhEVM: FHE-based confidential EVM" + language: "Solidity, Rust" + - url: https://github.com/ethereum/iptf-pocs/tree/master/pocs/private-bond/privacy-l2 + description: "IPTF PoC: private institutional bond on a privacy L2" + language: "Noir, Solidity" --- ## Intent -Use a **privacy-native rollup** (ZK or FHE-based) to execute financial logic with private state, enabling both **confidential value** and **unlinkable identity flows**. +Use a privacy-native rollup, either ZK-based or FHE-based, to execute financial logic with private state. This enables confidential value and unlinkable identity flows in a programmable environment, while anchoring security on Ethereum L1 via a bridge. + +## Components + +- **Privacy rollup execution layer**: either a ZK rollup that commits to state via ZK proofs of valid transitions, or an FHE rollup that computes on encrypted state. +- **L1 bridge contracts**: deposit, withdraw, and forced-exit paths that anchor the rollup to Ethereum. +- **Client-side or coprocessor prover**: generates ZK proofs for private state transitions, or orchestrates FHE computation. +- **Viewing key and disclosure infrastructure**: off-chain key management and attestation services for regulator access. +- **Sequencer or block builder**: collects and orders transactions for the rollup; centralized on most deployments today. + +Shielded note logic on the rollup is described in `pattern-shielding`; disclosure flows in `pattern-regulatory-disclosure-keys-proofs`. + +## Protocol -## Ingredients +1. [user] Bridge assets from L1 to the privacy L2 via a deposit contract. +2. [contract] Assets are converted to private notes or encrypted balances on the L2. +3. [user] Execute transactions privately within the L2 (amounts, senders, receivers shielded within the rollup). +4. [prover] Generate ZK proofs (or FHE state-transition proofs) for valid state transitions. +5. [sequencer] Order and aggregate transitions; post the proof and state root to L1. +6. [contract] Optionally couple settlement with an on-chain DvP or PvP contract for atomic cross-asset flows. +7. [regulator] Access transaction details via viewing keys or disclosure proofs as required. +8. [user] Exit to L1 by submitting a withdrawal proof of valid state ownership. -- **Standards**: ERC-20/3643 (bridged); ERC-7573 optional for settlement -- **Infra**: - - ZK rollups: Aztec, Aleo, Lita, Miden - - FHE rollups: Zama/fhEVM, Inco -- **Off-chain**: Key management, regulator view proofs +## Guarantees & threat model -## Protocol (concise) +Guarantees: -1. Bridge assets from L1 to privacy L2 via deposit contract. -2. Assets converted to private notes/commitments on the L2. -3. Execute transactions privately within L2 (amounts, senders, receivers shielded). -4. Generate ZK proofs (or FHE computations) for state transitions. -5. Optionally couple with ERC-7573 for atomic DvP/PvP settlement. -6. Provide viewing keys or disclosure proofs to regulators as needed. -7. Exit to L1 via withdrawal with proof of valid state. +- Private transactions: amounts, sender, and receiver are shielded within the L2. +- Private state: balances and contract state are stored as encrypted commitments or notes. +- Interoperability with L1 state: rollup state roots anchor on L1, enabling bridging and settlement with L1 assets. +- Programmable compliance: viewing keys, selective disclosure, and audit proofs can be embedded in contract logic. -## Guarantees +Threat model: -- **Private transactions**: Transaction details (amounts, senders, receivers) are shielded within the L2. -- **Private state**: Balances and contract state are stored as encrypted commitments/notes. -- **Interoperability with L1 state**: Rollup state roots anchor on L1, enabling bridging and settlement with L1 assets. +- Bridge soundness. An exploited bridge can inflate or steal assets on L1. +- Proof system or FHE scheme soundness. Breaks here allow unauthorized state transitions. +- Sequencer liveness and honesty. A centralized or censoring sequencer can exclude transactions until the L1 forced-exit path is exercised. +- Viewing key custody. A compromised viewing key exposes the history protected under it. +- Non-standardized regulator interfaces. Each deployment rolls its own compliance hooks, creating fragmentation risk for supervisors. ## Trade-offs -- **Maturity risks**: Most private L2s are early-stage, limited production deployments. -- **Migration/bridging required**: Assets and apps must move from L1 or other L2s; adds friction. -- **New attack surfaces**: Viewing key compromise, bridge exploits. -- **Regulatory auditability uncertain**: While selective disclosure is possible, no standardized frameworks exist yet for regulator access or compliance proofs. -- **Sequencer centralization**: Most private L2 sequencers are currently centralized; can censor transactions until decentralized sequencing is implemented. -- **CROPS context (both)**: CR could reach `high` if sequencer selection shifts to permissionless leader election. OS improves to `yes` by requiring full source publication under copyleft with binding no-proprietary-prover commitments. Security could reach `high` by moving to committee-based state attestation with randomly selected validators signing each checkpoint. In I2I, decentralized sequencing ensures no single operator can censor institutional settlement transactions. In I2U, permissionless block production protects end users from unilateral transaction exclusion or ordering manipulation. +- Maturity risks. Most privacy L2s are early-stage with limited production deployments. +- Migration and bridging overhead. Assets and apps must move from L1 or other L2s, adding friction and new trust surfaces. +- New attack surfaces. Viewing key compromise, bridge exploits, and sequencer censorship. +- Regulatory auditability uncertain. Selective disclosure is possible, but no standardized frameworks exist yet for regulator access or compliance proofs. +- Sequencer centralization. Most privacy L2 sequencers are currently centralized and can censor until decentralized sequencing is implemented. ## Example -- Bond issuance + settlement on Aztec notes. -- FHE L2 running private credit risk models with encrypted inputs. +- Bond issuance and secondary trading on native shielded notes. +- An FHE-based L2 running a private credit risk model where inputs remain encrypted end-to-end and only the final attestation is revealed to the counterparty. ## See also -- Aztec docs: https://docs.aztec.network/ -- Aleo: https://aleo.org/ -- Zama fhEVM: https://docs.zama.org/protocol/protocol/overview -- Miden: https://miden.xyz/ +- [Aztec documentation](https://docs.aztec.network/) +- [Aleo](https://aleo.org/) +- [fhEVM documentation](https://docs.zama.org/protocol/protocol/overview) +- [Miden](https://miden.xyz/) +- [Aztec (vendor page)](../vendors/aztec.md) +- [Miden (vendor page)](../vendors/miden.md) +- [Zama (vendor page)](../vendors/zama.md) diff --git a/patterns/pattern-private-iso20022.md b/patterns/pattern-private-iso20022.md index a9c4140..7988dc7 100644 --- a/patterns/pattern-private-iso20022.md +++ b/patterns/pattern-private-iso20022.md @@ -1,116 +1,119 @@ --- title: "Pattern: Private ISO 20022 Messaging & Settlement" status: draft -maturity: experimental +maturity: concept +type: standard layer: hybrid -privacy_goal: Private ERC-20 settlements linked to ISO 20022 instructions with regulator-only visibility -assumptions: ISO 20022 schema, shielded pool or confidential token infrastructure, threshold KMS -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 + works-best-when: - - Institutions already exchange ISO 20022 messages (pacs.008/009/002, camt.\*). - - On-chain settlement (ERC-20, tokenized deposits) must link to SWIFT/ISO workflows. + - Institutions already exchange ISO 20022 messages (pacs.008, pacs.009, pacs.002, camt.\*). + - On-chain settlement (ERC-20, tokenized deposits) must link to existing ISO or correspondent banking workflows. - Regulators require selective audit, not full transparency. + avoid-when: - - Institutions are not ISO-native (retail/DeFi-native apps). - - Privacy is not a requirement (public stablecoins acceptable). -dependencies: - - ISO 20022 schema (pacs.008/009/002, camt.\*) - - ERC-20 / ERC-3643 (tokenized cash/RWA) - - Optional: ERC-7573 (conditional settlement), ZK proof system + - Institutions are not ISO-native (retail or DeFi-native apps). + - Privacy is not a requirement and a public stablecoin is acceptable. + context: i2i + crops_profile: cr: medium - os: partial - privacy: full - security: medium + o: partial + p: full + s: medium + +crops_context: + cr: "Reaches `high` when settlement runs on a single-chain shielded pool without a trusted relayer or gatekeeper. Drops to `low` when the private rail is operator-controlled or depends on a proprietary coprocessor with no open submission path." + o: "ISO 20022 schemas are open and widely adopted. SWIFT infrastructure is licensed and proprietary. The settlement rail determines overall openness: an open shielded pool improves the score, a proprietary FHE coprocessor degrades it. Reaches `yes` only when every component, including the ISO extension carriers and the settlement rail, is open-source." + p: "Cash-leg amounts and counterparties are hidden on-chain. The ISO instruction layer is off-chain and covered by existing bank-to-bank confidentiality practice. Metadata at intermediaries (correspondent banks that pass the message without understanding the extension) may still leak timing or existence." + s: "Rides on the settlement rail's cryptography (ZK proofs, FHE, threshold keys) and on signing conventions agreed between banks. Reaches `high` when signing algorithms, PKI, and the ISO extension registration are formally published and jointly governed." + +post_quantum: + risk: high + vector: "Cash-leg settlement rail typically uses EC-based ZK proofs (Groth16, PLONK/KZG) or pairing-based threshold encryption, all broken by CRQC. HNDL risk is high because correspondent-banking payloads are archived for years." + mitigation: "Migrate the settlement rail to STARK-based shielded pools with hash commitments; use lattice-based threshold encryption for any encrypted message envelopes." + +visibility: + counterparty: [amounts, terms, identities] + chain: [message_type, commitment, status] + regulator: [full_tx with view keys] + public: [] + +standards: [ISO-20022, ERC-20, ERC-3643, ERC-7573] + +related_patterns: + composes_with: [pattern-shielding, pattern-privacy-l2s, pattern-dvp-erc7573, pattern-regulatory-disclosure-keys-proofs] + see_also: [pattern-crypto-registry-bridge-ewpg-eas, pattern-permissioned-ledger-interoperability] + +open_source_implementations: [] --- ## Intent -Coordinate **private ERC-20 settlements** between banks using ISO 20022 as the instruction layer. -ISO messages are linked to the cash leg, while the **cash leg itself settles privately** via a shielded mechanism (privacy L2 / shielded pool / confidential token) with regulator-only visibility. - ---- - -## Ingredients +Coordinate private ERC-20 settlements between banks using ISO 20022 as the instruction layer. The ISO message binds to the on-chain cash leg, while the cash leg itself settles privately via a shielded mechanism (privacy L2, shielded pool, or confidential token) with regulator-only visibility. -- **Standards**: - - [ISO 20022 schema](https://www.iso20022.org/iso-20022-message-definitions) (pacs.008/009/002, camt.\*) - - [ERC-20](https://eips.ethereum.org/EIPS/eip-20) / [ERC-3643](https://eips.ethereum.org/EIPS/eip-3643) (tokenized cash/RWA) - - (Optional) [ERC-7573](https://eips.ethereum.org/EIPS/eip-7573) (conditional settlement / atomic coupling) - - [``](https://www.iso20022.org/supplementary_data.page) extension mechanism (proof/commitment carrier within ISO messages) -- **Infra** - - Privacy settlement rail: **shielded pool** (e.g., Aztec/Railgun/Penumbra) **or** **confidential token** (e.g., fhEVM-style) - - Rollup/validium for anchoring minimal metadata (msg type, status, coarse time bucket) -- **Off-chain** - - ISO parsing/normalization (XML → canonical JSON) - - KMS for bank/regulator keys; selective-disclosure service +## Components ---- +- **ISO 20022 schema and envelopes**: pacs.008, pacs.009, pacs.002, camt.\* messages plus the `` extension mechanism used to carry commitments and proofs. +- **Message commitment `C_msg`**: hash of the canonical ISO message used to bind the settlement on-chain to the off-chain instruction. +- **Private settlement rail**: a shielded pool, a confidential token layer, or a privacy L2 that performs the cash-leg transfer with amounts and counterparties hidden on-chain. +- **Rollup or validium anchor** for minimal on-chain metadata (message type, coarse time bucket, status). +- **Off-chain services**: ISO parsing and canonicalization (XML to canonical JSON), KMS for bank and regulator keys, and a selective-disclosure service. +- **Settlement controller**: optional permissioned actor that authorizes confidential transfers on a permissioned confidential-token rail. -## Protocol (private cash-leg variants) +The shielded pool details live in `pattern-shielding`; the privacy L2 option in `pattern-privacy-l2s`; DvP coupling in `pattern-dvp-erc7573`. -### A1. Shielded Pool Settlement +## Protocol -1. Anchor minimal ISO metadata (e.g., `msgType`, `timeBucket`) and a **message commitment** `C_msg` on-chain. -2. Wrap/mint the ERC-20 into a **shielded pool** and hold balances as **notes**. -3. Execute a **shielded transfer** from Bank A’s note to Bank B’s note, **binding** the transfer to `C_msg` (e.g., include `C_msg` in the spend circuit). -4. Regulator holds **view keys** for scoped audits (amounts/parties/routes if needed). +The pattern admits three variants for the cash leg. They share steps 1 to 3 and diverge at settlement. -### A2. Confidential Token Settlement (permissioned L2) +1. [user] Bank A issues an ISO 20022 message (e.g., `pacs.008` for a customer credit transfer) to Bank B. +2. [user] Off-chain, both banks compute `C_msg` from the canonical form of the ISO message. +3. [contract] Minimal ISO metadata and `C_msg` are anchored on a rollup or validium. +4. [contract] Variant A: the cash-leg ERC-20 is wrapped into a shielded pool and held as notes. A shielded transfer executes from Bank A's note to Bank B's note with `C_msg` bound inside the spend circuit. +5. [contract] Variant B: a confidential ERC-20 with encrypted balances executes a confidential transfer authorized by the settlement controller, referencing `C_msg`. +6. [contract] Variant C: both cash legs are temporarily bridged to a shared privacy L2. A single shielded DvP or PvP transaction referencing `C_msg` executes, then assets bridge back to their origin chains. +7. [regulator] The supervisor holds view keys for scoped audits (amounts, parties, routes as needed) and can decrypt selected fields or inspect shielded transfers. -1. Anchor minimal ISO metadata + `C_msg`. -2. Use a **confidential ERC-20** where balances and amounts are encrypted. -3. Settlement controller authorizes a **confidential transfer** (encrypted state update) referencing `C_msg`. -4. Regulator can view via scoped keys or field-level selective reveal. +The commitment and any ZK proof can be embedded in the ISO message using ``, with `` pointing to the extended element. ISO 20022's "can ignore" semantics mean intermediaries that do not support the extension process the message normally, while endpoints that understand it verify the proof. -### A3. Single-Domain Private Settle (roll-in, settle, roll-out) +## Guarantees & threat model -1. Temporarily bridge both legs to a **common privacy L2** (e.g.; Aztec). -2. Perform a **single-tx shielded DvP/PvP** referencing `C_msg`. -3. Bridge assets back to their origin chains as needed. +Guarantees: -### Proof Transport via `` +- Privacy: cash-leg amounts and counterparties are hidden on-chain. +- Integrity and linkage: settlement references `C_msg` so the cash leg is cryptographically tied to the ISO instruction. +- Auditability: regulators can decrypt selected fields or use view keys to audit shielded transfers. +- Interoperability: ISO schema provides consistent mapping across banks and corridors. -`C_msg` (and an optional ZK proof) can be embedded in the ISO message using `/`, with `` pointing to the extended element (e.g., `/Document/FIToFICstmrCdtTrf/CdtTrfTxInf`). +Threat model: -This leverages ISO 20022's **"can ignore" semantics**: intermediaries that do not support the extension process the message normally, only endpoints that understand the extension verify the proof. This enables **incremental adoption** across correspondent chains. - -To formalize, institutions can submit a **Change Request (CR)** to the relevant SEG to register an Extension `MessageDefinition` carrying proof data (commitments, ZK proofs, verification keys) as first-class ISO 20022 components. - ---- - -## Guarantees - -- **Privacy:** cash-leg amounts and counterparties are hidden on-chain (B1/B2/B3). -- **Integrity & linkage:** settlement references `C_msg` so the cash leg is cryptographically linked to the ISO instruction. -- **Auditability:** regulator can decrypt selected fields or use view keys to audit shielded transfers. -- **Interoperability:** ISO schema provides consistent mapping across banks/corridors. - ---- +- Settlement rail soundness (ZK proof system, FHE scheme, or confidential VM). +- Signing-convention agreement between banks. Algorithm choice, PKI, and canonicalization (full ISO hash versus reduced settlement tuple) must be jointly specified. +- Cross-chain atomicity under partition. Variants A and B can strand one leg if the two sides sit on different chains without an atomic bridge; variant C mitigates via single-domain execution but introduces bridge risk. +- Intermediate-correspondent exposure. Non-participating intermediaries pass the message unchanged but cannot verify the proof in transit, so they must trust endpoints to catch invalid extensions. +- Regulator key custody. Compromised view keys expose historical audit scope. ## Trade-offs -- Privacy rails (B1/B2) introduce **infra complexity** (shielded circuits or confidential VM) and **key governance**. -- **Signing convention** (algorithm, PKI) must be agreed (full ISO hash vs reduced settlement tuple) for on-chain authorization. -- **Cross-chain atomicity** (if the two legs span different chains) requires **zk-SPV** or **single-domain execution** (B3). -- **Incremental rollout**: `` "can ignore" semantics mean non-participating intermediaries pass messages through unchanged, but they also cannot verify proofs in transit. -- **CROPS context (I2I)**: CR improves to `high` if settlement uses single-chain shielded pool without relayer. OS depends on privacy rail: Railgun (open) vs proprietary FHE coprocessor. SWIFT infrastructure is licensed/proprietary; ISO schema is open. - ---- +- The private rails in variants A and B add infra complexity (shielded circuits or confidential VM) and require key governance. +- Cross-chain atomicity requires zk-SPV-style bridges or single-domain execution. Two-chain designs without an atomic bridge can fail partially. +- Incremental rollout via `` "can ignore" semantics works but limits correspondent-chain visibility until endpoints upgrade. +- Formalizing the extension requires a Change Request to the relevant ISO SEG to register an Extension `MessageDefinition` for proof data as a first-class component; without this, adoption remains bilateral. ## Example -- Bank A issues `pacs.008` “pay 10m EURC from DEUTDEFFXXX → BNPAFRPPXXX”. -- Off-chain: compute `C_msg` from the canonical ISO message. -- **B1:** Wrap EURC into a shielded pool, execute a note-to-note transfer bound to `C_msg`. - **or B2:** Call confidential-token transfer (encrypted state), referencing `C_msg`. - **or B3:** Bridge to a shared privacy L2, do one-tx shielded DvP, bridge out. -- Regulator later audits via view keys / selective disclosure. - ---- +- Bank A issues `pacs.008` to pay 10m EURC from `DEUTDEFFXXX` to `BNPAFRPPXXX`. +- Off-chain, both banks compute `C_msg` from the canonical ISO message. +- Variant A: EURC is wrapped into a shielded pool and a note-to-note transfer bound to `C_msg` executes. +- Variant B: a confidential-token transfer with encrypted state references `C_msg`. +- Variant C: both legs bridge to a shared privacy L2, a single shielded DvP executes referencing `C_msg`, and assets bridge out. +- The supervisor later audits via view keys and selective disclosure. ## See also -- [Pattern: DvP using ERC-7573](./pattern-dvp-erc7573.md): conditional coupling -- [Pattern: Privacy L2](./pattern-privacy-l2s.md): privacy rails +- [ISO 20022 message definitions](https://www.iso20022.org/iso-20022-message-definitions) +- [ISO 20022 `` extension mechanism](https://www.iso20022.org/supplementary_data.page) +- [ERC-7573 (conditional settlement)](https://eips.ethereum.org/EIPS/eip-7573) +- [ERC-3643 (tokenized RWA)](https://eips.ethereum.org/EIPS/eip-3643) diff --git a/patterns/pattern-shielding.md b/patterns/pattern-shielding.md index 555829a..e9bedd2 100644 --- a/patterns/pattern-shielding.md +++ b/patterns/pattern-shielding.md @@ -1,69 +1,109 @@ --- -title: "Pattern: Shielded ERC-20 Transfers" -status: draft -maturity: PoC +title: "Pattern: Shielding" +status: ready +maturity: production +type: standard layer: hybrid -privacy_goal: Confidential ERC-20 transfers hiding balances and metadata with selective disclosure -assumptions: Shielded pool contracts or privacy L2, wallet support for shielded keys -last_reviewed: 2026-01-14 +last_reviewed: 2026-04-22 + works-best-when: - - You need confidential transfer amounts/counterparties. - - Selective disclosure/auditing is required. + - You need confidential transfer amounts and counterparties. + - Selective disclosure or auditing is required. avoid-when: - Transparency is mandated by design. -dependencies: - - ERC-20 - - Optional: ERC-5564 (stealth addresses), ERC-3643 (eligibility gating), [Attestations](pattern-verifiable-attestation.md) for audit + context: both +context_differentiation: + i2i: "Between institutions, both counterparties have legal recourse and KYC-aligned identities. A shielded pool can be permissioned to institutional participants once the anonymity set is large enough to preserve unlinkability within the set. Shielding hides positions from competitors while viewing keys cover audit." + i2u: "User is asymmetric to the operator. The shielded pool's CR must not depend on an operator who can block withdrawals. Forced withdrawal is required to make the privacy guarantee meaningful; without it, CR is effectively `low`." + crops_profile: cr: medium - os: partial - privacy: full - security: medium + o: partial + p: full + s: medium + +crops_context: + cr: "Reaches `high` on L1 permissionless shielded pools where users can deposit and withdraw without a gatekeeper. Drops to `low` on permissioned L2s with operator-controlled exit. Relies on relayer and paymaster for transaction submission, both of which can censor." + o: "Open-source contracts are available; users can fork and run their own relayer. Some L2 deployments are closed or operator-controlled." + p: "Plausible deniability on amounts, sender, and receiver. Metadata (contract-level patterns, IP addresses, gas payer, timing) remains visible and must be covered at the network layer." + s: "Rides on the soundness of the ZK proof system and on-chain state integrity. Operator honesty matters on permissioned deployments." + +post_quantum: + risk: high + vector: "EC-based commitments (Groth16, PLONK/KZG) broken by CRQC; HNDL risk high for encrypted notes." + mitigation: "STARK-based shielded pools with hash commitments. See [Post-Quantum Threats](../domains/post-quantum.md)." + +standards: [ERC-20, ERC-5564, ERC-3643] + +related_patterns: + composes_with: [pattern-stealth-addresses, pattern-erc3643-rwa, pattern-regulatory-disclosure-keys-proofs] + see_also: [pattern-forced-withdrawal, pattern-user-controlled-viewing-keys, pattern-network-anonymity] + +open_source_implementations: + - url: https://github.com/Railgun-Privacy/contract + description: "Railgun shielded pool (L1, production)" + language: "Solidity, Circom" + - url: https://github.com/ethereum/iptf-pocs/tree/master/pocs/private-payment + description: "IPTF PoC (UltraHonk/Noir, research)" + language: "Noir, Solidity" + - url: https://github.com/AztecProtocol/aztec-packages + description: "Aztec Network, privacy L2 with native shielding (production)" + language: "Noir" --- ## Intent -Enable **confidential ERC-20 transfers** by shielding balances and transfer metadata, while still allowing regulators/auditors to verify via selective disclosure (view keys, proofs). +Enable **confidential transfers** by shielding balances, sender, and receiver, while still allowing regulators and auditors to verify via selective disclosure (viewing keys, proofs). The logic generalizes beyond ERC-20 to any transferable asset. + +## Components + +- **Shielded pool contract** stores commitments, the nullifier set, and a ZK verifier. Deployable on L1 or a shielded L2. +- **Hash-based commitments** (e.g. Poseidon) hide note contents; notes represent spendable state. +- **Nullifier set** prevents double-spends by tracking spent notes. +- **Prover and verifier**, with circuit logic authored in a DSL (Noir, Circom, Halo2, Gnark, etc.); the prover runs client-side. +- **Wallet/KMS** manages shielded keys and optional viewing keys. +- **Relayer/paymaster** (optional) for gas abstraction. +- **Stealth addresses** (optional, ERC-5564) for recipient unlinkability. + +## Protocol -## Ingredients +1. [user] Deposit assets into the shielded pool contract. +2. [contract] Store the commitment submitted by the user in the commitment set. +3. [user] Construct a shielded transfer: generate a zero-knowledge proof that (a) nullifiers for spent notes are not already in the nullifier set, (b) commitments for spent notes are members of the commitment set, (c) the sum of output note amounts does not exceed the sum of input note amounts, and (d) the sender owns the spending keys. +4. [relayer] Submit the shielded transaction for gas abstraction (optional). +5. [contract] Verify the proof, add new commitments, and add spent nullifiers. +6. [auditor] Verify a specific transfer via the recipient's viewing key. +7. [user] Withdraw by proving ownership of notes and burning them. -- **Standards**: ERC-20 base; optional ERC-5564 (stealth addresses) -- **Implementations**: - - **L1/L2 contracts** (e.g., Railgun-style shielded pools). - - **Privacy L2/app-chains** (e.g., Aztec, Zama fhEVM, Fhenix) with native shielding. -- **Wallet/KMS**: Management of shielded keys and optional viewing keys. +## Guarantees & threat model -## Protocol (concise) +Guarantees: -1. Deposit ERC-20 tokens into shielded pool contract. -2. Receive private notes/commitments representing the deposit. -3. Execute shielded transfers by spending notes and creating new ones. -4. Generate ZK proof for each transfer (balance validity, no double-spend). -5. Optionally use stealth addresses (ERC-5564) for recipient unlinkability. -6. Provide viewing keys to auditors for selective disclosure. -7. Withdraw by proving ownership of notes and burning them. +- Hides amounts, sender, and receiver from non-participants within the anonymity set. +- Enables scoped disclosures to auditors via viewing keys. +- Anchors state on the underlying chain (L1 or L2) for integrity. -## Guarantees +Threat model: -- Hides amounts + counterparties from non-participants. -- Enables scoped disclosures to auditors. -- Anchors commitments on L1 for integrity. +- Soundness of the ZK proof system. +- Non-censoring sequencer or validator set on shielded L2s. +- Non-compromised relayer and paymaster. The relayer sees raw transaction data (nullifier, commitment, proof) and can link user IPs to shielded activity even though the contents stay hidden. A colluding paymaster can selectively censor. +- Network-layer metadata (timing, gas payer, IP) is out of scope for the shielding layer; combine with network-level anonymity to cover it. ## Trade-offs -- Cost/latency of ZK/FHE proofs. -- Metadata leakage possible (timing, gas payer). -- Tooling immaturity compared to ERC-20. -- **CROPS context (both)**: CR reaches `high` on L1 shielded pools (Railgun) where users can deposit/withdraw permissionlessly. Drops to `low` on permissioned L2s with operator-controlled exit. Relies on relayer and paymaster for transaction submission, both of which can censor. In I2U, the exit path guarantee is critical — without forced withdrawal, CR is effectively `low`. -- **Post-quantum exposure**: underlying ZK proof system may use EC-based commitments (Groth16, PLONK/KZG) broken by CRQC; HNDL risk is high for encrypted notes. Mitigation: STARK-based shielded pools with hash commitments. See [Post-Quantum Threats](../domains/post-quantum.md). +- Cost and latency of zero-knowledge proofs (prover time, calldata/blobspace). +- Metadata leakage at the network layer. +- Gas abstraction is mandatory in practice: paying gas from the user's own EOA links the exit address back to the entry, breaking entry-to-exit unlinkability. A relayer or paymaster is required to break that link. +- Monotonic state growth: commitments accumulate indefinitely, so pool state bloats and proof costs drift up over time. ## Example -- Alice shields USDC into Railgun; transfers to Bob privately; regulator later verifies the transfer via Bob’s viewing key. +- A user shields stablecoins into the pool, transfers them privately to a recipient, and the regulator later verifies the transfer via the recipient's viewing key. ## See also -- Railgun: https://docs.railgun.org/wiki -- Aztec docs: https://docs.aztec.network/ -- Zama fhEVM: https://docs.zama.org/protocol/protocol/overview +- [Railgun](../vendors/railgun.md) +- [Hinkal](../vendors/hinkal.md) +- [Aztec](../vendors/aztec.md) From d7b8740596bfe63c1e02d6b2f292d93cd8479df2 Mon Sep 17 00:00:00 2001 From: Meyanis95 Date: Thu, 23 Apr 2026 16:09:04 +0200 Subject: [PATCH 02/10] fix(patterns): use canonical terminology across batch 1 --- patterns/pattern-co-snark.md | 4 ++-- patterns/pattern-compliance-monitoring.md | 16 ++++++++-------- patterns/pattern-cross-chain-privacy-bridge.md | 4 ++-- patterns/pattern-forced-withdrawal.md | 2 +- patterns/pattern-hybrid-public-private-modes.md | 6 +++--- patterns/pattern-l2-privacy-evaluation.md | 4 ++-- patterns/pattern-modular-privacy-stack.md | 2 +- patterns/pattern-native-account-abstraction.md | 2 +- patterns/pattern-noir-private-contracts.md | 14 +++++++------- .../pattern-origin-locked-confidential-ledger.md | 4 ++-- patterns/pattern-plasma-stateless-privacy.md | 12 ++++++------ patterns/pattern-private-iso20022.md | 8 ++++---- patterns/pattern-shielding.md | 4 ++-- 13 files changed, 41 insertions(+), 41 deletions(-) diff --git a/patterns/pattern-co-snark.md b/patterns/pattern-co-snark.md index dbfe6c7..7f9a5b5 100644 --- a/patterns/pattern-co-snark.md +++ b/patterns/pattern-co-snark.md @@ -7,7 +7,7 @@ layer: hybrid last_reviewed: 2026-04-23 works-best-when: - - A user or institution lacks the compute, memory, or battery to generate a ZK proof client-side and wants to offload the work without disclosing the witness. + - A user or institution lacks the compute, memory, or battery to generate a zero-knowledge proof client-side and wants to offload the work without disclosing the witness. - The delegatee set can be run by independent operators so no single party sees the full witness. avoid-when: - Client-side proving is feasible and low-latency is critical. @@ -50,7 +50,7 @@ open_source_implementations: ## Intent -Offload ZK proof generation to a distributed prover network without revealing the witness. The user secret-shares their witness across several proving nodes; the nodes jointly run an MPC protocol to compute a single SNARK proof; no individual node ever reconstructs the full witness. The resulting proof is identical to one produced client-side and is verified on-chain or off-chain with no changes on the verifier side. +Offload zero-knowledge proof generation to a distributed prover network without revealing the witness. The user secret-shares their witness across several proving nodes; the nodes jointly run an MPC protocol to compute a single SNARK proof; no individual node ever reconstructs the full witness. The resulting proof is identical to one produced client-side and is verified on-chain or off-chain with no changes on the verifier side. This pattern covers **delegated proving for a single prover's witness**. For multi-party joint computation over shared secret inputs (e.g. a consortium ledger), see `pattern-private-shared-state-cosnark`. diff --git a/patterns/pattern-compliance-monitoring.md b/patterns/pattern-compliance-monitoring.md index de4df09..01121c8 100644 --- a/patterns/pattern-compliance-monitoring.md +++ b/patterns/pattern-compliance-monitoring.md @@ -28,12 +28,12 @@ crops_profile: crops_context: cr: "The screening oracle is a single point of censorship by design. Reaches `medium` if replaced with a threshold consensus oracle network that includes appeal routes and cannot unilaterally block transactions." o: "Rule engines are often proprietary and bundled with screening vendors. Improves to `yes` by open-sourcing the rule engine under a copyleft license and making rule updates auditable." - p: "The oracle sees some transaction metadata by design. Reaches `full` when enforced screening uses ZK proofs (prove amount under threshold, prove counterparty not on sanctions list) so the oracle validates attestations without seeing amounts or identities." + p: "The oracle sees some transaction metadata by design. Reaches `full` when enforced screening uses zero-knowledge proofs (prove amount under threshold, prove counterparty not on sanctions list) so the oracle validates attestations without seeing amounts or identities." s: "Rides on a single operator's honesty and availability. Improves to `high` by replacing single-operator trust with threshold KMS and timelocked recovery for rule updates." post_quantum: risk: medium - vector: "Signatures on screening attestations inherit host-chain and oracle signature assumptions. ZK proofs used in privacy-preserving screening inherit their proof system's exposure." + vector: "Signatures on screening attestations inherit host-chain and oracle signature assumptions. zero-knowledge proofs used in privacy-preserving screening inherit their proof system's exposure." mitigation: "Hash-based signatures and STARK-based screening proofs. See [Post-Quantum Threats](../domains/post-quantum.md)." standards: [EAS, ERC-3643] @@ -49,22 +49,22 @@ open_source_implementations: [] Enable institutions to screen private transactions for regulatory compliance (AML, sanctions, fraud) without exposing transaction details to unauthorized parties. Balance privacy preservation with auditability through selective screening approaches and tiered disclosure, so settlement can proceed under compliance controls while counterparty identities and amounts remain shielded from public view. -This is an orchestration pattern that composes primitives (viewing keys, ZK proofs, threshold KMS, attestations) into a compliance workflow. The unique contribution is the rule engine, alert pipeline, and audit trail that hold the workflow together; the underlying disclosure primitives are linked via `related_patterns`. +This is an orchestration pattern that composes primitives (viewing keys, zero-knowledge proofs, threshold KMS, attestations) into a compliance workflow. The unique contribution is the rule engine, alert pipeline, and audit trail that hold the workflow together; the underlying disclosure primitives are linked via `related_patterns`. ## Components - **Compliance oracle or screening service** evaluates transactions against sanctions lists, AML rules, and internal policies. Can be centralized, federated, or threshold-operated. - **Rule engine** stores jurisdiction-specific rules with versioning. Rule updates are logged and auditable. - **Threshold key management** issues and rotates viewing keys distributed to authorized parties, so no single operator can unilaterally decrypt transaction contents. -- **ZK proof verifiers** (optional) validate compliance attestations such as "amount below reporting threshold" or "counterparty not on sanctions list" without revealing the underlying values. +- **zero-knowledge proof verifiers** (optional) validate compliance attestations such as "amount below reporting threshold" or "counterparty not on sanctions list" without revealing the underlying values. - **Alert and case management system** handles flagged transactions through severity tiers with defined response times. - **Audit log** records every screening decision with timestamp, rule version, and decision hash. Typically anchored on-chain via attestations for tamper evidence. ## Protocol -1. [user] Sender constructs a transaction and generates a compliance attestation (viewing key or ZK proof) alongside the encrypted payload. +1. [user] Sender constructs a transaction and generates a compliance attestation (viewing key or zero-knowledge proof) alongside the encrypted payload. 2. [operator] Compliance oracle pre-screens the recipient against sanctions lists and internal policies before the transaction is submitted. -3. [operator] Oracle verifies the transaction against AML rules using the attestation, without seeing the full plaintext when ZK proofs are used. +3. [operator] Oracle verifies the transaction against AML rules using the attestation, without seeing the full plaintext when zero-knowledge proofs are used. 4. [operator] If screening passes, the oracle emits a cleared attestation; if flagged, an alert is generated with severity level. 5. [operator] High-severity alerts trigger a hold and manual review; low-severity cases are logged for batch review. 6. [contract] Cleared transactions settle on the host chain; flagged transactions remain held pending resolution. @@ -81,7 +81,7 @@ Guarantees: Threat model: -- Soundness of any ZK proofs used for screening attestations. +- Soundness of any zero-knowledge proofs used for screening attestations. - Non-colluding oracle operators. A single compromised or coerced operator in a centralized deployment can leak transaction metadata or unilaterally block transactions. - Rule engine integrity. A tampered rule set can allow prohibited transactions or block legitimate ones. - Key management for viewing keys. Compromised keys enable unauthorized decryption of historical transactions. @@ -99,7 +99,7 @@ Threat model: - An institution initiates a large bond purchase on a privacy L2. - The sender's compliance node pre-screens the counterparty against the sanctions list (clear). -- The transaction is submitted with an encrypted amount and a ZK proof that the amount is within the reporting threshold. +- The transaction is submitted with an encrypted amount and a zero-knowledge proof that the amount is within the reporting threshold. - The oracle verifies the proof, checks the counterparty risk score (medium), and clears the transaction. - Settlement executes. The audit log records timestamp, screening version, result, and proof hash. - A monthly report aggregates cleared transactions for the regulatory filing. diff --git a/patterns/pattern-cross-chain-privacy-bridge.md b/patterns/pattern-cross-chain-privacy-bridge.md index d4294c4..41d00f1 100644 --- a/patterns/pattern-cross-chain-privacy-bridge.md +++ b/patterns/pattern-cross-chain-privacy-bridge.md @@ -66,7 +66,7 @@ Move assets between chains while preserving privacy on the destination by mintin 1. [user] Generate a destination note commitment `C = hash(value, recipient_pubkey, randomness)`. The recipient is not revealed on the source chain. 2. [contract] Lock or burn the assets in the source escrow. Emit an event containing the amount, `C`, and a nonce. The lock is public on the source chain. -3. [relayer] Obtain finality evidence for the source lock: operator signature, threshold signature, optimistic claim, ZK proof of source consensus, light-client header, or TEE attestation, depending on the bridge's trust model. +3. [relayer] Obtain finality evidence for the source lock: operator signature, threshold signature, optimistic claim, zero-knowledge proof of source consensus, light-client header, or TEE attestation, depending on the bridge's trust model. 4. [contract] The destination bridge contract verifies the finality evidence and mints a note into the shielded pool with commitment `C`. 5. [user] The recipient spends the note privately within the destination pool using standard shielded-pool semantics (nullifier reveal, proof of membership and ownership). 6. [user] For the return path, burn the shielded note on the destination, prove the burn to the source, and unlock the escrowed assets. The return leg can also be private if the source supports it. @@ -94,7 +94,7 @@ Threat model: ## Trade-offs - Two-phase commit workflow, not instant atomic settlement. Latency depends on source finality and any challenge window. -- Cost scales with the verification mechanism. ZK proofs are expensive to generate; optimistic systems impose challenge delays; custodial designs are cheap but centralized. +- Cost scales with the verification mechanism. zero-knowledge proofs are expensive to generate; optimistic systems impose challenge delays; custodial designs are cheap but centralized. - Reorg handling and cross-domain confusion (wrong chain ID, token mismatch) are recurring failure modes that must be guarded at the contract layer. - Griefing through deposits that are never minted locks funds until timeout. The recovery path must be robust and well-documented. - Key and governance risks: TSS or MPC signer collusion, view-key misuse, and malicious contract upgrades each sit outside the cryptographic trust model and require operational controls. diff --git a/patterns/pattern-forced-withdrawal.md b/patterns/pattern-forced-withdrawal.md index 036aa56..6a1b9e4 100644 --- a/patterns/pattern-forced-withdrawal.md +++ b/patterns/pattern-forced-withdrawal.md @@ -51,7 +51,7 @@ When an L2 sequencer, relayer, or operator becomes unavailable, users need a uni ## Components - **Data availability source** lets the user reconstruct their position. Can be L1 calldata, L1 blobs, an external DA layer, a validium DA committee, or client-side storage. -- **L1 state-root oracle** stores the last verified L2 state root. Validity rollups anchor with a ZK proof; optimistic rollups anchor after a challenge period survives. +- **L1 state-root oracle** stores the last verified L2 state root. Validity rollups anchor with a zero-knowledge proof; optimistic rollups anchor after a challenge period survives. - **Proof verifier contract** accepts Merkle proofs (transparent systems) or zero-knowledge proofs (privacy systems) and checks them against the anchored root. - **Nullifier registry** records completed withdrawals to prevent double-claims. - **Bridge liquidity contract** holds the locked deposits that forced exits draw from; no new funds are created. diff --git a/patterns/pattern-hybrid-public-private-modes.md b/patterns/pattern-hybrid-public-private-modes.md index f5b7d2e..528de7d 100644 --- a/patterns/pattern-hybrid-public-private-modes.md +++ b/patterns/pattern-hybrid-public-private-modes.md @@ -33,7 +33,7 @@ crops_context: post_quantum: risk: high - vector: "Any private leg using EC-based ZK proofs (Groth16, PLONK over BN254) is broken by a CRQC. HNDL risk is high for encrypted view-key material shared between counterparties." + vector: "Any private leg using EC-based zero-knowledge proofs (Groth16, PLONK over BN254) is broken by a CRQC. HNDL risk is high for encrypted view-key material shared between counterparties." mitigation: "Route private legs through STARK-based shielded pools with hash commitments. Rotate long-lived view keys and prefer post-quantum signatures for cross-mode settlement oracles." standards: [ERC-7573, ERC-3643, ERC-5564] @@ -62,7 +62,7 @@ Allow institutions to select public or private execution mode on a per-transacti 1. [operator] Configure policy rules covering counterparty whitelist, asset thresholds, and jurisdictional routing. 2. [operator] When a trade arrives, the policy engine evaluates rules and assigns each leg to public or private execution. 3. [user] Prepare assets in the appropriate environment. Public legs stay on the transparent chain; private legs are shielded into a private pool or bridged to a privacy L2. -4. [contract] Execute legs in parallel or sequence. Each leg runs in its assigned environment; private legs generate ZK proofs or use FHE, public legs execute standard transfers. +4. [contract] Execute legs in parallel or sequence. Each leg runs in its assigned environment; private legs generate zero-knowledge proofs or use FHE, public legs execute standard transfers. 5. [contract] Coordinate cross-mode settlement via ERC-7573 outcome keys or commit-and-prove so both legs settle atomically or both fail. 6. [regulator] Receive disclosure artifacts from private legs: view keys or ZK attestations delivered per policy. 7. [operator] Finalize and reconcile. Internal systems map public chain events to private proofs for the audit trail. @@ -87,7 +87,7 @@ Threat model: - Metadata leakage. Mode selection itself reveals information: choosing private signals sensitivity. Timing correlation between legs may link transactions. - Operational complexity. Dual infrastructure requires expertise in both transparent and privacy systems; failure modes multiply. -- Cost asymmetry. Private execution incurs ZK proof generation costs; public execution is cheaper but exposes data. Mixed-mode trades pay both overheads. +- Cost asymmetry. Private execution incurs zero-knowledge proof generation costs; public execution is cheaper but exposes data. Mixed-mode trades pay both overheads. - Tooling maturity. Cross-mode settlement is less battle-tested than single-environment flows. Limited production deployments exist. - Policy drift risk. Rules must stay synchronized across systems; misconfigurations can route sensitive transactions to public mode. diff --git a/patterns/pattern-l2-privacy-evaluation.md b/patterns/pattern-l2-privacy-evaluation.md index d528ee2..f28ed4e 100644 --- a/patterns/pattern-l2-privacy-evaluation.md +++ b/patterns/pattern-l2-privacy-evaluation.md @@ -39,7 +39,7 @@ open_source_implementations: ## Intent -Give institutions a vendor-neutral, sourced methodology for comparing privacy-preserving L2 solutions across performance and cost, privacy and data availability, and security and governance. The framework defines a common workload so that self-reported metrics can be placed next to independent benchmarks on the same axes. +Give institutions a vendor-neutral, sourced methodology for comparing privacy-preserving L2 solutions across performance and cost, privacy and Data Availability, and security and governance. The framework defines a common workload so that self-reported metrics can be placed next to independent benchmarks on the same axes. > Note: this card is an evaluation framework, not a reusable privacy primitive. `pattern-privacy-l2s` is the actual L2 pattern; this one documents how to compare privacy L2s. Candidate for relocation to `approaches/` or a methodology section in a follow-up. @@ -71,7 +71,7 @@ Give institutions a vendor-neutral, sourced methodology for comparing privacy-pr | **Finality time** | `Soft Finality` (L2 inclusion), `Hard Finality` (L1 commitment + proof), `Challenge Period` | | **Transaction retrieval** | Sync mechanism (`Trial decryption`, `Detection Keys`, `Server-side filtering`) and sync speed | -### 2. Privacy and data availability +### 2. Privacy and Data Availability | Metric | Discrete metrics | | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------ | diff --git a/patterns/pattern-modular-privacy-stack.md b/patterns/pattern-modular-privacy-stack.md index f10e382..e8205fb 100644 --- a/patterns/pattern-modular-privacy-stack.md +++ b/patterns/pattern-modular-privacy-stack.md @@ -68,7 +68,7 @@ Compose a privacy architecture from four distinct layers: Data, Execution, Settl ## Components - **Data layer** stores and retrieves encrypted payloads. Options include off-chain encrypted storage, data-availability layers, L1 blob data, and content-addressed networks with encryption. -- **Execution layer** runs private computation. Options include zero-knowledge execution environments, fully homomorphic encryption, and trusted execution environments. +- **Execution layer** runs private computation. Options include zero-knowledge execution environments, Fully Homomorphic Encryption, and trusted execution environments. - **Settlement layer** provides finality and atomicity. Options include L1, validity-proof rollups, optimistic rollups, and cross-chain atomic swap protocols. - **Disclosure layer** exposes scoped access for audit and compliance. Options include viewing keys, zero-knowledge proofs of properties, threshold key management, and on-chain attestations. - **Interface contracts** define what each layer consumes and emits: encrypted reads and writes for Data, state transitions for Execution, proofs and signed transactions for Settlement, and disclosure artifacts for Disclosure. diff --git a/patterns/pattern-native-account-abstraction.md b/patterns/pattern-native-account-abstraction.md index 7e15c1b..cf6deb3 100644 --- a/patterns/pattern-native-account-abstraction.md +++ b/patterns/pattern-native-account-abstraction.md @@ -55,7 +55,7 @@ Make every Ethereum account natively programmable by replacing the hardcoded ECD ## Components - **Frame transaction**: ordered list of frames per transaction. Each frame specifies a mode (`VERIFY`, `SENDER`, `DEFAULT`), target address, gas limit, and data. Frames execute sequentially with independent gas metering. -- **Account validation code**: per-account logic executed inside `VERIFY` frames. It can validate any signature scheme (ECDSA, ML-DSA, SLH-DSA, passkeys, multisig) or any ZK proof. +- **Account validation code**: per-account logic executed inside `VERIFY` frames. It can validate any signature scheme (ECDSA, ML-DSA, SLH-DSA, passkeys, multisig) or any zero-knowledge proof. - **`APPROVE` opcode**: called inside `VERIFY` frames to authorise execution (`0x0`), payment (`0x1`), or both (`0x2`). Payment approval decides who pays gas at runtime, decoupling authorisation of execution from gas payment. - **Regular mempool**: carries frame transactions alongside legacy transactions. No separate mempool or bundler network. diff --git a/patterns/pattern-noir-private-contracts.md b/patterns/pattern-noir-private-contracts.md index da6ce97..7ea268b 100644 --- a/patterns/pattern-noir-private-contracts.md +++ b/patterns/pattern-noir-private-contracts.md @@ -29,8 +29,8 @@ crops_profile: crops_context: cr: "Medium while sequencer election is centralised. Reaches `high` once sequencing becomes permissionless." o: "Contracts, DSL, and prover backend are open-source. Client-side proving lets anyone run the stack locally." - p: "Private state, private function inputs, and private logs are hidden from sequencers and observers. Public state and function calls remain transparent by design. Selective disclosure is supported through viewing keys or ZK proofs." - s: "Rides on the soundness of the ZK proof system and the validity-proof pipeline that settles to L1. Could reach `high` by replacing admin keys with DAO-governed upgrade paths." + p: "Private state, private function inputs, and private logs are hidden from sequencers and observers. Public state and function calls remain transparent by design. Selective disclosure is supported through viewing keys or zero-knowledge proofs." + s: "Rides on the soundness of the zero-knowledge proof system and the validity-proof pipeline that settles to L1. Could reach `high` by replacing admin keys with DAO-governed upgrade paths." post_quantum: risk: high @@ -57,7 +57,7 @@ open_source_implementations: ## Intent -Give developers a privacy-focused DSL to write smart contracts that blend public logic with confidential private computation in the same contract. Private functions execute client-side and produce ZK proofs; public functions execute on the sequencer transparently. Private and public state can be composed in a single application. +Give developers a privacy-focused DSL to write smart contracts that blend public logic with confidential private computation in the same contract. Private functions execute client-side and produce zero-knowledge proofs; public functions execute on the sequencer transparently. Private and public state can be composed in a single application. ## Components @@ -71,7 +71,7 @@ Give developers a privacy-focused DSL to write smart contracts that blend public 1. [user] Write a contract in the DSL with private and public functions. Compile to the circuit intermediate representation. 2. [user] Deploy the contract to the privacy rollup. -3. [user] Execute a private function locally, generating a ZK proof of correct execution over private inputs and state. +3. [user] Execute a private function locally, generating a zero-knowledge proof of correct execution over private inputs and state. 4. [user] Submit the proof and any public inputs to the sequencer. 5. [sequencer] Verify the proof, update the encrypted private state, and apply any public state changes. 6. [sequencer] Batch transactions periodically and settle to Ethereum L1 with a validity proof. @@ -84,12 +84,12 @@ Guarantees: - Private state stays encrypted and hidden from sequencers and observers. Private function inputs and outputs are not revealed on-chain. - Public state, public function calls, and contract source remain transparent and auditable. - Validity proofs ensure state transitions follow contract rules; L1 finality comes via periodic batch settlement. -- Selective disclosure to auditors is possible through viewing keys or targeted ZK proofs. +- Selective disclosure to auditors is possible through viewing keys or targeted zero-knowledge proofs. - Encrypted event logs enable note discovery without leaking content to the public. Threat model: -- Soundness of the ZK proof system and the circuit compiler. +- Soundness of the zero-knowledge proof system and the circuit compiler. - Non-censoring sequencer set. A censoring sequencer can stall user transactions; forced-withdrawal paths to L1 are required to bound this. - Client-side key management: compromise of local proving or viewing keys exposes the user's private state. - Note discovery relies on scanning; a malicious or buggy indexer can cause notes to be missed, though funds are not lost. @@ -104,7 +104,7 @@ Threat model: ## Example - A corporate treasury shields stablecoins into a private contract, receiving private notes. -- It pays a supplier privately; the client generates a ZK proof of sufficient balance and note ownership. +- It pays a supplier privately; the client generates a zero-knowledge proof of sufficient balance and note ownership. - The transaction emits an encrypted log; only the supplier can decrypt and discover the payment. - The rollup verifies the proof, updates balances in encrypted form, and includes the transaction in a batch settled to L1. Observers see that a valid transaction occurred but not amounts or parties. - The supplier can then spend the received notes privately; the treasury's remaining position stays hidden. diff --git a/patterns/pattern-origin-locked-confidential-ledger.md b/patterns/pattern-origin-locked-confidential-ledger.md index d1dda33..ed40b6e 100644 --- a/patterns/pattern-origin-locked-confidential-ledger.md +++ b/patterns/pattern-origin-locked-confidential-ledger.md @@ -69,10 +69,10 @@ Provide confidential balances and transfers for an existing ERC-20 on an origin 1. [user] Deposit ERC-20 into the origin locking contract. 2. [contract] Emit a cross-chain message crediting the user's encrypted balance on the confidentiality layer. -3. [user] Submit a confidential transfer: ciphertext amount, ZK proof of correctness, and recipient identifier. +3. [user] Submit a confidential transfer: ciphertext amount, zero-knowledge proof of correctness, and recipient identifier. 4. [relayer] Carry the transfer packet to the confidentiality layer. 5. [operator] The confidentiality layer verifies the proof and homomorphically updates encrypted balances of sender and receiver. -6. [user] Submit a withdrawal request with a ZK proof of sufficient encrypted balance. +6. [user] Submit a withdrawal request with a zero-knowledge proof of sufficient encrypted balance. 7. [contract] On receipt of the debit acknowledgement, unlock the corresponding ERC-20 to the user on the origin chain. 8. [auditor] Under a deployment-defined policy, receive a scoped decryption key or proof for a specific account or transaction; access events are logged if required. diff --git a/patterns/pattern-plasma-stateless-privacy.md b/patterns/pattern-plasma-stateless-privacy.md index 29bf14c..c98b079 100644 --- a/patterns/pattern-plasma-stateless-privacy.md +++ b/patterns/pattern-plasma-stateless-privacy.md @@ -19,7 +19,7 @@ avoid-when: context: both context_differentiation: i2i: "Institutions already run reliable off-chain infrastructure, so data custody is a known cost. The value of stateless Plasma at I2I scale is minimal L1 footprint and no shared pool state, which avoids revealing portfolio sizes via gas patterns or commitment volumes. Forced exits via the L1 anchor let either counterparty settle unilaterally if the block producer stalls." - i2u: "End users cannot reliably custody their own data long-term. This pattern is only safe for user-facing deployments when paired with redundant self-hosted or trust-minimized data availability. Forced withdrawal is critical: the L1 anchor must accept unilateral exit proofs so a censoring block producer cannot freeze user funds." + i2u: "End users cannot reliably custody their own data long-term. This pattern is only safe for user-facing deployments when paired with redundant self-hosted or trust-minimized Data Availability. Forced withdrawal is critical: the L1 anchor must accept unilateral exit proofs so a censoring block producer cannot freeze user funds." crops_profile: cr: medium @@ -31,7 +31,7 @@ crops_context: cr: "Reaches `high` when the L1 anchor enforces forced exits via cryptographic proof-based withdrawals that bypass block producer liveness. Drops to `low` if the only withdrawal path depends on a single block producer's cooperation." o: "Reaches `yes` when the block producer software, circuit code, and client software are all published under permissive or copyleft licenses in forkable repositories." p: "Transaction amounts, sender, and receiver are hidden from chain observers; only block commitments and per-block sender lists are visible on L1. Network-layer metadata (IP, timing against the block producer) remains out of scope." - s: "Rides on L1 security for deposit and exit, on the ZK proof system for transfer validity, and on the user's ability to preserve their own data. Reaches `high` with post-quantum hash-based ZK primitives and robust self-hosted data availability." + s: "Rides on L1 security for deposit and exit, on the zero-knowledge proof system for transfer validity, and on the user's ability to preserve their own data. Reaches `high` with post-quantum hash-based ZK primitives and robust self-hosted Data Availability." post_quantum: risk: medium @@ -66,13 +66,13 @@ Use a stateless Plasma architecture to enable private token transfers where tran - **L1 anchor contract**: stores block commitments (Merkle roots of transaction hashes) and handles deposits, withdrawals, and forced exits. - **Block producer**: aggregates transactions, collects signatures, and posts the block commitment to L1. Stateless with respect to transaction contents. - **Client-side prover**: users generate ZK balance and transfer proofs locally (e.g., recursive FRI-based proofs). -- **User-held data availability**: users custody their own note and transfer history. Optional trust-minimized DA layer for redundancy. +- **User-held Data Availability**: users custody their own note and transfer history. Optional trust-minimized DA layer for redundancy. - **Forced-exit mechanism**: L1 contract accepts exit proofs independently of the block producer, bypassing liveness failure. ## Protocol 1. [user] Deposit an ERC-20 to the L1 anchor contract, which credits a balance commitment on L2. -2. [user] Generate a ZK proof of a valid transfer client-side; send the proof and an encrypted note to the recipient. +2. [user] Generate a zero-knowledge proof of a valid transfer client-side; send the proof and an encrypted note to the recipient. 3. [operator] The block producer collects signatures and proofs, builds a Merkle tree of the new state, and verifies correctness. 4. [operator] The block producer posts the state root to L1 as a minimal block commitment. 5. [user] The recipient stores the received note locally and can spend it in future transactions. @@ -84,13 +84,13 @@ Use a stateless Plasma architecture to enable private token transfers where tran Guarantees: - Transaction amounts, sender, and receiver are hidden from chain observers; only commitments and per-block sender lists are visible. -- ZK proofs ensure no double-spend or inflation without revealing transaction details. +- zero-knowledge proofs ensure no double-spend or inflation without revealing transaction details. - Users control their own data; no operator can freeze specific balances if forced exit is implemented. - Funds are secured by L1; users can always exit with a valid proof. Threat model: -- Soundness of the ZK proof system. +- Soundness of the zero-knowledge proof system. - Correct implementation of the L1 anchor, especially the forced-exit path. - User data loss. A user who loses their local transaction history loses access to their funds; there is no protocol-level recovery. - Block producer liveness. A stalled producer halts new transactions; users can still exit unilaterally with their own proofs. diff --git a/patterns/pattern-private-iso20022.md b/patterns/pattern-private-iso20022.md index 7988dc7..82433bc 100644 --- a/patterns/pattern-private-iso20022.md +++ b/patterns/pattern-private-iso20022.md @@ -27,11 +27,11 @@ crops_context: cr: "Reaches `high` when settlement runs on a single-chain shielded pool without a trusted relayer or gatekeeper. Drops to `low` when the private rail is operator-controlled or depends on a proprietary coprocessor with no open submission path." o: "ISO 20022 schemas are open and widely adopted. SWIFT infrastructure is licensed and proprietary. The settlement rail determines overall openness: an open shielded pool improves the score, a proprietary FHE coprocessor degrades it. Reaches `yes` only when every component, including the ISO extension carriers and the settlement rail, is open-source." p: "Cash-leg amounts and counterparties are hidden on-chain. The ISO instruction layer is off-chain and covered by existing bank-to-bank confidentiality practice. Metadata at intermediaries (correspondent banks that pass the message without understanding the extension) may still leak timing or existence." - s: "Rides on the settlement rail's cryptography (ZK proofs, FHE, threshold keys) and on signing conventions agreed between banks. Reaches `high` when signing algorithms, PKI, and the ISO extension registration are formally published and jointly governed." + s: "Rides on the settlement rail's cryptography (zero-knowledge proofs, FHE, threshold keys) and on signing conventions agreed between banks. Reaches `high` when signing algorithms, PKI, and the ISO extension registration are formally published and jointly governed." post_quantum: risk: high - vector: "Cash-leg settlement rail typically uses EC-based ZK proofs (Groth16, PLONK/KZG) or pairing-based threshold encryption, all broken by CRQC. HNDL risk is high because correspondent-banking payloads are archived for years." + vector: "Cash-leg settlement rail typically uses EC-based zero-knowledge proofs (Groth16, PLONK/KZG) or pairing-based threshold encryption, all broken by CRQC. HNDL risk is high because correspondent-banking payloads are archived for years." mitigation: "Migrate the settlement rail to STARK-based shielded pools with hash commitments; use lattice-based threshold encryption for any encrypted message envelopes." visibility: @@ -76,7 +76,7 @@ The pattern admits three variants for the cash leg. They share steps 1 to 3 and 6. [contract] Variant C: both cash legs are temporarily bridged to a shared privacy L2. A single shielded DvP or PvP transaction referencing `C_msg` executes, then assets bridge back to their origin chains. 7. [regulator] The supervisor holds view keys for scoped audits (amounts, parties, routes as needed) and can decrypt selected fields or inspect shielded transfers. -The commitment and any ZK proof can be embedded in the ISO message using ``, with `` pointing to the extended element. ISO 20022's "can ignore" semantics mean intermediaries that do not support the extension process the message normally, while endpoints that understand it verify the proof. +The commitment and any zero-knowledge proof can be embedded in the ISO message using ``, with `` pointing to the extended element. ISO 20022's "can ignore" semantics mean intermediaries that do not support the extension process the message normally, while endpoints that understand it verify the proof. ## Guarantees & threat model @@ -89,7 +89,7 @@ Guarantees: Threat model: -- Settlement rail soundness (ZK proof system, FHE scheme, or confidential VM). +- Settlement rail soundness (zero-knowledge proof system, FHE scheme, or confidential VM). - Signing-convention agreement between banks. Algorithm choice, PKI, and canonicalization (full ISO hash versus reduced settlement tuple) must be jointly specified. - Cross-chain atomicity under partition. Variants A and B can strand one leg if the two sides sit on different chains without an atomic bridge; variant C mitigates via single-domain execution but introduces bridge risk. - Intermediate-correspondent exposure. Non-participating intermediaries pass the message unchanged but cannot verify the proof in transit, so they must trust endpoints to catch invalid extensions. diff --git a/patterns/pattern-shielding.md b/patterns/pattern-shielding.md index e9bedd2..c74e637 100644 --- a/patterns/pattern-shielding.md +++ b/patterns/pattern-shielding.md @@ -27,7 +27,7 @@ crops_context: cr: "Reaches `high` on L1 permissionless shielded pools where users can deposit and withdraw without a gatekeeper. Drops to `low` on permissioned L2s with operator-controlled exit. Relies on relayer and paymaster for transaction submission, both of which can censor." o: "Open-source contracts are available; users can fork and run their own relayer. Some L2 deployments are closed or operator-controlled." p: "Plausible deniability on amounts, sender, and receiver. Metadata (contract-level patterns, IP addresses, gas payer, timing) remains visible and must be covered at the network layer." - s: "Rides on the soundness of the ZK proof system and on-chain state integrity. Operator honesty matters on permissioned deployments." + s: "Rides on the soundness of the zero-knowledge proof system and on-chain state integrity. Operator honesty matters on permissioned deployments." post_quantum: risk: high @@ -86,7 +86,7 @@ Guarantees: Threat model: -- Soundness of the ZK proof system. +- Soundness of the zero-knowledge proof system. - Non-censoring sequencer or validator set on shielded L2s. - Non-compromised relayer and paymaster. The relayer sees raw transaction data (nullifier, commitment, proof) and can link user IPs to shielded activity even though the contents stay hidden. A colluding paymaster can selectively censor. - Network-layer metadata (timing, gas payer, IP) is out of scope for the shielding layer; combine with network-level anonymity to cover it. From 8c9523dea4656661c33b2a44261eb146323e2f9c Mon Sep 17 00:00:00 2001 From: Meyanis95 Date: Thu, 23 Apr 2026 16:41:42 +0200 Subject: [PATCH 03/10] style(patterns): remove bold emphasis across batch 1 cards --- patterns/pattern-co-snark.md | 12 ++--- patterns/pattern-commit-and-prove.md | 10 ++-- patterns/pattern-compliance-monitoring.md | 12 ++--- .../pattern-cross-chain-privacy-bridge.md | 20 +++---- ...pattern-crypto-registry-bridge-ewpg-eas.md | 10 ++-- patterns/pattern-dvp-erc7573.md | 24 ++++----- patterns/pattern-eil.md | 12 ++--- patterns/pattern-erc3643-rwa.md | 12 ++--- patterns/pattern-focil-eip7805.md | 10 ++-- patterns/pattern-forced-withdrawal.md | 22 ++++---- .../pattern-hybrid-public-private-modes.md | 12 ++--- patterns/pattern-icma-bdt-data-model.md | 10 ++-- patterns/pattern-l2-privacy-evaluation.md | 54 +++++++++---------- patterns/pattern-modular-privacy-stack.md | 12 ++--- patterns/pattern-mpc-custody.md | 14 ++--- .../pattern-native-account-abstraction.md | 8 +-- patterns/pattern-network-anonymity.md | 6 +-- patterns/pattern-noir-private-contracts.md | 10 ++-- patterns/pattern-oif.md | 10 ++-- patterns/pattern-onion-routing.md | 8 +-- ...ttern-origin-locked-confidential-ledger.md | 12 ++--- ...rn-permissioned-ledger-interoperability.md | 10 ++-- patterns/pattern-permissionless-spend-auth.md | 10 ++-- patterns/pattern-plasma-stateless-privacy.md | 10 ++-- .../pattern-pretrade-privacy-encryption.md | 10 ++-- patterns/pattern-privacy-l2s.md | 10 ++-- patterns/pattern-private-iso20022.md | 12 ++--- patterns/pattern-shielding.md | 16 +++--- 28 files changed, 189 insertions(+), 189 deletions(-) diff --git a/patterns/pattern-co-snark.md b/patterns/pattern-co-snark.md index 7f9a5b5..5cc9e6e 100644 --- a/patterns/pattern-co-snark.md +++ b/patterns/pattern-co-snark.md @@ -52,15 +52,15 @@ open_source_implementations: Offload zero-knowledge proof generation to a distributed prover network without revealing the witness. The user secret-shares their witness across several proving nodes; the nodes jointly run an MPC protocol to compute a single SNARK proof; no individual node ever reconstructs the full witness. The resulting proof is identical to one produced client-side and is verified on-chain or off-chain with no changes on the verifier side. -This pattern covers **delegated proving for a single prover's witness**. For multi-party joint computation over shared secret inputs (e.g. a consortium ledger), see `pattern-private-shared-state-cosnark`. +This pattern covers delegated proving for a single prover's witness. For multi-party joint computation over shared secret inputs (e.g. a consortium ledger), see `pattern-private-shared-state-cosnark`. ## Components -- **User or application** holds the witness and wants a proof generated without exposing the witness. -- **Share-distribution layer** splits the witness using secret-sharing (additive or Shamir) and routes shares to proving nodes. -- **Distributed prover network** runs the MPC protocol to jointly compute the SNARK. Each node sees only its share. -- **Coordinator** sequences MPC rounds and assembles the final proof. Can be one of the proving nodes or a separate role. -- **Verifier** checks the final proof exactly as it would check a client-side SNARK. No changes on the verification side. +- User or application holds the witness and wants a proof generated without exposing the witness. +- Share-distribution layer splits the witness using secret-sharing (additive or Shamir) and routes shares to proving nodes. +- Distributed prover network runs the MPC protocol to jointly compute the SNARK. Each node sees only its share. +- Coordinator sequences MPC rounds and assembles the final proof. Can be one of the proving nodes or a separate role. +- Verifier checks the final proof exactly as it would check a client-side SNARK. No changes on the verification side. ## Protocol diff --git a/patterns/pattern-commit-and-prove.md b/patterns/pattern-commit-and-prove.md index b257a84..bdec037 100644 --- a/patterns/pattern-commit-and-prove.md +++ b/patterns/pattern-commit-and-prove.md @@ -50,11 +50,11 @@ Coordinate a cross-chain settlement by having both parties post commitments to a ## Components -- **Commitment scheme** (hash-based or Pedersen) binds the shared witness `w` to a public value `C` that both parties post. -- **Per-chain settlement contracts** accept a settlement transaction that references `C` and verifies local conditions (asset transfer, payment). -- **Coordination layer** (off-chain) holds the pre-image `w`, sequences the two legs, and drives retry logic. -- **Timeout and refund paths** on each chain allow a counterparty to reclaim funds if the other leg never posts within a deadline. -- **Attestation log** (optional) records the commitments and settlement events for later audit. +- Commitment scheme (hash-based or Pedersen) binds the shared witness `w` to a public value `C` that both parties post. +- Per-chain settlement contracts accept a settlement transaction that references `C` and verifies local conditions (asset transfer, payment). +- Coordination layer (off-chain) holds the pre-image `w`, sequences the two legs, and drives retry logic. +- Timeout and refund paths on each chain allow a counterparty to reclaim funds if the other leg never posts within a deadline. +- Attestation log (optional) records the commitments and settlement events for later audit. ## Protocol diff --git a/patterns/pattern-compliance-monitoring.md b/patterns/pattern-compliance-monitoring.md index 01121c8..be65fd5 100644 --- a/patterns/pattern-compliance-monitoring.md +++ b/patterns/pattern-compliance-monitoring.md @@ -53,12 +53,12 @@ This is an orchestration pattern that composes primitives (viewing keys, zero-kn ## Components -- **Compliance oracle or screening service** evaluates transactions against sanctions lists, AML rules, and internal policies. Can be centralized, federated, or threshold-operated. -- **Rule engine** stores jurisdiction-specific rules with versioning. Rule updates are logged and auditable. -- **Threshold key management** issues and rotates viewing keys distributed to authorized parties, so no single operator can unilaterally decrypt transaction contents. -- **zero-knowledge proof verifiers** (optional) validate compliance attestations such as "amount below reporting threshold" or "counterparty not on sanctions list" without revealing the underlying values. -- **Alert and case management system** handles flagged transactions through severity tiers with defined response times. -- **Audit log** records every screening decision with timestamp, rule version, and decision hash. Typically anchored on-chain via attestations for tamper evidence. +- Compliance oracle or screening service evaluates transactions against sanctions lists, AML rules, and internal policies. Can be centralized, federated, or threshold-operated. +- Rule engine stores jurisdiction-specific rules with versioning. Rule updates are logged and auditable. +- Threshold key management issues and rotates viewing keys distributed to authorized parties, so no single operator can unilaterally decrypt transaction contents. +- zero-knowledge proof verifiers (optional) validate compliance attestations such as "amount below reporting threshold" or "counterparty not on sanctions list" without revealing the underlying values. +- Alert and case management system handles flagged transactions through severity tiers with defined response times. +- Audit log records every screening decision with timestamp, rule version, and decision hash. Typically anchored on-chain via attestations for tamper evidence. ## Protocol diff --git a/patterns/pattern-cross-chain-privacy-bridge.md b/patterns/pattern-cross-chain-privacy-bridge.md index 41d00f1..0337218 100644 --- a/patterns/pattern-cross-chain-privacy-bridge.md +++ b/patterns/pattern-cross-chain-privacy-bridge.md @@ -55,12 +55,12 @@ Move assets between chains while preserving privacy on the destination by mintin ## Components -- **Source escrow contract** locks assets on forward bridging or burns them on return. Emits an event carrying the destination commitment. -- **Destination privacy primitive** is a shielded pool with commitments and nullifiers. The bridge mints a note into this pool rather than transferring a transparent token. -- **Cross-domain message and verification mechanism** carries finality evidence from source to destination. Options include operator signatures, MPC or threshold signatures, optimistic claims with challenge windows, ZK succinct proofs of source consensus (zk-SPV), light clients, or TEE-attested enclaves. -- **Relayer infrastructure** submits finality proofs on the destination without linking the depositor. Fee model matters: if the depositor pays the relayer directly from a known address, the linkage is reintroduced. -- **Optional compliance hooks** include viewing keys for auditors, screening gates, and deposit limits. -- **Timeout and recovery path** on the source escrow allows the depositor to reclaim funds if the destination mint never completes. +- Source escrow contract locks assets on forward bridging or burns them on return. Emits an event carrying the destination commitment. +- Destination privacy primitive is a shielded pool with commitments and nullifiers. The bridge mints a note into this pool rather than transferring a transparent token. +- Cross-domain message and verification mechanism carries finality evidence from source to destination. Options include operator signatures, MPC or threshold signatures, optimistic claims with challenge windows, ZK succinct proofs of source consensus (zk-SPV), light clients, or TEE-attested enclaves. +- Relayer infrastructure submits finality proofs on the destination without linking the depositor. Fee model matters: if the depositor pays the relayer directly from a known address, the linkage is reintroduced. +- Optional compliance hooks include viewing keys for auditors, screening gates, and deposit limits. +- Timeout and recovery path on the source escrow allows the depositor to reclaim funds if the destination mint never completes. ## Protocol @@ -110,10 +110,10 @@ Threat model: ## Variants -- **Pre-bridge mixing**: Deposit through a source-chain shielded pool first, then bridge. Achieves full sender privacy at the cost of additional latency. -- **Hub-and-spoke**: Use L1 as a verification hub; multiple L2s prove deposits via the L1 bridge contract. -- **Privacy-to-privacy**: Both source and destination have shielded pools. Maximum privacy but verification is more complex. -- **Asymmetric**: Only one direction is private (for example, public L1 to private L2). +- Pre-bridge mixing: Deposit through a source-chain shielded pool first, then bridge. Achieves full sender privacy at the cost of additional latency. +- Hub-and-spoke: Use L1 as a verification hub; multiple L2s prove deposits via the L1 bridge contract. +- Privacy-to-privacy: Both source and destination have shielded pools. Maximum privacy but verification is more complex. +- Asymmetric: Only one direction is private (for example, public L1 to private L2). ## See also diff --git a/patterns/pattern-crypto-registry-bridge-ewpg-eas.md b/patterns/pattern-crypto-registry-bridge-ewpg-eas.md index 47218aa..e008151 100644 --- a/patterns/pattern-crypto-registry-bridge-ewpg-eas.md +++ b/patterns/pattern-crypto-registry-bridge-ewpg-eas.md @@ -45,11 +45,11 @@ Operate with a licensed crypto-register today while mirroring key legal facts (i ## Components -- **Licensed crypto-register** under eWpG holds the legal records, PII, and signed notarial documents off-chain. It is the sole source of legal truth. -- **Registrar API integration layer** exposes signed records for each legal event (issuance, transfer, lien) to downstream systems. -- **On-chain attestation schema** defines the structure of mirrored facts: event type, record hash, registrar identifier, timestamp. PII never appears on-chain. -- **Middleware attester** reads the registrar's signed records, computes the hash, and posts an attestation on-chain under the schema. -- **Reconciliation and audit tooling** matches the on-chain anchor to the off-chain registrar record and flags drift. +- Licensed crypto-register under eWpG holds the legal records, PII, and signed notarial documents off-chain. It is the sole source of legal truth. +- Registrar API integration layer exposes signed records for each legal event (issuance, transfer, lien) to downstream systems. +- On-chain attestation schema defines the structure of mirrored facts: event type, record hash, registrar identifier, timestamp. PII never appears on-chain. +- Middleware attester reads the registrar's signed records, computes the hash, and posts an attestation on-chain under the schema. +- Reconciliation and audit tooling matches the on-chain anchor to the off-chain registrar record and flags drift. ## Protocol diff --git a/patterns/pattern-dvp-erc7573.md b/patterns/pattern-dvp-erc7573.md index 46b02b0..3e58253 100644 --- a/patterns/pattern-dvp-erc7573.md +++ b/patterns/pattern-dvp-erc7573.md @@ -48,18 +48,18 @@ Enable atomic Delivery-versus-Payment across two networks so that either the ass In this pattern: -- **asset leg** is the tokenized security or collateral being delivered. -- **cash leg** is the token used for payment, such as a stablecoin or tokenized deposit. -- **decryption oracle** is a service on the payment network that, for each trade, decrypts one of two outcome keys based on the actual payment result; the asset contract then uses that key to decide whether to deliver or reclaim. +- asset leg is the tokenized security or collateral being delivered. +- cash leg is the token used for payment, such as a stablecoin or tokenized deposit. +- decryption oracle is a service on the payment network that, for each trade, decrypts one of two outcome keys based on the actual payment result; the asset contract then uses that key to decide whether to deliver or reclaim. ## Components -- **Locking contract on the asset network** registers the hashed outcome keys per trade identifier and gates delivery of the locked asset. -- **Decryption contract on the payment network** holds the encrypted outcome keys and calls the oracle after observing the payment result. -- **Decryption oracle** is a single or multi-operator service that decrypts the outcome key matching the actual payment result. Stateless by design. -- **Off-chain trade negotiation layer** assigns a shared trade identifier, creates and distributes two outcome keys per trade (success and failure), and holds them off-chain. -- **Oracle proxy and callback contracts** bridge the decryption contract and the oracle per the ERC-7573 interface. -- **Monitoring and logging infrastructure** watches both networks for event correlation and reconciles trade state. +- Locking contract on the asset network registers the hashed outcome keys per trade identifier and gates delivery of the locked asset. +- Decryption contract on the payment network holds the encrypted outcome keys and calls the oracle after observing the payment result. +- Decryption oracle is a single or multi-operator service that decrypts the outcome key matching the actual payment result. Stateless by design. +- Off-chain trade negotiation layer assigns a shared trade identifier, creates and distributes two outcome keys per trade (success and failure), and holds them off-chain. +- Oracle proxy and callback contracts bridge the decryption contract and the oracle per the ERC-7573 interface. +- Monitoring and logging infrastructure watches both networks for event correlation and reconciles trade state. ## Protocol @@ -107,9 +107,9 @@ Threat model: Standard ERC-7573 provides atomic settlement but no privacy. For institutional use cases requiring confidentiality: -- **Threshold decryption oracle**: Run the oracle with several independent operators and require a k-of-n quorum before an outcome key is released. -- **Minimal on-chain trade data**: Keep full trade terms (price, size, counterparties) in internal systems; on-chain, store only a trade identifier and a short reference that links back to those records. -- **Private or proof-based payment layer**: Use a network or rollup for the cash leg that hides detailed balances but can provide a clear "payment completed or not completed" result for each trade identifier. +- Threshold decryption oracle: Run the oracle with several independent operators and require a k-of-n quorum before an outcome key is released. +- Minimal on-chain trade data: Keep full trade terms (price, size, counterparties) in internal systems; on-chain, store only a trade identifier and a short reference that links back to those records. +- Private or proof-based payment layer: Use a network or rollup for the cash leg that hides detailed balances but can provide a clear "payment completed or not completed" result for each trade identifier. These extensions do not change how the contracts decide outcomes: the asset contract still receives an outcome key and either delivers the asset or allows reclaim. diff --git a/patterns/pattern-eil.md b/patterns/pattern-eil.md index 4c2c359..eca05d1 100644 --- a/patterns/pattern-eil.md +++ b/patterns/pattern-eil.md @@ -57,12 +57,12 @@ Account-based cross-L2 interoperability where users sign once and execute transa ## Components -- **ERC-4337 account with multichain validation module** signs a Merkle root over the set of UserOps, letting one signature authorize calls across many chains. -- **CrossChainPaymaster contracts** on each L2 accept vouchers from liquidity providers, pay gas, and release funds on the destination. -- **L1CrossChainStakeManager** tracks liquidity provider registrations and stakes, with an 8-day unstake delay. -- **Liquidity providers** stake on L1 once per network and quote fees via reverse Dutch auction; stake sizing is O(networks), not O(funds moved). -- **P2P UserOp mempool** propagates signed intents and vouchers permissionlessly. -- **L1 canonical bridge** serves as the arbiter for disputes when a liquidity provider misbehaves. +- ERC-4337 account with multichain validation module signs a Merkle root over the set of UserOps, letting one signature authorize calls across many chains. +- CrossChainPaymaster contracts on each L2 accept vouchers from liquidity providers, pay gas, and release funds on the destination. +- L1CrossChainStakeManager tracks liquidity provider registrations and stakes, with an 8-day unstake delay. +- Liquidity providers stake on L1 once per network and quote fees via reverse Dutch auction; stake sizing is O(networks), not O(funds moved). +- P2P UserOp mempool propagates signed intents and vouchers permissionlessly. +- L1 canonical bridge serves as the arbiter for disputes when a liquidity provider misbehaves. ## Protocol diff --git a/patterns/pattern-erc3643-rwa.md b/patterns/pattern-erc3643-rwa.md index 611819e..87a91d4 100644 --- a/patterns/pattern-erc3643-rwa.md +++ b/patterns/pattern-erc3643-rwa.md @@ -49,12 +49,12 @@ Enable compliant tokenization of real-world assets with built-in identity manage ## Components -- **Permissioned token contract** (ERC-3643) exposes an ERC-20 interface but routes every transfer through compliance and identity checks. -- **On-chain identity contract** per participant stores claims (KYC, accreditation, jurisdiction) and exposes verification endpoints. -- **Identity registry** maps wallet addresses to identity contracts and gates who is eligible to hold the token. -- **Compliance module suite** is a pluggable rules engine that evaluates per-transfer restrictions (caps, lockups, eligibility classes). -- **Claim issuers** are off-chain actors that sign claims written into identity contracts; the registry tracks trusted issuers. -- **Token agent** holds administrative powers: freeze, force-transfer, blacklist, supply management, compliance-rule updates. +- Permissioned token contract (ERC-3643) exposes an ERC-20 interface but routes every transfer through compliance and identity checks. +- On-chain identity contract per participant stores claims (KYC, accreditation, jurisdiction) and exposes verification endpoints. +- Identity registry maps wallet addresses to identity contracts and gates who is eligible to hold the token. +- Compliance module suite is a pluggable rules engine that evaluates per-transfer restrictions (caps, lockups, eligibility classes). +- Claim issuers are off-chain actors that sign claims written into identity contracts; the registry tracks trusted issuers. +- Token agent holds administrative powers: freeze, force-transfer, blacklist, supply management, compliance-rule updates. ## Protocol diff --git a/patterns/pattern-focil-eip7805.md b/patterns/pattern-focil-eip7805.md index 314f03e..b2aebc8 100644 --- a/patterns/pattern-focil-eip7805.md +++ b/patterns/pattern-focil-eip7805.md @@ -55,11 +55,11 @@ Prevent censorship of Ethereum transactions by sophisticated block builders. A c ## Components -- **IL committee** of 16 validators selected per slot to construct inclusion lists for the following slot. -- **Inclusion list** is a signed, bounded set of transactions (8 KiB max per member) that the next block must include. -- **P2P gossip network** propagates signed inclusion lists across the validator set. -- **Fork-choice enforcement** is the consensus-layer rule: attesters refuse to attest to blocks that fail to satisfy observed ILs. -- **Equivocation detection** identifies committee members publishing conflicting ILs and discards their contributions. +- IL committee of 16 validators selected per slot to construct inclusion lists for the following slot. +- Inclusion list is a signed, bounded set of transactions (8 KiB max per member) that the next block must include. +- P2P gossip network propagates signed inclusion lists across the validator set. +- Fork-choice enforcement is the consensus-layer rule: attesters refuse to attest to blocks that fail to satisfy observed ILs. +- Equivocation detection identifies committee members publishing conflicting ILs and discards their contributions. ## Protocol diff --git a/patterns/pattern-forced-withdrawal.md b/patterns/pattern-forced-withdrawal.md index 6a1b9e4..92660f9 100644 --- a/patterns/pattern-forced-withdrawal.md +++ b/patterns/pattern-forced-withdrawal.md @@ -50,12 +50,12 @@ When an L2 sequencer, relayer, or operator becomes unavailable, users need a uni ## Components -- **Data availability source** lets the user reconstruct their position. Can be L1 calldata, L1 blobs, an external DA layer, a validium DA committee, or client-side storage. -- **L1 state-root oracle** stores the last verified L2 state root. Validity rollups anchor with a zero-knowledge proof; optimistic rollups anchor after a challenge period survives. -- **Proof verifier contract** accepts Merkle proofs (transparent systems) or zero-knowledge proofs (privacy systems) and checks them against the anchored root. -- **Nullifier registry** records completed withdrawals to prevent double-claims. -- **Bridge liquidity contract** holds the locked deposits that forced exits draw from; no new funds are created. -- **Client-side prover** with the required circuit, proving keys or SRS artifacts, and local compute (roughly 0.5 to 3 seconds native or 20 to 30 seconds in browser WASM on current hardware). +- Data availability source lets the user reconstruct their position. Can be L1 calldata, L1 blobs, an external DA layer, a validium DA committee, or client-side storage. +- L1 state-root oracle stores the last verified L2 state root. Validity rollups anchor with a zero-knowledge proof; optimistic rollups anchor after a challenge period survives. +- Proof verifier contract accepts Merkle proofs (transparent systems) or zero-knowledge proofs (privacy systems) and checks them against the anchored root. +- Nullifier registry records completed withdrawals to prevent double-claims. +- Bridge liquidity contract holds the locked deposits that forced exits draw from; no new funds are created. +- Client-side prover with the required circuit, proving keys or SRS artifacts, and local compute (roughly 0.5 to 3 seconds native or 20 to 30 seconds in browser WASM on current hardware). Where the data lives determines the trust assumption: @@ -105,11 +105,11 @@ Threat model: ## Trade-offs -- **Upgrade risk:** 86% of 129 L2 projects allow instant contract upgrades without exit windows ([Ethical Risk Analysis of L2 Rollups, 2025](https://arxiv.org/html/2512.12732v1)). An escape hatch the operator can remove via upgrade provides no meaningful guarantee. L2Beat Stages requires 7-day (Stage 1) or 30-day (Stage 2) upgrade delays, minus any withdrawal delay. -- **DA withholding:** validium DA committees can freeze all funds by refusing to share state. External DA layers add a liveness dependency. On-chain calldata and blobs are immune but expensive. For privacy systems, data can sit on-chain yet be useless without decryption keys. -- **State freshness gap:** users can prove only against the most recently anchored root. Any transactions after that root are lost. Anchoring intervals range from minutes (validity rollups) to hours. -- **Mass exit:** everyone hits L1 at once. Gas prices spike, users with no L1 ETH cannot participate, and leveraged DeFi positions may create claims exceeding underlying bridge deposits. -- **Proving liveness:** for privacy systems, the user must retain secrets and run a compatible prover. The prover code must be open-source, deterministically compilable, and match the L1 verifier's expected proof format. A version mismatch means funds are frozen until governance acts. Browser WASM proving works but is 5 to 15 times slower than native. +- Upgrade risk: 86% of 129 L2 projects allow instant contract upgrades without exit windows ([Ethical Risk Analysis of L2 Rollups, 2025](https://arxiv.org/html/2512.12732v1)). An escape hatch the operator can remove via upgrade provides no meaningful guarantee. L2Beat Stages requires 7-day (Stage 1) or 30-day (Stage 2) upgrade delays, minus any withdrawal delay. +- DA withholding: validium DA committees can freeze all funds by refusing to share state. External DA layers add a liveness dependency. On-chain calldata and blobs are immune but expensive. For privacy systems, data can sit on-chain yet be useless without decryption keys. +- State freshness gap: users can prove only against the most recently anchored root. Any transactions after that root are lost. Anchoring intervals range from minutes (validity rollups) to hours. +- Mass exit: everyone hits L1 at once. Gas prices spike, users with no L1 ETH cannot participate, and leveraged DeFi positions may create claims exceeding underlying bridge deposits. +- Proving liveness: for privacy systems, the user must retain secrets and run a compatible prover. The prover code must be open-source, deterministically compilable, and match the L1 verifier's expected proof format. A version mismatch means funds are frozen until governance acts. Browser WASM proving works but is 5 to 15 times slower than native. ## Example diff --git a/patterns/pattern-hybrid-public-private-modes.md b/patterns/pattern-hybrid-public-private-modes.md index 528de7d..e8f6409 100644 --- a/patterns/pattern-hybrid-public-private-modes.md +++ b/patterns/pattern-hybrid-public-private-modes.md @@ -50,12 +50,12 @@ Allow institutions to select public or private execution mode on a per-transacti ## Components -- **Public execution environment** is an L1 or transparent L2 chain where amounts, counterparties, and timing are visible. -- **Private execution environment** is a privacy L2 or shielded pool where amounts and counterparties are hidden behind ZK commitments or FHE ciphertexts. -- **Mode-routing layer** is a smart contract or middleware that directs each transaction leg based on policy rules. -- **Policy engine** defines mode-selection criteria: counterparty whitelist, asset thresholds, jurisdiction-based rules. -- **Cross-mode settlement coordinator** uses ERC-7573 outcome keys or shared commitments to link a public leg and a private leg into one atomic trade. -- **View-key infrastructure** issues selective-disclosure artifacts from private legs to counterparties and regulators. +- Public execution environment is an L1 or transparent L2 chain where amounts, counterparties, and timing are visible. +- Private execution environment is a privacy L2 or shielded pool where amounts and counterparties are hidden behind ZK commitments or FHE ciphertexts. +- Mode-routing layer is a smart contract or middleware that directs each transaction leg based on policy rules. +- Policy engine defines mode-selection criteria: counterparty whitelist, asset thresholds, jurisdiction-based rules. +- Cross-mode settlement coordinator uses ERC-7573 outcome keys or shared commitments to link a public leg and a private leg into one atomic trade. +- View-key infrastructure issues selective-disclosure artifacts from private legs to counterparties and regulators. ## Protocol diff --git a/patterns/pattern-icma-bdt-data-model.md b/patterns/pattern-icma-bdt-data-model.md index 74dde5e..3c06fea 100644 --- a/patterns/pattern-icma-bdt-data-model.md +++ b/patterns/pattern-icma-bdt-data-model.md @@ -44,11 +44,11 @@ Use the ICMA Bond Data Taxonomy as the canonical schema for bond terms and lifec ## Components -- **Canonical schema** defines bond terms (identifiers, parties, cash flows, covenants) and lifecycle events (issuance, coupons, redemption, restructuring). -- **Schema validator** checks that bond records conform to the canonical definitions before they are signed, hashed, or anchored. -- **Compression layer** converts verbose representations (for example XML) into binary or compact serialization for efficient on-chain anchoring. -- **Registrar integration** maps internal registrar records to the canonical schema so existing systems can emit conformant data without rewriting their back office. -- **Attestation anchor** posts hashes of conformant records to an on-chain attestation registry so any verifier can check that a disclosed document matches what the registrar recorded. +- Canonical schema defines bond terms (identifiers, parties, cash flows, covenants) and lifecycle events (issuance, coupons, redemption, restructuring). +- Schema validator checks that bond records conform to the canonical definitions before they are signed, hashed, or anchored. +- Compression layer converts verbose representations (for example XML) into binary or compact serialization for efficient on-chain anchoring. +- Registrar integration maps internal registrar records to the canonical schema so existing systems can emit conformant data without rewriting their back office. +- Attestation anchor posts hashes of conformant records to an on-chain attestation registry so any verifier can check that a disclosed document matches what the registrar recorded. ## Protocol diff --git a/patterns/pattern-l2-privacy-evaluation.md b/patterns/pattern-l2-privacy-evaluation.md index f28ed4e..563df65 100644 --- a/patterns/pattern-l2-privacy-evaluation.md +++ b/patterns/pattern-l2-privacy-evaluation.md @@ -65,37 +65,37 @@ Give institutions a vendor-neutral, sourced methodology for comparing privacy-pr | Metric | Discrete metrics | | :------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | -| **Max Throughput** | Max theoretical TPS, tested peak TPS (with benchmark link). Report TPSPublic and TPSPrivate separately | -| **Transaction cost** | Gas usage in `L1 gas units` + `L2 gas units` for Simple Value Transfer | -| **Bridging and exit** | L2 to L1 withdrawal and forced exit cost (gas units) | -| **Finality time** | `Soft Finality` (L2 inclusion), `Hard Finality` (L1 commitment + proof), `Challenge Period` | -| **Transaction retrieval** | Sync mechanism (`Trial decryption`, `Detection Keys`, `Server-side filtering`) and sync speed | +| Max Throughput | Max theoretical TPS, tested peak TPS (with benchmark link). Report TPSPublic and TPSPrivate separately | +| Transaction cost | Gas usage in `L1 gas units` + `L2 gas units` for Simple Value Transfer | +| Bridging and exit | L2 to L1 withdrawal and forced exit cost (gas units) | +| Finality time | `Soft Finality` (L2 inclusion), `Hard Finality` (L1 commitment + proof), `Challenge Period` | +| Transaction retrieval | Sync mechanism (`Trial decryption`, `Detection Keys`, `Server-side filtering`) and sync speed | ### 2. Privacy and Data Availability | Metric | Discrete metrics | | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------ | -| **Level of privacy** | **What**: `Balance`, `Sender/Receiver`, `Amount`, `Code/Function`, `Contract Bytecode`. **Who sees**: `Public`, `Sequencer`, `Prover` | -| **DA layer** | `L1 Call Data`, `L1 Data Blobs (EIP-4844)`, `External DAC` | -| **DA trust** | `Trustless/L1-secured`, `Trusted DAC` | -| **Data posted to L1** | `Full Transaction Data`, `State Diff`, `Validity Proof Only` | -| **Compliance features** | `Incoming Viewing Key`, `Outgoing Viewing Key`, `Full History Viewing Key` | -| **Privacy trust model** | **Base**: `Cryptographic`, `Threshold (MPC/FHE)`. **Collusion threshold**: m-of-n | -| **Network privacy** | RPC privacy options (`Tor/I2P`, `Oblivious HTTP`, `Mixnet`) | +| Level of privacy | What: `Balance`, `Sender/Receiver`, `Amount`, `Code/Function`, `Contract Bytecode`. Who sees: `Public`, `Sequencer`, `Prover` | +| DA layer | `L1 Call Data`, `L1 Data Blobs (EIP-4844)`, `External DAC` | +| DA trust | `Trustless/L1-secured`, `Trusted DAC` | +| Data posted to L1 | `Full Transaction Data`, `State Diff`, `Validity Proof Only` | +| Compliance features | `Incoming Viewing Key`, `Outgoing Viewing Key`, `Full History Viewing Key` | +| Privacy trust model | Base: `Cryptographic`, `Threshold (MPC/FHE)`. Collusion threshold: m-of-n | +| Network privacy | RPC privacy options (`Tor/I2P`, `Oblivious HTTP`, `Mixnet`) | ### 3. Security and governance | Metric | Discrete metrics | | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Sequencer decentralization** | `Centralized`, `Permissioned Set`, `Decentralized Auction`, `Based (L1 Sequencing)` | -| **Censorship resistance** | **Mechanism**: `Force inclusion`, `Escape Hatch`, `Council`. **User burden**: `Stateless`, `Merkle Witness`, `Full State Reconstruction`. **Latency**: `Immediate`, `Challenge Period` | -| **Prover mechanism** | **Access**: `Whitelist`, `Permissionless`. **System**: `Plonk`, `Stark`, `FHE`, `Groth16` | -| **Upgrade process** | **Governance**: `Multisig (m-of-n)`, `Immutable`, `DAO Vote`. **Timelock**: delay in days or hours | -| **Client-side requirements** | **Client proving**: `Yes`/`No`. **Features**: `Mobile Proving`, `Trusted Delegation`, `Blind Delegation` | -| **Finality security** | `Validity (ZK)`, `Optimistic (Fraud Proofs)` | -| **Proof system setup** | `Trusted Ceremony`, `Transparent` | -| **Programmability** | **Language**: `EVM/Solidity`, `DSL`, `WASM`. **Deployment**: `Permissionless`, `Whitelisted` | -| **PQ security** | Susceptible to HNDL attacks? (`Yes`/`No`) | +| Sequencer decentralization | `Centralized`, `Permissioned Set`, `Decentralized Auction`, `Based (L1 Sequencing)` | +| Censorship resistance | Mechanism: `Force inclusion`, `Escape Hatch`, `Council`. User burden: `Stateless`, `Merkle Witness`, `Full State Reconstruction`. Latency: `Immediate`, `Challenge Period` | +| Prover mechanism | Access: `Whitelist`, `Permissionless`. System: `Plonk`, `Stark`, `FHE`, `Groth16` | +| Upgrade process | Governance: `Multisig (m-of-n)`, `Immutable`, `DAO Vote`. Timelock: delay in days or hours | +| Client-side requirements | Client proving: `Yes`/`No`. Features: `Mobile Proving`, `Trusted Delegation`, `Blind Delegation` | +| Finality security | `Validity (ZK)`, `Optimistic (Fraud Proofs)` | +| Proof system setup | `Trusted Ceremony`, `Transparent` | +| Programmability | Language: `EVM/Solidity`, `DSL`, `WASM`. Deployment: `Permissionless`, `Whitelisted` | +| PQ security | Susceptible to HNDL attacks? (`Yes`/`No`) | ## Simple Value Transfer @@ -132,12 +132,12 @@ Results below are drawn from public documentation and independent sources. Empty | Protocol | Deployment | Privacy model | Proof system | DA | Client proving | Censorship resistance | | :--------------- | :----------- | :----------------- | :----------------- | :---------------------- | :---------------------- | :-------------------- | -| **Aztec** | Public L2 | Cryptographic (ZK) | UltraHonk | L1 Blobs | Yes (heavy) | Escape Hatch | -| **Miden** | Public L2 | Cryptographic (ZK) | STARK (Winterfell) | L1 Blobs | Yes (can be delegated) | TBD | -| **Intmax** | Public L2 | Cryptographic (ZK) | Plonk/Gnark | Stateless (Client-Side) | Yes (light) | Force Inclusion | -| **Prividium** | AppChain SDK | Cryptographic (ZK) | Boojum/Plonk | External (Private DB) | No (server) | Operator-dependent | -| **Scroll Cloak** | AppChain SDK | Cryptographic (ZK) | Scroll zkEVM | Host chain | No (prover service) | Force Exit to host | -| **EY Nightfall** | AppChain SDK | Cryptographic (ZK) | UltraPlonk | L1 Call Data | Yes | TBD | +| Aztec | Public L2 | Cryptographic (ZK) | UltraHonk | L1 Blobs | Yes (heavy) | Escape Hatch | +| Miden | Public L2 | Cryptographic (ZK) | STARK (Winterfell) | L1 Blobs | Yes (can be delegated) | TBD | +| Intmax | Public L2 | Cryptographic (ZK) | Plonk/Gnark | Stateless (Client-Side) | Yes (light) | Force Inclusion | +| Prividium | AppChain SDK | Cryptographic (ZK) | Boojum/Plonk | External (Private DB) | No (server) | Operator-dependent | +| Scroll Cloak | AppChain SDK | Cryptographic (ZK) | Scroll zkEVM | Host chain | No (prover service) | Force Exit to host | +| EY Nightfall | AppChain SDK | Cryptographic (ZK) | UltraPlonk | L1 Call Data | Yes | TBD | AppChain SDKs have deployment-dependent assumptions (sequencer, DA, governance) that vary by operator. Public L2s offering hybrid modes (Aztec, Miden) let the developer choose between a public account model and a private UTXO note model; stateless or validium designs (Intmax, Prividium, Scroll Cloak) hide balances and transfer data by default. diff --git a/patterns/pattern-modular-privacy-stack.md b/patterns/pattern-modular-privacy-stack.md index e8205fb..9c3b522 100644 --- a/patterns/pattern-modular-privacy-stack.md +++ b/patterns/pattern-modular-privacy-stack.md @@ -67,12 +67,12 @@ Compose a privacy architecture from four distinct layers: Data, Execution, Settl ## Components -- **Data layer** stores and retrieves encrypted payloads. Options include off-chain encrypted storage, data-availability layers, L1 blob data, and content-addressed networks with encryption. -- **Execution layer** runs private computation. Options include zero-knowledge execution environments, Fully Homomorphic Encryption, and trusted execution environments. -- **Settlement layer** provides finality and atomicity. Options include L1, validity-proof rollups, optimistic rollups, and cross-chain atomic swap protocols. -- **Disclosure layer** exposes scoped access for audit and compliance. Options include viewing keys, zero-knowledge proofs of properties, threshold key management, and on-chain attestations. -- **Interface contracts** define what each layer consumes and emits: encrypted reads and writes for Data, state transitions for Execution, proofs and signed transactions for Settlement, and disclosure artifacts for Disclosure. -- **Orchestration service** routes references and coordinates cross-layer flows; it aggregates audit logs across layers. +- Data layer stores and retrieves encrypted payloads. Options include off-chain encrypted storage, data-availability layers, L1 blob data, and content-addressed networks with encryption. +- Execution layer runs private computation. Options include zero-knowledge execution environments, Fully Homomorphic Encryption, and trusted execution environments. +- Settlement layer provides finality and atomicity. Options include L1, validity-proof rollups, optimistic rollups, and cross-chain atomic swap protocols. +- Disclosure layer exposes scoped access for audit and compliance. Options include viewing keys, zero-knowledge proofs of properties, threshold key management, and on-chain attestations. +- Interface contracts define what each layer consumes and emits: encrypted reads and writes for Data, state transitions for Execution, proofs and signed transactions for Settlement, and disclosure artifacts for Disclosure. +- Orchestration service routes references and coordinates cross-layer flows; it aggregates audit logs across layers. If a component is itself a pattern in this map (see `sub_patterns` and `related_patterns`), link it rather than describe it in depth. diff --git a/patterns/pattern-mpc-custody.md b/patterns/pattern-mpc-custody.md index 0973883..91512d8 100644 --- a/patterns/pattern-mpc-custody.md +++ b/patterns/pattern-mpc-custody.md @@ -62,13 +62,13 @@ Provide custody and controlled execution of digital-asset transactions by distri ## Components -- **Threshold signature scheme** such as threshold ECDSA or threshold EdDSA; an `m`-of-`n` quorum produces a signature indistinguishable from a single-key signature. -- **Signing nodes** run inside hardened environments (trusted execution environments or hardware security modules) and hold one key share each. -- **Policy engine** validates each signing request against transaction limits, destination allowlists, and role-based approvals before releasing the signing request to the nodes. -- **Orchestration API** exposes request submission, approval workflow, audit events, and status queries to client applications. -- **Key-generation ceremony** creates the shares without ever materializing the full key; proactive key refresh rotates shares while keeping the public key stable. -- **Audit log** records signing attempts, approvals, denials, and share-refresh events for compliance review. -- **Target chain** (L1 or L2) that ultimately receives the signed transaction. +- Threshold signature scheme such as threshold ECDSA or threshold EdDSA; an `m`-of-`n` quorum produces a signature indistinguishable from a single-key signature. +- Signing nodes run inside hardened environments (trusted execution environments or hardware security modules) and hold one key share each. +- Policy engine validates each signing request against transaction limits, destination allowlists, and role-based approvals before releasing the signing request to the nodes. +- Orchestration API exposes request submission, approval workflow, audit events, and status queries to client applications. +- Key-generation ceremony creates the shares without ever materializing the full key; proactive key refresh rotates shares while keeping the public key stable. +- Audit log records signing attempts, approvals, denials, and share-refresh events for compliance review. +- Target chain (L1 or L2) that ultimately receives the signed transaction. ## Protocol diff --git a/patterns/pattern-native-account-abstraction.md b/patterns/pattern-native-account-abstraction.md index cf6deb3..2ceaf23 100644 --- a/patterns/pattern-native-account-abstraction.md +++ b/patterns/pattern-native-account-abstraction.md @@ -54,10 +54,10 @@ Make every Ethereum account natively programmable by replacing the hardcoded ECD ## Components -- **Frame transaction**: ordered list of frames per transaction. Each frame specifies a mode (`VERIFY`, `SENDER`, `DEFAULT`), target address, gas limit, and data. Frames execute sequentially with independent gas metering. -- **Account validation code**: per-account logic executed inside `VERIFY` frames. It can validate any signature scheme (ECDSA, ML-DSA, SLH-DSA, passkeys, multisig) or any zero-knowledge proof. -- **`APPROVE` opcode**: called inside `VERIFY` frames to authorise execution (`0x0`), payment (`0x1`), or both (`0x2`). Payment approval decides who pays gas at runtime, decoupling authorisation of execution from gas payment. -- **Regular mempool**: carries frame transactions alongside legacy transactions. No separate mempool or bundler network. +- Frame transaction: ordered list of frames per transaction. Each frame specifies a mode (`VERIFY`, `SENDER`, `DEFAULT`), target address, gas limit, and data. Frames execute sequentially with independent gas metering. +- Account validation code: per-account logic executed inside `VERIFY` frames. It can validate any signature scheme (ECDSA, ML-DSA, SLH-DSA, passkeys, multisig) or any zero-knowledge proof. +- `APPROVE` opcode: called inside `VERIFY` frames to authorise execution (`0x0`), payment (`0x1`), or both (`0x2`). Payment approval decides who pays gas at runtime, decoupling authorisation of execution from gas payment. +- Regular mempool: carries frame transactions alongside legacy transactions. No separate mempool or bundler network. ## Protocol diff --git a/patterns/pattern-network-anonymity.md b/patterns/pattern-network-anonymity.md index fa1bed0..2589e61 100644 --- a/patterns/pattern-network-anonymity.md +++ b/patterns/pattern-network-anonymity.md @@ -56,9 +56,9 @@ This is a meta-pattern. Multiple sub-patterns exist, each with different trade-o ## Components -- **Transport anonymity layer**: a relay network, mix network, or hardware-assisted cluster that strips or obscures sender metadata before the message reaches the destination. -- **Client routing or submission library**: prepares the message for the chosen anonymity layer (layered encryption, mix encoding, or secret sharing). -- **Destination**: RPC endpoint, sequencer, or transaction mempool. The anonymity layer sits between the client and the destination. +- Transport anonymity layer: a relay network, mix network, or hardware-assisted cluster that strips or obscures sender metadata before the message reaches the destination. +- Client routing or submission library: prepares the message for the chosen anonymity layer (layered encryption, mix encoding, or secret sharing). +- Destination: RPC endpoint, sequencer, or transaction mempool. The anonymity layer sits between the client and the destination. Each sub-pattern instantiates these components differently. See `sub_patterns` in frontmatter. diff --git a/patterns/pattern-noir-private-contracts.md b/patterns/pattern-noir-private-contracts.md index 7ea268b..9724b42 100644 --- a/patterns/pattern-noir-private-contracts.md +++ b/patterns/pattern-noir-private-contracts.md @@ -61,11 +61,11 @@ Give developers a privacy-focused DSL to write smart contracts that blend public ## Components -- **Private contract DSL**: Rust-inspired language for authoring functions, compiling to a circuit intermediate representation. -- **Circuit intermediate representation**: backend-agnostic IR that the prover backend compiles into proving and verification keys. -- **Client-side prover**: generates proofs for private-function executions on the user's machine (typically 8 GB RAM recommended). -- **Privacy rollup**: private execution runtime, public execution VM, note-discovery infrastructure, and validity-proof pipeline to Ethereum L1. -- **Encrypted logs**: note discovery mechanism; only the holders of decryption keys can read log contents. +- Private contract DSL: Rust-inspired language for authoring functions, compiling to a circuit intermediate representation. +- Circuit intermediate representation: backend-agnostic IR that the prover backend compiles into proving and verification keys. +- Client-side prover: generates proofs for private-function executions on the user's machine (typically 8 GB RAM recommended). +- Privacy rollup: private execution runtime, public execution VM, note-discovery infrastructure, and validity-proof pipeline to Ethereum L1. +- Encrypted logs: note discovery mechanism; only the holders of decryption keys can read log contents. ## Protocol diff --git a/patterns/pattern-oif.md b/patterns/pattern-oif.md index 272c3ef..aaaf5cc 100644 --- a/patterns/pattern-oif.md +++ b/patterns/pattern-oif.md @@ -52,11 +52,11 @@ Enable cross-chain intent-based settlement where users express desired outcomes ## Components -- **Intent contracts**: input-collection and output-delivery entry points that escrow user assets, record intent parameters, and release funds on proof of fulfilment. -- **Solver**: off-chain service that indexes intents, computes execution routes (swaps, bridges, liquidity routing), and submits fulfilment transactions. -- **Cross-chain messaging layer**: transports proofs of fulfilment between origin and destination chains. -- **Oracle or proof mechanism**: verifies that outputs have been delivered before the origin contract releases inputs. -- **Settlement module**: finalises the intent and handles refund or cancellation on failure. +- Intent contracts: input-collection and output-delivery entry points that escrow user assets, record intent parameters, and release funds on proof of fulfilment. +- Solver: off-chain service that indexes intents, computes execution routes (swaps, bridges, liquidity routing), and submits fulfilment transactions. +- Cross-chain messaging layer: transports proofs of fulfilment between origin and destination chains. +- Oracle or proof mechanism: verifies that outputs have been delivered before the origin contract releases inputs. +- Settlement module: finalises the intent and handles refund or cancellation on failure. ## Protocol diff --git a/patterns/pattern-onion-routing.md b/patterns/pattern-onion-routing.md index cf32114..cc09880 100644 --- a/patterns/pattern-onion-routing.md +++ b/patterns/pattern-onion-routing.md @@ -62,10 +62,10 @@ Hide who is sending transactions or querying state by routing traffic through a ## Components -- **Circuit of relays**: three or more nodes selected from a relay directory, each holding one encryption layer. -- **Layered (onion) encryption**: the client wraps the message once per relay, outermost layer decryptable only by the first hop. -- **Client routing library**: negotiates the circuit, applies the encryption layers, and exposes a local proxy (SOCKS5 or WASM) to the dApp or wallet. -- **Exit relay**: decrypts the last layer and forwards the message to the destination (RPC node, mempool, .onion service). +- Circuit of relays: three or more nodes selected from a relay directory, each holding one encryption layer. +- Layered (onion) encryption: the client wraps the message once per relay, outermost layer decryptable only by the first hop. +- Client routing library: negotiates the circuit, applies the encryption layers, and exposes a local proxy (SOCKS5 or WASM) to the dApp or wallet. +- Exit relay: decrypts the last layer and forwards the message to the destination (RPC node, mempool, .onion service). ## Protocol diff --git a/patterns/pattern-origin-locked-confidential-ledger.md b/patterns/pattern-origin-locked-confidential-ledger.md index ed40b6e..012ecc7 100644 --- a/patterns/pattern-origin-locked-confidential-ledger.md +++ b/patterns/pattern-origin-locked-confidential-ledger.md @@ -58,12 +58,12 @@ Provide confidential balances and transfers for an existing ERC-20 on an origin ## Components -- **Origin locking contract**: minimal contract on the origin EVM chain that escrows deposits and releases withdrawals. It is the only place user funds live. -- **Encrypted ledger**: per-account balances stored as ElGamal ciphertext under the account holder's key on a separate confidentiality execution layer. -- **ZK verifier**: validates state transitions on the encrypted ledger (no overspend, conservation of value, correct key usage) without decrypting balances. -- **Homomorphic update logic**: encrypted balances update via ElGamal additive homomorphism; plaintext balances are never reconstructed by any component. -- **Verifiable cross-chain messaging**: light-client or IBC-style messaging between the origin chain and the confidentiality layer. Relayers move packets but are not trusted for correctness. -- **Disclosure layer** (optional): scoped viewing keys or per-transaction audit keys generated via MPC, so a designated auditor can decrypt specific transactions under review. +- Origin locking contract: minimal contract on the origin EVM chain that escrows deposits and releases withdrawals. It is the only place user funds live. +- Encrypted ledger: per-account balances stored as ElGamal ciphertext under the account holder's key on a separate confidentiality execution layer. +- ZK verifier: validates state transitions on the encrypted ledger (no overspend, conservation of value, correct key usage) without decrypting balances. +- Homomorphic update logic: encrypted balances update via ElGamal additive homomorphism; plaintext balances are never reconstructed by any component. +- Verifiable cross-chain messaging: light-client or IBC-style messaging between the origin chain and the confidentiality layer. Relayers move packets but are not trusted for correctness. +- Disclosure layer (optional): scoped viewing keys or per-transaction audit keys generated via MPC, so a designated auditor can decrypt specific transactions under review. ## Protocol diff --git a/patterns/pattern-permissioned-ledger-interoperability.md b/patterns/pattern-permissioned-ledger-interoperability.md index d651753..329dcb0 100644 --- a/patterns/pattern-permissioned-ledger-interoperability.md +++ b/patterns/pattern-permissioned-ledger-interoperability.md @@ -61,11 +61,11 @@ Enable atomic transactions and data exchange across distinct permissioned ledger ## Components -- **Permissioned ledger domains**, each with its own consensus, identity set, and privacy boundary. -- **Synchronization protocol** that coordinates commits across domains (two-phase or view-based atomic commit). -- **Smart contract language** with explicit participant visibility controls, so contract state is replicated only to actual stakeholders. -- **Governance model** for validator or participant node admission, rotation, and exit. -- **Selective disclosure mechanism** for supervisors and auditors to access relevant state without full replication. +- Permissioned ledger domains, each with its own consensus, identity set, and privacy boundary. +- Synchronization protocol that coordinates commits across domains (two-phase or view-based atomic commit). +- Smart contract language with explicit participant visibility controls, so contract state is replicated only to actual stakeholders. +- Governance model for validator or participant node admission, rotation, and exit. +- Selective disclosure mechanism for supervisors and auditors to access relevant state without full replication. ## Protocol diff --git a/patterns/pattern-permissionless-spend-auth.md b/patterns/pattern-permissionless-spend-auth.md index 40c4dfc..7e87869 100644 --- a/patterns/pattern-permissionless-spend-auth.md +++ b/patterns/pattern-permissionless-spend-auth.md @@ -53,11 +53,11 @@ Separate note ownership from spend authorization in a shielded pool, and use a r ## Components -- **Ownership secret**: a per-user secret (e.g., a nullifier key) committed in each note via its hash. Not derived from any auth credential. -- **Auth policy registry**: on-chain Merkleized registry binding `(userIdentifier, innerVkHash)` to credentials. Separate from the note tree so auth updates do not touch note state. -- **Outer circuit (stable)**: proves ownership, enforces pool invariants (value conservation, nullifier correctness), and recursively verifies the inner proof. -- **Inner circuit (permissionless)**: proves authorization for a registered auth policy. Anyone can author and deploy a new inner circuit type. -- **Recursive verifier**: the outer circuit verifies the inner circuit's proof inline, producing a single on-chain proof format. +- Ownership secret: a per-user secret (e.g., a nullifier key) committed in each note via its hash. Not derived from any auth credential. +- Auth policy registry: on-chain Merkleized registry binding `(userIdentifier, innerVkHash)` to credentials. Separate from the note tree so auth updates do not touch note state. +- Outer circuit (stable): proves ownership, enforces pool invariants (value conservation, nullifier correctness), and recursively verifies the inner proof. +- Inner circuit (permissionless): proves authorization for a registered auth policy. Anyone can author and deploy a new inner circuit type. +- Recursive verifier: the outer circuit verifies the inner circuit's proof inline, producing a single on-chain proof format. The shielded pool this plugs into is described in `pattern-shielding`. diff --git a/patterns/pattern-plasma-stateless-privacy.md b/patterns/pattern-plasma-stateless-privacy.md index c98b079..8af7168 100644 --- a/patterns/pattern-plasma-stateless-privacy.md +++ b/patterns/pattern-plasma-stateless-privacy.md @@ -63,11 +63,11 @@ Use a stateless Plasma architecture to enable private token transfers where tran ## Components -- **L1 anchor contract**: stores block commitments (Merkle roots of transaction hashes) and handles deposits, withdrawals, and forced exits. -- **Block producer**: aggregates transactions, collects signatures, and posts the block commitment to L1. Stateless with respect to transaction contents. -- **Client-side prover**: users generate ZK balance and transfer proofs locally (e.g., recursive FRI-based proofs). -- **User-held Data Availability**: users custody their own note and transfer history. Optional trust-minimized DA layer for redundancy. -- **Forced-exit mechanism**: L1 contract accepts exit proofs independently of the block producer, bypassing liveness failure. +- L1 anchor contract: stores block commitments (Merkle roots of transaction hashes) and handles deposits, withdrawals, and forced exits. +- Block producer: aggregates transactions, collects signatures, and posts the block commitment to L1. Stateless with respect to transaction contents. +- Client-side prover: users generate ZK balance and transfer proofs locally (e.g., recursive FRI-based proofs). +- User-held Data Availability: users custody their own note and transfer history. Optional trust-minimized DA layer for redundancy. +- Forced-exit mechanism: L1 contract accepts exit proofs independently of the block producer, bypassing liveness failure. ## Protocol diff --git a/patterns/pattern-pretrade-privacy-encryption.md b/patterns/pattern-pretrade-privacy-encryption.md index 804d1f4..1bb59c7 100644 --- a/patterns/pattern-pretrade-privacy-encryption.md +++ b/patterns/pattern-pretrade-privacy-encryption.md @@ -74,11 +74,11 @@ Prevent front-running and information leakage by routing quotes and orders via e ## Components -- **Encrypted submission path**: either a threshold-encrypted mempool (committee holds key shares; ciphertext is decrypted only after ordering is committed) or a private-builder stack (confidential execution environment that sees the order but commits to ordering honesty). -- **RFQ broker**: off-chain service that routes quote requests to allow-listed counterparties and records the quote lifecycle for audit. -- **Settlement rail**: shielded pool or privacy L2 where the winning order settles with amounts hidden. -- **Fallback path**: unencrypted submission route invoked if the encrypted path stalls or fails. -- **Audit trail**: signed or committed record of every RFQ, quote, and settlement for compliance review. +- Encrypted submission path: either a threshold-encrypted mempool (committee holds key shares; ciphertext is decrypted only after ordering is committed) or a private-builder stack (confidential execution environment that sees the order but commits to ordering honesty). +- RFQ broker: off-chain service that routes quote requests to allow-listed counterparties and records the quote lifecycle for audit. +- Settlement rail: shielded pool or privacy L2 where the winning order settles with amounts hidden. +- Fallback path: unencrypted submission route invoked if the encrypted path stalls or fails. +- Audit trail: signed or committed record of every RFQ, quote, and settlement for compliance review. The encrypted mempool details are covered in `pattern-threshold-encrypted-mempool`; the settlement layer in `pattern-shielding` or `pattern-privacy-l2s`. diff --git a/patterns/pattern-privacy-l2s.md b/patterns/pattern-privacy-l2s.md index 00a9d68..abb2dd7 100644 --- a/patterns/pattern-privacy-l2s.md +++ b/patterns/pattern-privacy-l2s.md @@ -70,11 +70,11 @@ Use a privacy-native rollup, either ZK-based or FHE-based, to execute financial ## Components -- **Privacy rollup execution layer**: either a ZK rollup that commits to state via ZK proofs of valid transitions, or an FHE rollup that computes on encrypted state. -- **L1 bridge contracts**: deposit, withdraw, and forced-exit paths that anchor the rollup to Ethereum. -- **Client-side or coprocessor prover**: generates ZK proofs for private state transitions, or orchestrates FHE computation. -- **Viewing key and disclosure infrastructure**: off-chain key management and attestation services for regulator access. -- **Sequencer or block builder**: collects and orders transactions for the rollup; centralized on most deployments today. +- Privacy rollup execution layer: either a ZK rollup that commits to state via ZK proofs of valid transitions, or an FHE rollup that computes on encrypted state. +- L1 bridge contracts: deposit, withdraw, and forced-exit paths that anchor the rollup to Ethereum. +- Client-side or coprocessor prover: generates ZK proofs for private state transitions, or orchestrates FHE computation. +- Viewing key and disclosure infrastructure: off-chain key management and attestation services for regulator access. +- Sequencer or block builder: collects and orders transactions for the rollup; centralized on most deployments today. Shielded note logic on the rollup is described in `pattern-shielding`; disclosure flows in `pattern-regulatory-disclosure-keys-proofs`. diff --git a/patterns/pattern-private-iso20022.md b/patterns/pattern-private-iso20022.md index 82433bc..b69a955 100644 --- a/patterns/pattern-private-iso20022.md +++ b/patterns/pattern-private-iso20022.md @@ -55,12 +55,12 @@ Coordinate private ERC-20 settlements between banks using ISO 20022 as the instr ## Components -- **ISO 20022 schema and envelopes**: pacs.008, pacs.009, pacs.002, camt.\* messages plus the `` extension mechanism used to carry commitments and proofs. -- **Message commitment `C_msg`**: hash of the canonical ISO message used to bind the settlement on-chain to the off-chain instruction. -- **Private settlement rail**: a shielded pool, a confidential token layer, or a privacy L2 that performs the cash-leg transfer with amounts and counterparties hidden on-chain. -- **Rollup or validium anchor** for minimal on-chain metadata (message type, coarse time bucket, status). -- **Off-chain services**: ISO parsing and canonicalization (XML to canonical JSON), KMS for bank and regulator keys, and a selective-disclosure service. -- **Settlement controller**: optional permissioned actor that authorizes confidential transfers on a permissioned confidential-token rail. +- ISO 20022 schema and envelopes: pacs.008, pacs.009, pacs.002, camt.\* messages plus the `` extension mechanism used to carry commitments and proofs. +- Message commitment `C_msg`: hash of the canonical ISO message used to bind the settlement on-chain to the off-chain instruction. +- Private settlement rail: a shielded pool, a confidential token layer, or a privacy L2 that performs the cash-leg transfer with amounts and counterparties hidden on-chain. +- Rollup or validium anchor for minimal on-chain metadata (message type, coarse time bucket, status). +- Off-chain services: ISO parsing and canonicalization (XML to canonical JSON), KMS for bank and regulator keys, and a selective-disclosure service. +- Settlement controller: optional permissioned actor that authorizes confidential transfers on a permissioned confidential-token rail. The shielded pool details live in `pattern-shielding`; the privacy L2 option in `pattern-privacy-l2s`; DvP coupling in `pattern-dvp-erc7573`. diff --git a/patterns/pattern-shielding.md b/patterns/pattern-shielding.md index c74e637..5a8831e 100644 --- a/patterns/pattern-shielding.md +++ b/patterns/pattern-shielding.md @@ -54,17 +54,17 @@ open_source_implementations: ## Intent -Enable **confidential transfers** by shielding balances, sender, and receiver, while still allowing regulators and auditors to verify via selective disclosure (viewing keys, proofs). The logic generalizes beyond ERC-20 to any transferable asset. +Enable confidential transfers by shielding balances, sender, and receiver, while still allowing regulators and auditors to verify via selective disclosure (viewing keys, proofs). The logic generalizes beyond ERC-20 to any transferable asset. ## Components -- **Shielded pool contract** stores commitments, the nullifier set, and a ZK verifier. Deployable on L1 or a shielded L2. -- **Hash-based commitments** (e.g. Poseidon) hide note contents; notes represent spendable state. -- **Nullifier set** prevents double-spends by tracking spent notes. -- **Prover and verifier**, with circuit logic authored in a DSL (Noir, Circom, Halo2, Gnark, etc.); the prover runs client-side. -- **Wallet/KMS** manages shielded keys and optional viewing keys. -- **Relayer/paymaster** (optional) for gas abstraction. -- **Stealth addresses** (optional, ERC-5564) for recipient unlinkability. +- Shielded pool contract stores commitments, the nullifier set, and a ZK verifier. Deployable on L1 or a shielded L2. +- Hash-based commitments (e.g. Poseidon) hide note contents; notes represent spendable state. +- Nullifier set prevents double-spends by tracking spent notes. +- Prover and verifier, with circuit logic authored in a DSL (Noir, Circom, Halo2, Gnark, etc.); the prover runs client-side. +- Wallet/KMS manages shielded keys and optional viewing keys. +- Relayer/paymaster (optional) for gas abstraction. +- Stealth addresses (optional, ERC-5564) for recipient unlinkability. ## Protocol From b766d5d0ba363791c8ed716ef382b5103e3ae8b1 Mon Sep 17 00:00:00 2001 From: Meyanis95 Date: Fri, 24 Apr 2026 11:28:34 +0200 Subject: [PATCH 04/10] fix(patterns): address CodeRabbit review on #154 Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 1 - patterns/pattern-co-snark.md | 1 - patterns/pattern-compliance-monitoring.md | 4 +- .../pattern-cross-chain-privacy-bridge.md | 8 +- patterns/pattern-dvp-erc7573.md | 4 +- patterns/pattern-eil.md | 4 +- patterns/pattern-forced-withdrawal.md | 10 +- .../pattern-hybrid-public-private-modes.md | 5 +- patterns/pattern-icma-bdt-data-model.md | 6 +- .../pattern-l2-encrypted-offchain-audit.md | 8 +- patterns/pattern-l2-privacy-evaluation.md | 154 ------------------ patterns/pattern-lean-ethereum.md | 6 +- patterns/pattern-mixnet-anonymity.md | 2 +- patterns/pattern-modular-privacy-stack.md | 4 +- patterns/pattern-mpc-custody.md | 5 +- .../pattern-native-account-abstraction.md | 4 +- patterns/pattern-network-anonymity.md | 4 +- patterns/pattern-noir-private-contracts.md | 4 +- patterns/pattern-oif.md | 2 +- patterns/pattern-onion-routing.md | 2 +- ...rn-permissioned-ledger-interoperability.md | 4 +- patterns/pattern-permissionless-spend-auth.md | 1 - patterns/pattern-plasma-stateless-privacy.md | 9 +- patterns/pattern-privacy-l2s.md | 4 +- rfps/rfp-benchmark-dashboard.md | 4 +- 25 files changed, 50 insertions(+), 210 deletions(-) delete mode 100644 patterns/pattern-l2-privacy-evaluation.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 449f645..1f3d90d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,7 +40,6 @@ All notable changes to the IPTF Map are documented here. - feat(pattern): Private Shared State split into [co-SNARKs](patterns/pattern-private-shared-state-cosnark.md), [FHE](patterns/pattern-private-shared-state-fhe.md), [TEE](patterns/pattern-private-shared-state-tee.md) — each with distinct CROPS profile and trust model ([#104](https://github.com/ethereum/iptf-map/issues/104)) - feat(pattern): Enhanced [Hybrid TEE + ZK Settlement](patterns/pattern-tee-zk-settlement.md) with trust framework, TEE API surface, stealth address design, anti-pattern table, and PoC learnings ([#79](https://github.com/ethereum/iptf-map/issues/79)) - feat(pattern): [Compliance Monitoring](patterns/pattern-compliance-monitoring.md) - Transaction screening with privacy-preserving audit trails ([#73](https://github.com/ethereum/iptf-map/pull/73)) -- feat(pattern): [L2 Privacy Evaluation Framework](patterns/pattern-l2-privacy-evaluation.md) - Methodology for institutions to compare privacy L2s (PR-011) - feat(pattern): [Cross-chain Privacy Bridge](patterns/pattern-cross-chain-privacy-bridge.md) - Bridge assets between chains while preserving privacy - feat(pattern): [Stateless Plasma Privacy](patterns/pattern-plasma-stateless-privacy.md) - Client-side proving with minimal on-chain footprint (Intmax-style) - feat(pattern): [vOPRF Nullifiers](patterns/pattern-voprf-nullifiers.md) - Threshold vOPRF-based nullifier generation for credentials/signals ([#61](https://github.com/ethereum/iptf-map/pull/61)) diff --git a/patterns/pattern-co-snark.md b/patterns/pattern-co-snark.md index 5cc9e6e..9add84b 100644 --- a/patterns/pattern-co-snark.md +++ b/patterns/pattern-co-snark.md @@ -100,4 +100,3 @@ Threat model: - [Collaborative zk-SNARKs (Ozdemir & Boneh, 2021)](https://eprint.iacr.org/2021/1530.pdf) - [TACEO private proof delegation](https://core.taceo.io/articles/private-proof-delegation/) -- [TACEO Merces vendor page](../vendors/taceo-merces.md) diff --git a/patterns/pattern-compliance-monitoring.md b/patterns/pattern-compliance-monitoring.md index be65fd5..b9a7430 100644 --- a/patterns/pattern-compliance-monitoring.md +++ b/patterns/pattern-compliance-monitoring.md @@ -49,7 +49,7 @@ open_source_implementations: [] Enable institutions to screen private transactions for regulatory compliance (AML, sanctions, fraud) without exposing transaction details to unauthorized parties. Balance privacy preservation with auditability through selective screening approaches and tiered disclosure, so settlement can proceed under compliance controls while counterparty identities and amounts remain shielded from public view. -This is an orchestration pattern that composes primitives (viewing keys, zero-knowledge proofs, threshold KMS, attestations) into a compliance workflow. The unique contribution is the rule engine, alert pipeline, and audit trail that hold the workflow together; the underlying disclosure primitives are linked via `related_patterns`. +This is an orchestration pattern that composes primitives (viewing keys, zero-knowledge proofs, threshold KMS, attestations) into a compliance workflow. The pattern's contribution is the rule engine, alert pipeline, and audit trail that hold the workflow together; the underlying disclosure primitives are linked via `related_patterns`. ## Components @@ -74,7 +74,7 @@ This is an orchestration pattern that composes primitives (viewing keys, zero-kn Guarantees: -- Transaction details are visible only to the compliance function and authorized parties. +- Transaction details are exposed solely to the compliance function and authorized parties. - All transactions are screened against current sanctions lists and jurisdiction rules before settlement. - Screening decisions produce an immutable, timestamped audit trail suitable for regulator review. - Counterparty identities are protected from public view; disclosure is scoped to authorized auditors via viewing keys. diff --git a/patterns/pattern-cross-chain-privacy-bridge.md b/patterns/pattern-cross-chain-privacy-bridge.md index 0337218..6047b3a 100644 --- a/patterns/pattern-cross-chain-privacy-bridge.md +++ b/patterns/pattern-cross-chain-privacy-bridge.md @@ -96,7 +96,7 @@ Threat model: - Two-phase commit workflow, not instant atomic settlement. Latency depends on source finality and any challenge window. - Cost scales with the verification mechanism. zero-knowledge proofs are expensive to generate; optimistic systems impose challenge delays; custodial designs are cheap but centralized. - Reorg handling and cross-domain confusion (wrong chain ID, token mismatch) are recurring failure modes that must be guarded at the contract layer. -- Griefing through deposits that are never minted locks funds until timeout. The recovery path must be robust and well-documented. +- Griefing through deposits that are never minted locks funds until timeout. The recovery path must be clearly specified and documented. - Key and governance risks: TSS or MPC signer collusion, view-key misuse, and malicious contract upgrades each sit outside the cryptographic trust model and require operational controls. ## Example @@ -110,10 +110,10 @@ Threat model: ## Variants -- Pre-bridge mixing: Deposit through a source-chain shielded pool first, then bridge. Achieves full sender privacy at the cost of additional latency. +- Pre-bridge mixing: Deposit through a source-chain shielded pool beforehand, then bridge. Achieves sender-side privacy at the cost of additional latency. - Hub-and-spoke: Use L1 as a verification hub; multiple L2s prove deposits via the L1 bridge contract. -- Privacy-to-privacy: Both source and destination have shielded pools. Maximum privacy but verification is more complex. -- Asymmetric: Only one direction is private (for example, public L1 to private L2). +- Privacy-to-privacy: Both source and destination have shielded pools. Strongest privacy but verification is more complex. +- Asymmetric: One direction is private (for example, public L1 to private L2) while the reverse is transparent. ## See also diff --git a/patterns/pattern-dvp-erc7573.md b/patterns/pattern-dvp-erc7573.md index 3e58253..b218fce 100644 --- a/patterns/pattern-dvp-erc7573.md +++ b/patterns/pattern-dvp-erc7573.md @@ -84,7 +84,7 @@ Threat model: - Soundness of the commitment scheme binding outcome key hashes. - Non-colluding decryption oracle operators. A single operator in a centralized deployment can withhold decryption or release the wrong outcome key, breaking atomicity or liveness. - Non-censoring sequencers on both networks during the settlement window. A censored payment or settlement transaction forces the fallback to the reclaim path. -- Honest trade-setup system that generates unique, unpredictable outcome keys and distributes them correctly. Collision or replay across trades breaks the guarantee. +- Honest trade-setup system that generates distinct, unpredictable outcome keys and distributes them correctly. Collision or replay across trades breaks the guarantee. - Network-layer metadata (IP, timing, gas patterns) is out of scope. ## Trade-offs @@ -108,7 +108,7 @@ Threat model: Standard ERC-7573 provides atomic settlement but no privacy. For institutional use cases requiring confidentiality: - Threshold decryption oracle: Run the oracle with several independent operators and require a k-of-n quorum before an outcome key is released. -- Minimal on-chain trade data: Keep full trade terms (price, size, counterparties) in internal systems; on-chain, store only a trade identifier and a short reference that links back to those records. +- Minimal on-chain trade data: Keep full trade terms (price, size, counterparties) in internal systems; on-chain, store a trade identifier and a short reference that links back to those records. - Private or proof-based payment layer: Use a network or rollup for the cash leg that hides detailed balances but can provide a clear "payment completed or not completed" result for each trade identifier. These extensions do not change how the contracts decide outcomes: the asset contract still receives an outcome key and either delivers the asset or allows reclaim. diff --git a/patterns/pattern-eil.md b/patterns/pattern-eil.md index eca05d1..2bb1fb4 100644 --- a/patterns/pattern-eil.md +++ b/patterns/pattern-eil.md @@ -80,7 +80,7 @@ Guarantees: - Censorship resistance via a permissionless mempool where a single honest node is sufficient to propagate intents. - No trusted intermediaries: users execute their own calls, and disputes resolve on L1. -- Inherits the security of each underlying chain. Providers cannot steal funds, only face slashing risk. +- Inherits the security of each underlying chain. Providers cannot steal funds; misbehavior is addressed via slashing. - One signature authorizes operations across all involved chains. - Latency matches the slowest underlying chain. @@ -94,7 +94,7 @@ Threat model: ## Trade-offs -- Not suitable for contract-to-contract composability. The model is account-based only. +- Not suitable for contract-to-contract composability. The model is account-based. - ERC-4337 bundler overhead persists until EIP-7701 (Native AA) adoption. - Dispute mechanism adds complexity compared to simple bridges; wallets must track open vouchers and their dispute windows. - Requires wallet-side coordination to discover providers and construct cross-chain Merkle roots before signing. diff --git a/patterns/pattern-forced-withdrawal.md b/patterns/pattern-forced-withdrawal.md index 92660f9..f749674 100644 --- a/patterns/pattern-forced-withdrawal.md +++ b/patterns/pattern-forced-withdrawal.md @@ -50,7 +50,7 @@ When an L2 sequencer, relayer, or operator becomes unavailable, users need a uni ## Components -- Data availability source lets the user reconstruct their position. Can be L1 calldata, L1 blobs, an external DA layer, a validium DA committee, or client-side storage. +- Data availability source lets the user reconstruct their position. Can be L1 calldata, L1 blobs, an external DA Layer, a validium DA committee, or client-side storage. - L1 state-root oracle stores the last verified L2 state root. Validity rollups anchor with a zero-knowledge proof; optimistic rollups anchor after a challenge period survives. - Proof verifier contract accepts Merkle proofs (transparent systems) or zero-knowledge proofs (privacy systems) and checks them against the anchored root. - Nullifier registry records completed withdrawals to prevent double-claims. @@ -63,7 +63,7 @@ Where the data lives determines the trust assumption: | ----------------------- | ------------------------------------- | --------------------------------- | | L1 calldata | Ethereum consensus | Nothing (permanent, expensive) | | L1 blobs (EIP-4844) | Ethereum plus archival within ~18 days | Pruned if nobody archives | -| External DA layer | DA layer liveness plus economic security | DA layer offline or withholds | +| External DA Layer | DA Layer liveness plus economic security | DA Layer offline or withholds | | DA committee (validium) | Honest committee majority | Committee withholds; funds frozen | | Client-side | The user | User loses data; funds gone | @@ -106,8 +106,8 @@ Threat model: ## Trade-offs - Upgrade risk: 86% of 129 L2 projects allow instant contract upgrades without exit windows ([Ethical Risk Analysis of L2 Rollups, 2025](https://arxiv.org/html/2512.12732v1)). An escape hatch the operator can remove via upgrade provides no meaningful guarantee. L2Beat Stages requires 7-day (Stage 1) or 30-day (Stage 2) upgrade delays, minus any withdrawal delay. -- DA withholding: validium DA committees can freeze all funds by refusing to share state. External DA layers add a liveness dependency. On-chain calldata and blobs are immune but expensive. For privacy systems, data can sit on-chain yet be useless without decryption keys. -- State freshness gap: users can prove only against the most recently anchored root. Any transactions after that root are lost. Anchoring intervals range from minutes (validity rollups) to hours. +- DA withholding: validium DA committees can freeze all funds by refusing to share state. External DA Layers add a liveness dependency. On-chain calldata and blobs are immune but expensive. For privacy systems, data can sit on-chain yet be useless without decryption keys. +- State freshness gap: users can prove against the most recently anchored root, and no further. Any transactions after that root are lost. Anchoring intervals range from minutes (validity rollups) to hours. - Mass exit: everyone hits L1 at once. Gas prices spike, users with no L1 ETH cannot participate, and leveraged DeFi positions may create claims exceeding underlying bridge deposits. - Proving liveness: for privacy systems, the user must retain secrets and run a compatible prover. The prover code must be open-source, deterministically compilable, and match the L1 verifier's expected proof format. A version mismatch means funds are frozen until governance acts. Browser WASM proving works but is 5 to 15 times slower than native. @@ -119,5 +119,5 @@ A bank operates a private payment L2 for its clients. The sequencer goes offline - [L2Beat Stages Framework](https://l2beat.com/stages): maturity classification for rollup escape hatches - [A Practical Rollup Escape Hatch Design (Zircuit, 2025)](https://arxiv.org/html/2503.23986v1): resolver contracts for DeFi positions -- [L2Beat DA Risk Framework](https://forum.l2beat.com/t/the-data-availability-risk-framework/318): DA layer risk evaluation methodology +- [L2Beat DA Risk Framework](https://forum.l2beat.com/t/the-data-availability-risk-framework/318): DA Layer risk evaluation methodology - [Introducing Stages (Medium)](https://medium.com/l2beat/introducing-stages-a-framework-to-evaluate-rollups-maturity-d290bb22befe) diff --git a/patterns/pattern-hybrid-public-private-modes.md b/patterns/pattern-hybrid-public-private-modes.md index e8f6409..3ed9019 100644 --- a/patterns/pattern-hybrid-public-private-modes.md +++ b/patterns/pattern-hybrid-public-private-modes.md @@ -59,8 +59,8 @@ Allow institutions to select public or private execution mode on a per-transacti ## Protocol -1. [operator] Configure policy rules covering counterparty whitelist, asset thresholds, and jurisdictional routing. -2. [operator] When a trade arrives, the policy engine evaluates rules and assigns each leg to public or private execution. +1. [operator] Publish policy rules (counterparty whitelist, asset thresholds, jurisdictional routing) to the on-chain policy contract through governed, auditable change controls. +2. [contract] When a trade arrives, the on-chain policy contract evaluates rules and assigns each leg to public or private execution. Routing is deterministic and not subject to unilateral operator override. 3. [user] Prepare assets in the appropriate environment. Public legs stay on the transparent chain; private legs are shielded into a private pool or bridged to a privacy L2. 4. [contract] Execute legs in parallel or sequence. Each leg runs in its assigned environment; private legs generate zero-knowledge proofs or use FHE, public legs execute standard transfers. 5. [contract] Coordinate cross-mode settlement via ERC-7573 outcome keys or commit-and-prove so both legs settle atomically or both fail. @@ -97,5 +97,4 @@ A bank sells a tokenized bond (public asset leg on L1) to a counterparty for a s ## See also -- [Private Bonds Approach](../approaches/approach-private-bonds.md) - [ERC-7573 specification](https://eips.ethereum.org/EIPS/eip-7573) diff --git a/patterns/pattern-icma-bdt-data-model.md b/patterns/pattern-icma-bdt-data-model.md index 3c06fea..a462fb8 100644 --- a/patterns/pattern-icma-bdt-data-model.md +++ b/patterns/pattern-icma-bdt-data-model.md @@ -62,9 +62,9 @@ Use the ICMA Bond Data Taxonomy as the canonical schema for bond terms and lifec Guarantees: -- Interoperable, regulator-friendly bond data across platforms. -- Easier proofs and attestations over common fields without bespoke per-issuer schemas. -- Clean baseline for composing with hash-anchored registries and zero-knowledge disclosure patterns. +- Interoperable bond data representation across platforms and supervisory workflows. +- Common fields that reduce per-issuer schema translation for proofs and attestations. +- Baseline compatibility with hash-anchored registries and zero-knowledge disclosure patterns. Threat model: diff --git a/patterns/pattern-l2-encrypted-offchain-audit.md b/patterns/pattern-l2-encrypted-offchain-audit.md index 75de5fb..4882219 100644 --- a/patterns/pattern-l2-encrypted-offchain-audit.md +++ b/patterns/pattern-l2-encrypted-offchain-audit.md @@ -51,12 +51,12 @@ open_source_implementations: ## Intent -Run settlement on a low-cost L2, publish only commitments and hashes on chain, and keep the full transaction facts in an append-only encrypted log off chain. Integrity is anchored by periodic Merkle roots submitted on chain. Regulators and auditors receive scoped decryption keys or predicate proofs. Delivery-versus-payment is expressed through an atomic settlement standard. +Run settlement on a low-cost L2, publish commitments and hashes on-chain, and keep the full transaction facts in an append-only encrypted off-chain log. Integrity is anchored by periodic Merkle roots submitted on-chain. Regulators and auditors receive scoped decryption keys or predicate proofs. Delivery-versus-payment is expressed through an atomic settlement standard. ## Components - On-chain audit contract that accepts `AuditCommit(bytes32)` entries and records hourly Merkle roots over the off-chain log. -- Append-only encrypted log, replicated across regions, storing per-trade records keyed by a content address. +- Append-only encrypted off-chain log, replicated across regions, storing per-trade records keyed by a content address. - Per-trade symmetric key, wrapped to a threshold set of authorities so that disclosure requires a quorum rather than a single custodian. - Atomic settlement contract implementing cross-leg delivery-versus-payment over cash and asset legs. - Access-logging attestations emitted on chain whenever a scoped key is issued or used. @@ -74,7 +74,7 @@ Run settlement on a low-cost L2, publish only commitments and hashes on chain, a Guarantees: -- Public observers see only commitments and hashes; amounts, identities, and positions remain off chain. +- Public observers see commitments and hashes; amounts, identities, and positions remain off-chain. - Merkle anchoring makes the log tamper-evident: any silent rewrite breaks the on-chain root. - Atomic delivery-versus-payment prevents one-sided settlement failure. - Disclosure is scoped and logged, so access is auditable after the fact. @@ -95,7 +95,7 @@ Threat model: ## Example -A dealer sells a bond to an asset manager on the L2. The chain records only the commitment and the hourly Merkle root; full trade details sit encrypted in the log. Delivery-versus-payment finalizes atomically on chain. The national supervisor later receives a 24-hour scoped key for that record, and the issuance is attested on chain so the disclosure is itself auditable. +A dealer sells a bond to an asset manager on the L2. The chain records the commitment and the hourly Merkle root; full trade details sit encrypted in the log. Delivery-versus-payment finalizes atomically on-chain. The national supervisor later receives a 24-hour scoped key for that record, and the issuance is attested on-chain so the disclosure is itself auditable. ## See also diff --git a/patterns/pattern-l2-privacy-evaluation.md b/patterns/pattern-l2-privacy-evaluation.md deleted file mode 100644 index 563df65..0000000 --- a/patterns/pattern-l2-privacy-evaluation.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: "Pattern: L2 Privacy Evaluation Framework" -status: draft -maturity: concept -type: standard -layer: L2 -last_reviewed: 2026-04-22 - -works-best-when: - - Multiple privacy L2s must be compared for an institutional deployment decision. - - Throughput, security, and censorship resistance have to be placed side by side across heterogeneous architectures. - - A consistent, sourced methodology is needed so that procurement and risk teams can review the same evidence. -avoid-when: - - The L2 under review has no privacy features; use a general L2 scorecard instead. - - A single vendor is already chosen and only vendor docs need verification. - -context: both -context_differentiation: - i2i: "Between institutions the framework is used by procurement, risk, and ops teams to weigh counterparty-aligned criteria such as force-inclusion SLAs, compliance features, and DA trust assumptions. Both sides can cross-review the filled table." - i2u: "For user-facing deployments the framework surfaces asymmetries that matter to end users: client proving cost, availability of forced exits without operator cooperation, and whether disclosure can be compelled unilaterally by the operator." - -crops_profile: "n/a" - -post_quantum: - risk: low - vector: "The framework itself is a methodology, not a cryptographic primitive. One of its rows (`PQ Security`) flags HNDL exposure in the evaluated systems." - mitigation: "Encourage each system to report post-quantum readiness in its row, and re-evaluate as systems migrate proof systems." - -standards: [] - -related_patterns: - see_also: [pattern-privacy-l2s, pattern-hybrid-public-private-modes, pattern-shielding, pattern-forced-withdrawal] - -open_source_implementations: - - url: https://github.com/l2beat/l2beat - description: "L2Beat open dataset and risk methodology used as a baseline for independently verified metrics" - language: TypeScript ---- - -## Intent - -Give institutions a vendor-neutral, sourced methodology for comparing privacy-preserving L2 solutions across performance and cost, privacy and Data Availability, and security and governance. The framework defines a common workload so that self-reported metrics can be placed next to independent benchmarks on the same axes. - -> Note: this card is an evaluation framework, not a reusable privacy primitive. `pattern-privacy-l2s` is the actual L2 pattern; this one documents how to compare privacy L2s. Candidate for relocation to `approaches/` or a methodology section in a follow-up. - -## Components - -- Self-reported metric sheets collected from each L2 team, with a source link per cell. -- Independent benchmarks and risk reviews used to cross-check the self-reported values. -- A standardized workload (Simple Value Transfer) that fixes what a transaction means across heterogeneous architectures. -- A disclosure convention that records what each metric measures, what is excluded, and whether a value is `Pending` or `N/A`. - -## Protocol - -1. [evaluator] Adopt Simple Value Transfer as the baseline workload. -2. [evaluator] Request each L2 team to fill the three evaluation tables (performance, privacy and DA, security and governance). -3. [evaluator] Require a source link for every claim (benchmark run, docs page, or paper). -4. [evaluator] Mark `Pending` where data is missing and `N/A` where the metric does not apply to that architecture. -5. [evaluator] Produce the comparative view; highlight trade-offs that matter for the target use case. -6. [evaluator] Re-run the exercise on hard forks, client updates, or when a new benchmark is published. - -## Evaluation criteria - -### 1. Performance and cost - -| Metric | Discrete metrics | -| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | -| Max Throughput | Max theoretical TPS, tested peak TPS (with benchmark link). Report TPSPublic and TPSPrivate separately | -| Transaction cost | Gas usage in `L1 gas units` + `L2 gas units` for Simple Value Transfer | -| Bridging and exit | L2 to L1 withdrawal and forced exit cost (gas units) | -| Finality time | `Soft Finality` (L2 inclusion), `Hard Finality` (L1 commitment + proof), `Challenge Period` | -| Transaction retrieval | Sync mechanism (`Trial decryption`, `Detection Keys`, `Server-side filtering`) and sync speed | - -### 2. Privacy and Data Availability - -| Metric | Discrete metrics | -| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------ | -| Level of privacy | What: `Balance`, `Sender/Receiver`, `Amount`, `Code/Function`, `Contract Bytecode`. Who sees: `Public`, `Sequencer`, `Prover` | -| DA layer | `L1 Call Data`, `L1 Data Blobs (EIP-4844)`, `External DAC` | -| DA trust | `Trustless/L1-secured`, `Trusted DAC` | -| Data posted to L1 | `Full Transaction Data`, `State Diff`, `Validity Proof Only` | -| Compliance features | `Incoming Viewing Key`, `Outgoing Viewing Key`, `Full History Viewing Key` | -| Privacy trust model | Base: `Cryptographic`, `Threshold (MPC/FHE)`. Collusion threshold: m-of-n | -| Network privacy | RPC privacy options (`Tor/I2P`, `Oblivious HTTP`, `Mixnet`) | - -### 3. Security and governance - -| Metric | Discrete metrics | -| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Sequencer decentralization | `Centralized`, `Permissioned Set`, `Decentralized Auction`, `Based (L1 Sequencing)` | -| Censorship resistance | Mechanism: `Force inclusion`, `Escape Hatch`, `Council`. User burden: `Stateless`, `Merkle Witness`, `Full State Reconstruction`. Latency: `Immediate`, `Challenge Period` | -| Prover mechanism | Access: `Whitelist`, `Permissionless`. System: `Plonk`, `Stark`, `FHE`, `Groth16` | -| Upgrade process | Governance: `Multisig (m-of-n)`, `Immutable`, `DAO Vote`. Timelock: delay in days or hours | -| Client-side requirements | Client proving: `Yes`/`No`. Features: `Mobile Proving`, `Trusted Delegation`, `Blind Delegation` | -| Finality security | `Validity (ZK)`, `Optimistic (Fraud Proofs)` | -| Proof system setup | `Trusted Ceremony`, `Transparent` | -| Programmability | Language: `EVM/Solidity`, `DSL`, `WASM`. Deployment: `Permissionless`, `Whitelisted` | -| PQ security | Susceptible to HNDL attacks? (`Yes`/`No`) | - -## Simple Value Transfer - -A protocol-native payment where a sender transfers an ERC-20 amount to a single recipient, resulting in a valid state transition. TPSPublic measures transfer semantics that are publicly observable (L2 inclusion plus validity). TPSPrivate measures a full privacy mode that hides sender, recipient, and amount as applicable; optional features are excluded unless they are mandatory in the protocol. Features excluded when reporting TPS must not be implicitly assumed elsewhere. The definition does not equalize DA models, finality, confirmation UX, compliance features, or off-chain coordination. - -## Guarantees & threat model - -Guarantees: - -- Consistent comparison criteria across heterogeneous L2 architectures. -- Separation of self-reported metrics from independently verified metrics. -- Clear visibility into what each system hides and from whom. -- Traceable claims: every metric requires a source. - -Threat model: - -- Self-reported metrics may be optimistic; the source link is what anchors them. -- Some systems do not map cleanly to every row; the `N/A` marker is load-bearing. -- Criteria drift over time; periodic re-evaluation is required. - -## Trade-offs - -- The exercise is labor-intensive; automation via a benchmark pipeline helps. -- Architectural heterogeneity makes equal-weight scoring misleading; use the tables as input to a weighted decision, not an output score. -- Frozen snapshots age quickly; timestamp every filled table and link back to source commits where possible. - -## Targeted systems - -Privacy L2s currently in scope: Aztec, Miden, Intmax, Prividium, Scroll Cloak, EY Nightfall. The framework also applies to privacy app layers on existing chains (shielded pools, enterprise privacy layers, FHE coprocessors), which share DA but not sequencer assumptions. - -## Results snapshot - -Results below are drawn from public documentation and independent sources. Empty cells indicate data not yet publicly available; each published snapshot must be timestamped. - -| Protocol | Deployment | Privacy model | Proof system | DA | Client proving | Censorship resistance | -| :--------------- | :----------- | :----------------- | :----------------- | :---------------------- | :---------------------- | :-------------------- | -| Aztec | Public L2 | Cryptographic (ZK) | UltraHonk | L1 Blobs | Yes (heavy) | Escape Hatch | -| Miden | Public L2 | Cryptographic (ZK) | STARK (Winterfell) | L1 Blobs | Yes (can be delegated) | TBD | -| Intmax | Public L2 | Cryptographic (ZK) | Plonk/Gnark | Stateless (Client-Side) | Yes (light) | Force Inclusion | -| Prividium | AppChain SDK | Cryptographic (ZK) | Boojum/Plonk | External (Private DB) | No (server) | Operator-dependent | -| Scroll Cloak | AppChain SDK | Cryptographic (ZK) | Scroll zkEVM | Host chain | No (prover service) | Force Exit to host | -| EY Nightfall | AppChain SDK | Cryptographic (ZK) | UltraPlonk | L1 Call Data | Yes | TBD | - -AppChain SDKs have deployment-dependent assumptions (sequencer, DA, governance) that vary by operator. Public L2s offering hybrid modes (Aztec, Miden) let the developer choose between a public account model and a private UTXO note model; stateless or validium designs (Intmax, Prividium, Scroll Cloak) hide balances and transfer data by default. - -Snapshot last refreshed 2026-01-27. Sources: [L2Beat](https://l2beat.com/), [Aztec Docs](https://docs.aztec.network/), [Miden VM](https://0xmiden.github.io/miden-vm/), [Intmax](https://intmax.io/), [Intmax2 Paper](https://eprint.iacr.org/2023/1082.pdf), [Prividium Docs](https://docs.zksync.io/zk-stack/prividium), [Cloak Docs](https://scroll-tech.github.io/cloak-documentation/), [Nightfall_4](https://github.com/EYBlockchain/nightfall_4_CE). - -## Example - -An OTC settlement team filters the table for cryptographic privacy, requires viewing keys for audit support, compares client proving cost against trust assumptions, and reviews censorship-resistance SLAs before choosing between an AppChain SDK and a public privacy L2. - -## See also - -- [RFP: Living Benchmark Dashboard](../rfps/rfp-benchmark-dashboard.md) - automated benchmark pipeline. -- [L2Beat](https://l2beat.com/) - independent L2 risk analysis. -- [Post-Quantum Threats](../domains/post-quantum.md) diff --git a/patterns/pattern-lean-ethereum.md b/patterns/pattern-lean-ethereum.md index 9c82f30..4fe5170 100644 --- a/patterns/pattern-lean-ethereum.md +++ b/patterns/pattern-lean-ethereum.md @@ -77,7 +77,7 @@ Guarantees: - Post-quantum resilience for the core signature layer. - Lower barriers to solo validation, improving validator decentralization. - Light-client verification of full consensus rules on minimal hardware. -- Clear scope: consensus only; execution-layer scaling and privacy are handled by separate tracks. +- Clear scope: limited to consensus; execution-layer scaling and privacy are handled by separate tracks. Threat model: @@ -91,12 +91,12 @@ Threat model: - Multi-year horizon with heavy dependence on open research questions across cryptography, proof systems, and networking. - Single bundled fork means a failure in one component delays the entire upgrade. -- Consensus-only scope: does not address execution-layer scaling or transaction privacy. +- Consensus-scoped: does not address execution-layer scaling or transaction privacy. - Coordination across many client teams adds engineering overhead but also resilience. ## Example -A consumer-grade laptop runs a solo validator at a stake threshold around 1 ETH. A minimal zkVM compresses committee signatures off chain into a single proof that any node verifies in milliseconds. The network operates at roughly four-second slots with a fast-finality variant under evaluation. A mobile phone verifies the full consensus rules independently. +A consumer-grade laptop runs a solo validator at a stake threshold around 1 ETH. A minimal zkVM compresses committee signatures off-chain into a single proof that any node verifies in milliseconds. The network operates at roughly four-second slots with a fast-finality variant under evaluation. A mobile phone verifies the full consensus rules independently. ## See also diff --git a/patterns/pattern-mixnet-anonymity.md b/patterns/pattern-mixnet-anonymity.md index ec1027a..18d5549 100644 --- a/patterns/pattern-mixnet-anonymity.md +++ b/patterns/pattern-mixnet-anonymity.md @@ -55,7 +55,7 @@ open_source_implementations: ## Intent -Hide who is sending a transaction or querying state by routing messages through a network of mix nodes that batch, delay, reorder, and pad traffic with cover messages. Mixnets provide stronger sender anonymity than onion routing against global passive adversaries because timing correlation is defeated by design, at the cost of higher latency and bandwidth overhead. +Hide who is sending a transaction or querying state by routing messages through a network of mix nodes that batch, delay, reorder, and pad traffic with cover messages. Mixnets can provide stronger sender anonymity than onion routing against global passive adversaries by reducing timing-correlation leakage, at the cost of higher latency and bandwidth overhead. ## Components diff --git a/patterns/pattern-modular-privacy-stack.md b/patterns/pattern-modular-privacy-stack.md index 9c3b522..db4bf61 100644 --- a/patterns/pattern-modular-privacy-stack.md +++ b/patterns/pattern-modular-privacy-stack.md @@ -41,7 +41,7 @@ standards: [ERC-7573, ERC-3643, EIP-4844, EAS] related_patterns: composes_with: [pattern-privacy-l2s, pattern-commit-and-prove, pattern-dvp-erc7573, pattern-regulatory-disclosure-keys-proofs, pattern-tee-based-privacy, pattern-l2-encrypted-offchain-audit] - see_also: [pattern-shielding, pattern-l2-privacy-evaluation] + see_also: [pattern-shielding] sub_patterns: - name: "Data layer" @@ -55,7 +55,7 @@ sub_patterns: crops_summary: "Hardware trust; mitigates prover cost but introduces vendor attestation dependency" - name: "Settlement layer" pattern: pattern-dvp-erc7573 - crops_summary: "Atomic cross-chain settlement anchored to L1 finality" + crops_summary: "Atomic DvP via outcome-key commitments and oracle-driven decryption; assumes non-colluding trade-setup oracle" - name: "Disclosure layer" pattern: pattern-regulatory-disclosure-keys-proofs crops_summary: "View keys, ZK proofs, and attestations for scoped audit access" diff --git a/patterns/pattern-mpc-custody.md b/patterns/pattern-mpc-custody.md index 91512d8..556bf02 100644 --- a/patterns/pattern-mpc-custody.md +++ b/patterns/pattern-mpc-custody.md @@ -7,7 +7,7 @@ layer: offchain last_reviewed: 2026-04-22 works-best-when: - - An institution needs regulated-grade custody for digital assets. + - An institution needs institutional custody under regulatory controls for digital assets. - Key material must never exist in one place while signing must still be quick. - Policy-based approvals (role, limit, allowlist) are required before signing. avoid-when: @@ -117,7 +117,6 @@ A bank issues a tokenized bond on Ethereum under a 2-of-3 custody policy across ## See also -- [Fireblocks](../vendors/fireblocks.md) - [FROST specification](https://datatracker.ietf.org/doc/draft-irtf-cfrg-frost/) - [CGGMP21 paper](https://eprint.iacr.org/2021/060) -- [Post-Quantum Threats](../domains/post-quantum.md) +- [Fireblocks (vendor docs)](https://www.fireblocks.com/) diff --git a/patterns/pattern-native-account-abstraction.md b/patterns/pattern-native-account-abstraction.md index 2ceaf23..cc96807 100644 --- a/patterns/pattern-native-account-abstraction.md +++ b/patterns/pattern-native-account-abstraction.md @@ -83,14 +83,14 @@ Threat model: ## Trade-offs -- Draft status: EIP-8141 is being discussed as a potential headliner for a future fork but is not finalised. Production use is not available. +- Draft status: EIP-8141 is being discussed as a candidate for a future fork but is not finalised. Production use is not available. - Migration path: wallets, dApps, indexers, and tooling must be updated. Existing EOAs need an upgrade path. - Validation code risk: custom validation logic introduces a new class of account-level vulnerabilities. Standardised, audited libraries mitigate this. - Mempool propagation: nodes need to validate frame transactions before relaying, which slightly increases propagation cost compared to legacy transactions. ## Example -- A user receives funds at a stealth address. A sponsor (or the user's main account) approves payment for the stealth account's first transaction. No relayer, no paymaster, and no on-chain link between the stealth address and the funding account. The stealth account uses passkey validation initially. Later, the user rotates validation logic to ML-DSA for post-quantum safety: same address, same funds, new signature scheme. +- A user receives funds at a stealth address. A sponsor (or the user's main account) approves payment for the stealth account's initial transaction. No relayer, no paymaster, and no on-chain link between the stealth address and the funding account. The stealth account uses passkey validation initially. Later, the user rotates validation logic to ML-DSA for post-quantum safety: same address, same funds, new signature scheme. ## See also diff --git a/patterns/pattern-network-anonymity.md b/patterns/pattern-network-anonymity.md index 2589e61..2fa6ca2 100644 --- a/patterns/pattern-network-anonymity.md +++ b/patterns/pattern-network-anonymity.md @@ -100,5 +100,5 @@ Threat model: ## See also -- [Modular Privacy Stack](pattern-modular-privacy-stack.md): where network anonymity fits in the four-layer architecture. -- [RFP: Private Reads](../rfps/rfp-private-reads.md): read-side privacy gap. +- [Tor Project documentation](https://spec.torproject.org/) +- [Nym mixnet documentation](https://nymtech.net/docs/) diff --git a/patterns/pattern-noir-private-contracts.md b/patterns/pattern-noir-private-contracts.md index 9724b42..222f93e 100644 --- a/patterns/pattern-noir-private-contracts.md +++ b/patterns/pattern-noir-private-contracts.md @@ -65,7 +65,7 @@ Give developers a privacy-focused DSL to write smart contracts that blend public - Circuit intermediate representation: backend-agnostic IR that the prover backend compiles into proving and verification keys. - Client-side prover: generates proofs for private-function executions on the user's machine (typically 8 GB RAM recommended). - Privacy rollup: private execution runtime, public execution VM, note-discovery infrastructure, and validity-proof pipeline to Ethereum L1. -- Encrypted logs: note discovery mechanism; only the holders of decryption keys can read log contents. +- Encrypted logs: note discovery mechanism readable by holders of the decryption keys. ## Protocol @@ -105,7 +105,7 @@ Threat model: - A corporate treasury shields stablecoins into a private contract, receiving private notes. - It pays a supplier privately; the client generates a zero-knowledge proof of sufficient balance and note ownership. -- The transaction emits an encrypted log; only the supplier can decrypt and discover the payment. +- The transaction emits an encrypted log that the supplier decrypts to discover the payment. - The rollup verifies the proof, updates balances in encrypted form, and includes the transaction in a batch settled to L1. Observers see that a valid transaction occurred but not amounts or parties. - The supplier can then spend the received notes privately; the treasury's remaining position stays hidden. diff --git a/patterns/pattern-oif.md b/patterns/pattern-oif.md index aaaf5cc..134ba20 100644 --- a/patterns/pattern-oif.md +++ b/patterns/pattern-oif.md @@ -1,6 +1,6 @@ --- title: "Pattern: Open Intent Framework (OIF)" -status: draft +status: ready maturity: production type: standard layer: hybrid diff --git a/patterns/pattern-onion-routing.md b/patterns/pattern-onion-routing.md index cc09880..86ae6d7 100644 --- a/patterns/pattern-onion-routing.md +++ b/patterns/pattern-onion-routing.md @@ -108,5 +108,5 @@ Threat model: ## See also -- [Network-Level Anonymity](pattern-network-anonymity.md): meta-pattern and sub-pattern comparison. - [Tor Project Arti](https://gitlab.torproject.org/tpo/core/arti) +- [Tor specification](https://spec.torproject.org/) diff --git a/patterns/pattern-permissioned-ledger-interoperability.md b/patterns/pattern-permissioned-ledger-interoperability.md index 329dcb0..c751122 100644 --- a/patterns/pattern-permissioned-ledger-interoperability.md +++ b/patterns/pattern-permissioned-ledger-interoperability.md @@ -18,13 +18,13 @@ context: i2i crops_profile: cr: none - o: no + o: partial p: partial s: low crops_context: cr: "Each ledger operator controls participation, so CR is structurally `none` for non-members. Could reach `medium` if validators join permissionlessly via bonding with protocol-enforced exit rights." - o: "Sync protocols exist as open specifications (e.g., Canton Network) but core implementations are often proprietary or tightly coupled to a vendor stack. Reaches `yes` when the full protocol and reference implementation are published under permissive or copyleft licenses." + o: "Core frameworks are open-source (DAML under Apache-2.0, Besu under Apache-2.0), and sync protocols exist as open specifications (e.g., Canton Network). However, individual ledger deployments built on these frameworks are often proprietary or tightly coupled to a vendor stack, and some runtime components (Canton Network production deployments) remain commercial. Reaches `yes` when both the protocol and a production-grade reference runtime are published under permissive or copyleft licenses." p: "Counterparty-only visibility of transaction payloads between the two transacting domains. Cross-domain messages reveal the existence of interactions. Reaches `full` with end-to-end encryption of cross-domain messages and scoped view keys for regulators." s: "Rides on each domain's local consensus and on the sync protocol's commit coordination. Reaches `high` with proven Byzantine consensus liveness under partition and honest-minority thresholds on the sync coordinator." diff --git a/patterns/pattern-permissionless-spend-auth.md b/patterns/pattern-permissionless-spend-auth.md index 7e87869..2c530f6 100644 --- a/patterns/pattern-permissionless-spend-auth.md +++ b/patterns/pattern-permissionless-spend-auth.md @@ -100,4 +100,3 @@ Threat model: ## See also - [EIP-8182 draft](https://github.com/ethereum/EIPs/pull/11373) -- [Post-Quantum Threats](../domains/post-quantum.md) diff --git a/patterns/pattern-plasma-stateless-privacy.md b/patterns/pattern-plasma-stateless-privacy.md index 8af7168..0133503 100644 --- a/patterns/pattern-plasma-stateless-privacy.md +++ b/patterns/pattern-plasma-stateless-privacy.md @@ -30,7 +30,7 @@ crops_profile: crops_context: cr: "Reaches `high` when the L1 anchor enforces forced exits via cryptographic proof-based withdrawals that bypass block producer liveness. Drops to `low` if the only withdrawal path depends on a single block producer's cooperation." o: "Reaches `yes` when the block producer software, circuit code, and client software are all published under permissive or copyleft licenses in forkable repositories." - p: "Transaction amounts, sender, and receiver are hidden from chain observers; only block commitments and per-block sender lists are visible on L1. Network-layer metadata (IP, timing against the block producer) remains out of scope." + p: "Transaction amounts, sender, and receiver are hidden from chain observers; only block commitments are visible on L1. Sender-list data stays off-chain with the block producer and included users. Network-layer metadata (IP, timing against the block producer) remains out of scope." s: "Rides on L1 security for deposit and exit, on the zero-knowledge proof system for transfer validity, and on the user's ability to preserve their own data. Reaches `high` with post-quantum hash-based ZK primitives and robust self-hosted Data Availability." post_quantum: @@ -40,7 +40,7 @@ post_quantum: visibility: counterparty: [amounts, identities] - chain: [block_commitments, sender_lists] + chain: [block_commitments] regulator: [full_tx with user-provided viewing material] public: [block_commitments] @@ -66,7 +66,7 @@ Use a stateless Plasma architecture to enable private token transfers where tran - L1 anchor contract: stores block commitments (Merkle roots of transaction hashes) and handles deposits, withdrawals, and forced exits. - Block producer: aggregates transactions, collects signatures, and posts the block commitment to L1. Stateless with respect to transaction contents. - Client-side prover: users generate ZK balance and transfer proofs locally (e.g., recursive FRI-based proofs). -- User-held Data Availability: users custody their own note and transfer history. Optional trust-minimized DA layer for redundancy. +- User-held Data Availability: users custody their own note and transfer history. Optional trust-minimized DA Layer for redundancy. - Forced-exit mechanism: L1 contract accepts exit proofs independently of the block producer, bypassing liveness failure. ## Protocol @@ -83,7 +83,7 @@ Use a stateless Plasma architecture to enable private token transfers where tran Guarantees: -- Transaction amounts, sender, and receiver are hidden from chain observers; only commitments and per-block sender lists are visible. +- Transaction amounts, sender, and receiver are hidden from chain observers; only block commitments are visible on L1. - zero-knowledge proofs ensure no double-spend or inflation without revealing transaction details. - Users control their own data; no operator can freeze specific balances if forced exit is implemented. - Funds are secured by L1; users can always exit with a valid proof. @@ -118,4 +118,3 @@ Threat model: - [Plasma original paper](https://plasma.io/) - [Plasma-free paper (eprint 2023/1670)](https://eprint.iacr.org/2023/1670) - [Intmax2 paper (eprint 2025/021)](https://eprint.iacr.org/2025/021) -- [Post-Quantum Threats](../domains/post-quantum.md) diff --git a/patterns/pattern-privacy-l2s.md b/patterns/pattern-privacy-l2s.md index abb2dd7..30362df 100644 --- a/patterns/pattern-privacy-l2s.md +++ b/patterns/pattern-privacy-l2s.md @@ -16,7 +16,7 @@ avoid-when: context: both context_differentiation: - i2i: "Institutions can absorb bridging friction and centralized-sequencer risk as known operational costs. The primary value is programmable private state: confidential contract logic, private balances with DvP hooks, and selective disclosure integrated at the protocol level. Both counterparties share a legal framework, so temporary sequencer centralization is a liveness concern, not an existential one." + i2i: "Bridging friction and centralized-sequencer risk are acceptable trade-offs when both counterparties operate within a shared legal framework. The pattern's primary value is programmable private state: confidential contract logic, private balances with DvP hooks, and selective disclosure integrated at the protocol level. Temporary sequencer centralization is a liveness concern in this context, not an existential one." i2u: "End users face asymmetric exposure to the sequencer. A centralized sequencer can unilaterally exclude user transactions; without forced withdrawal via the L1 bridge, user funds can be stranded. Permissionless sequencer selection and forced-exit guarantees are prerequisites before this pattern is safe for user-facing deployments." crops_profile: @@ -47,7 +47,7 @@ standards: [ERC-20, ERC-3643, ERC-7573] related_patterns: composes_with: [pattern-shielding, pattern-regulatory-disclosure-keys-proofs, pattern-dvp-erc7573, pattern-erc3643-rwa] alternative_to: [pattern-plasma-stateless-privacy] - see_also: [pattern-forced-withdrawal, pattern-l2-privacy-evaluation, pattern-user-controlled-viewing-keys] + see_also: [pattern-forced-withdrawal, pattern-user-controlled-viewing-keys] open_source_implementations: - url: https://github.com/AztecProtocol/aztec-packages diff --git a/rfps/rfp-benchmark-dashboard.md b/rfps/rfp-benchmark-dashboard.md index 339242b..1eb0fc8 100644 --- a/rfps/rfp-benchmark-dashboard.md +++ b/rfps/rfp-benchmark-dashboard.md @@ -29,14 +29,14 @@ Privacy L2 vendors claim 25k+ TPS, but institutions have no way to verify these - Batch operations (10, 100, 1000 txs) - Compliance proof generation - Target systems (public testnets where available): - - **Privacy L2s** (see [L2 Privacy Evaluation Pattern](../patterns/pattern-l2-privacy-evaluation.md)): + - **Privacy L2s**: - *Public L2*: Aztec, Miden, Intmax - *AppChain SDK*: Prividium, EY Nightfall, Scroll Cloak - **Privacy App Layers**: - Zama fhEVM (coprocessor) - Kaleido/Paladin (L1 privacy) - Railgun (L1 shielded pool) -- Metrics per system (see [L2 Privacy Evaluation Pattern](../patterns/pattern-l2-privacy-evaluation.md) for full criteria): +- Metrics per system: - **Performance**: Throughput (TPSPublic/TPSPrivate), latency, finality - **Cost**: Gas usage, bridging costs, forced exit costs - **Privacy**: What is hidden, from whom, trust model From f2a7772ef50be8c78a4c0f22d86f1c64d7748a90 Mon Sep 17 00:00:00 2001 From: Meyanis95 Date: Fri, 24 Apr 2026 12:43:58 +0200 Subject: [PATCH 05/10] fix(patterns): address CodeRabbit round 2 on #154 Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 2 +- approaches/approach-private-identity.md | 2 +- domains/post-quantum.md | 4 ++-- patterns/pattern-dvp-erc7573.md | 1 - patterns/pattern-eil.md | 2 +- patterns/pattern-forced-withdrawal.md | 2 +- patterns/pattern-icma-bdt-data-model.md | 8 ++++---- patterns/pattern-l2-encrypted-offchain-audit.md | 8 ++++---- patterns/pattern-lean-ethereum.md | 1 - patterns/pattern-mixnet-anonymity.md | 6 +++--- patterns/pattern-mpc-custody.md | 2 +- patterns/pattern-network-anonymity.md | 2 +- patterns/pattern-onion-routing.md | 2 +- patterns/pattern-permissioned-ledger-interoperability.md | 4 ++-- ...ivate-contracts.md => pattern-private-contract-dsl.md} | 7 +++---- patterns/pattern-zk-proof-systems.md | 2 +- vendors/aztec.md | 4 ++-- 17 files changed, 28 insertions(+), 31 deletions(-) rename patterns/{pattern-noir-private-contracts.md => pattern-private-contract-dsl.md} (96%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f3d90d..7640bab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -130,7 +130,7 @@ All notable changes to the IPTF Map are documented here. - feat(pattern): [FOCIL-EIP7805](patterns/pattern-focil-eip7805.md) ([#26](https://github.com/ethereum/iptf-map/pull/26)) - feat(pattern): [Lean Ethereum](patterns/pattern-lean-ethereum.md) ([#26](https://github.com/ethereum/iptf-map/pull/26)) - feat(pattern): [OIF](patterns/pattern-oif.md) - Optimized Integrity Framework ([#26](https://github.com/ethereum/iptf-map/pull/26)) -- feat(pattern): [Noir private contracts](patterns/pattern-noir-private-contracts.md) ([#21](https://github.com/ethereum/iptf-map/pull/21)) +- feat(pattern): [Private Contract DSL](patterns/pattern-private-contract-dsl.md) ([#21](https://github.com/ethereum/iptf-map/pull/21)) - feat(vendor): [Paladin](vendors/paladin.md) ([#19](https://github.com/ethereum/iptf-map/pull/19)) - feat(vendor): [State Labs](vendors/tx-shield.md) - Tx Shield, OpenTMP LLM, Collab-Key ([#7](https://github.com/ethereum/iptf-map/pull/7)) - feat(vendor): [Soda Labs](vendors/soda-labs.md) diff --git a/approaches/approach-private-identity.md b/approaches/approach-private-identity.md index 95783aa..611e45a 100644 --- a/approaches/approach-private-identity.md +++ b/approaches/approach-private-identity.md @@ -263,7 +263,7 @@ When sources are honest, the cryptographic layer enforces one-to-one binding. Wh - **ZK Frameworks:** [Semaphore](https://github.com/semaphore-protocol), [Noir/Barretenberg](https://docs.aztec.network/), [Circom/Groth16](https://docs.circom.io/), [Iden3](https://github.com/iden3) - **Credential Systems:** [ZKPassport](https://zkpassport.id/), [Self](https://self.xyz/), [Rarimo](https://rarimo.com/), [Anon Aadhaar](https://github.com/anon-aadhaar), [zkEmail](https://prove.email/), [TLSNotary](https://tlsnotary.org/), [POD2](https://github.com/0xPARC/pod2), [OpenAC](https://eprint.iacr.org/2026/251), [Human Passport](https://passport.human.tech/), [Holonym](https://holonym.id/) - **Validated Deployments:** ZKPassport Aztec sale (120+ countries), Anon Aadhaar, World ID (25M registrations), [OpenCerts](https://www.opencerts.io/) (2M+ certs) -- **Related Patterns:** [Private MTP Auth](../patterns/pattern-private-mtp-auth.md), [ZK-KYC/ML + ONCHAINID](../patterns/pattern-zk-kyc-ml-id-erc734-735.md), [zk-TLS](../patterns/pattern-zk-tls.md), [Selective Disclosure](../patterns/pattern-regulatory-disclosure-keys-proofs.md), [co-SNARK](../patterns/pattern-co-snark.md), [Verifiable Attestation](../patterns/pattern-verifiable-attestation.md), [vOPRF Nullifiers](../patterns/pattern-voprf-nullifiers.md), [Stealth Addresses](../patterns/pattern-stealth-addresses.md), [ERC-3643 RWA](../patterns/pattern-erc3643-rwa.md), [Compliance Monitoring](../patterns/pattern-compliance-monitoring.md), [Network Anonymity](../patterns/pattern-network-anonymity.md), [Noir Private Contracts](../patterns/pattern-noir-private-contracts.md), [Privacy L2s](../patterns/pattern-privacy-l2s.md), [TEE-Based Privacy](../patterns/pattern-tee-based-privacy.md) +- **Related Patterns:** [Private MTP Auth](../patterns/pattern-private-mtp-auth.md), [ZK-KYC/ML + ONCHAINID](../patterns/pattern-zk-kyc-ml-id-erc734-735.md), [zk-TLS](../patterns/pattern-zk-tls.md), [Selective Disclosure](../patterns/pattern-regulatory-disclosure-keys-proofs.md), [co-SNARK](../patterns/pattern-co-snark.md), [Verifiable Attestation](../patterns/pattern-verifiable-attestation.md), [vOPRF Nullifiers](../patterns/pattern-voprf-nullifiers.md), [Stealth Addresses](../patterns/pattern-stealth-addresses.md), [ERC-3643 RWA](../patterns/pattern-erc3643-rwa.md), [Compliance Monitoring](../patterns/pattern-compliance-monitoring.md), [Network Anonymity](../patterns/pattern-network-anonymity.md), [Private Contract DSL](../patterns/pattern-private-contract-dsl.md), [Privacy L2s](../patterns/pattern-privacy-l2s.md), [TEE-Based Privacy](../patterns/pattern-tee-based-privacy.md) - **Prior Art:** [Vitalik zk-identity framework](https://vitalik.eth.limo/general/2025/06/28/zkid.html), [Human](https://human.tech/) (plural-identity scoring), [zk-creds (Rosenberg et al., 2023)](https://eprint.iacr.org/2022/878), [zk-promises (Shih et al., 2025)](https://eprint.iacr.org/2024/1260), [PLUME (Aayush Gupta, ERC-7524)](https://aayushg.com/thesis.pdf) - **PoC:** [Resilient Private Identity](https://github.com/ethereum/iptf-pocs/tree/master/pocs/private-identity/resilient-private-identity) - **Vendors:** [Aztec](../vendors/aztec.md), [Miden](../vendors/miden.md), [Zama](../vendors/zama.md), [Fhenix](../vendors/fhenix.md), [TACEO](../vendors/taceo-merces.md), [Privacy Pools](../vendors/privacypools.md), [Chainlink ACE](../vendors/chainlink-ace.md), [EY](../vendors/ey.md) diff --git a/domains/post-quantum.md b/domains/post-quantum.md index 8c4ac64..3734b05 100644 --- a/domains/post-quantum.md +++ b/domains/post-quantum.md @@ -81,7 +81,7 @@ Ethereum inherits PQ transport encryption for some surfaces (Go 1.24 ships hybri | Surface | Broken Primitive | Solution Path | Status | Pattern | | ------------------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------- | -| Note discovery / viewing keys | EC-based key derivation | ML-KEM (outside ZK circuit) + OMR | Tractable | [Shielding](../patterns/pattern-shielding.md), [Noir Private Contracts](../patterns/pattern-noir-private-contracts.md) | +| Note discovery / viewing keys | EC-based key derivation | ML-KEM (outside ZK circuit) + OMR | Tractable | [Shielding](../patterns/pattern-shielding.md), [Private Contract DSL](../patterns/pattern-private-contract-dsl.md) | | Proven-correct encryption to auditor | ElGamal (EC scalar mul) | Lattice PKE outside circuit + Poseidon symmetric encryption inside circuit (detect-and-flag model) | Partial | [Regulatory Disclosure](../patterns/pattern-regulatory-disclosure-keys-proofs.md) | | Protocol-enforced decryptability | Proving lattice PKE in-circuit | Field mismatch (q=3,329 vs BN254); simpler than full ML-KEM but still expensive | Unsolved | — | @@ -98,7 +98,7 @@ Ethereum inherits PQ transport encryption for some surfaces (Go 1.24 ships hybri | [PSI-DH](../patterns/pattern-private-set-intersection-dh.md) | DDH / commutative encryption | Medium | Lattice-based PSI | | [MPC Custody](../patterns/pattern-mpc-custody.md) | Threshold ECDSA/EdDSA | Low | ML-DSA / hash-based threshold | | [TEE Key Manager](../patterns/pattern-tee-key-manager.md) | ECDSA/BLS signing | Low | PQ signing in TEE | -| [Noir Private Contracts](../patterns/pattern-noir-private-contracts.md) | Barretenberg (PLONK) | High | Hash-based commitments / STARKs | +| [Private Contract DSL](../patterns/pattern-private-contract-dsl.md) | Barretenberg (PLONK) | High | Hash-based commitments / STARKs | | [Private Shared State (co-SNARK)](../patterns/pattern-private-shared-state-cosnark.md) | Groth16 | Medium | co-STARK alternatives | | [TEE+ZK Settlement](../patterns/pattern-tee-zk-settlement.md) | Groth16/PLONK | Medium | STARKs | | [co-SNARK](../patterns/pattern-co-snark.md) | co-SNARK (Groth16-based) | Medium | co-STARK | diff --git a/patterns/pattern-dvp-erc7573.md b/patterns/pattern-dvp-erc7573.md index b218fce..9be799e 100644 --- a/patterns/pattern-dvp-erc7573.md +++ b/patterns/pattern-dvp-erc7573.md @@ -116,4 +116,3 @@ These extensions do not change how the contracts decide outcomes: the asset cont ## See also - [ERC-7573 specification](https://ercs.ethereum.org/ERCS/erc-7573) -- [Private Trade Settlement approach](../approaches/approach-private-trade-settlement.md) diff --git a/patterns/pattern-eil.md b/patterns/pattern-eil.md index 2bb1fb4..d9228b2 100644 --- a/patterns/pattern-eil.md +++ b/patterns/pattern-eil.md @@ -31,7 +31,7 @@ crops_context: cr: "Reaches `high` through a permissionless P2P UserOp mempool where a single honest node is sufficient to propagate intents. Drops if the mempool becomes operator-gated or if liquidity providers coordinate to ignore specific users." o: "Open specifications (ERC-4337, EIP-7701, RIP-7859) and open-source SDKs. Any actor can register as a liquidity provider by staking on L1, and users can bypass providers by paying gas directly." p: "No privacy. Token amounts, gas limits, and call targets are visible pre-execution across all involved chains. Could reach `partial` by integrating encrypted UserOps via threshold encryption where cross-L2 intents remain encrypted until ordering is finalized." - s: "Inherits the security of each underlying chain. Liquidity providers face L1 slashing on misbehavior, so user funds cannot be stolen, only face short-term delays. An 8-day unstake window bounds the economic risk window." + s: "Inherits the security of each underlying chain. Liquidity providers face L1 slashing on misbehavior, so user funds cannot be stolen; worst case is a short-term delay. An 8-day unstake window bounds the economic risk window." post_quantum: risk: medium diff --git a/patterns/pattern-forced-withdrawal.md b/patterns/pattern-forced-withdrawal.md index f749674..a0f0877 100644 --- a/patterns/pattern-forced-withdrawal.md +++ b/patterns/pattern-forced-withdrawal.md @@ -26,7 +26,7 @@ crops_profile: s: high crops_context: - cr: "Reaches `high` only when the escape-hatch contract has meaningful upgrade delays (Stage 1 or higher, 7+ days). Instant upgrades let the operator remove the hatch, which invalidates the rating entirely. DA withholding and proving liveness are liveness constraints documented under Trade-offs; they do not change the CR score, which measures whether a single party can exclude a user at the protocol level." + cr: "Reaches `high` when the escape-hatch contract has meaningful upgrade delays (Stage 1 or higher, 7+ days). Instant upgrades let the operator remove the hatch, which invalidates the rating entirely. DA withholding and proving liveness are liveness constraints documented under Trade-offs; they do not change the CR score, which measures whether a single party can exclude a user at the protocol level." o: "Forced-withdrawal contracts are typically open-source and verifiable. Users can run their own prover and submit directly to L1. Proving-key hosting for Groth16 constructions is a soft dependency: if hosting goes offline, users may struggle to generate valid proofs." p: "For privacy systems, the zero-knowledge proof hides which commitment is withdrawn; no KYC disclosure or transaction history reveal is needed. The L1 withdrawal still reveals that an exit happened at a specific time for a specific amount." s: "Rides on the soundness of the proof system, correctness of the verifier, and honest state-root anchoring on L1. For optimistic constructions, a 7-day challenge window plus honest challengers are required. PQ exposure applies to ZK systems over BN254." diff --git a/patterns/pattern-icma-bdt-data-model.md b/patterns/pattern-icma-bdt-data-model.md index a462fb8..f798c01 100644 --- a/patterns/pattern-icma-bdt-data-model.md +++ b/patterns/pattern-icma-bdt-data-model.md @@ -16,14 +16,14 @@ context: i2i crops_profile: cr: none - o: yes - p: full + o: no + p: none s: high crops_context: cr: "Schema governance sits with a single standards body (ICMA). Could reach `medium` if the schema is published as a permissionless open registry with attestation-anchored contributions and no approval gate." - o: "Open specification, publicly documented. Implementations can reuse the schema without licensing barriers, though schema evolution is gated by the standards body." - p: "Schema itself contains no participant data; only field definitions. Raw bond data stays off-chain, with only hashes anchored on-chain, so the pattern does not expose confidential details." + o: "Specification is publicly documented but governance is centralized under ICMA; no explicit open license or forkability guarantee is established. Reaches `partial` or `yes` if the schema is published under a permissive or copyleft license with a forkable reference implementation." + p: "The taxonomy standardizes structure only; it is not a confidentiality primitive. Privacy outcomes depend entirely on companion patterns (selective disclosure, ZK proofs, controlled access, hash anchoring)." s: "Rides on the correctness of off-chain validators and the integrity of hash anchoring. Well-defined schemas reduce integration errors and make regulator reconciliation straightforward." post_quantum: diff --git a/patterns/pattern-l2-encrypted-offchain-audit.md b/patterns/pattern-l2-encrypted-offchain-audit.md index 4882219..15ec44b 100644 --- a/patterns/pattern-l2-encrypted-offchain-audit.md +++ b/patterns/pattern-l2-encrypted-offchain-audit.md @@ -59,13 +59,13 @@ Run settlement on a low-cost L2, publish commitments and hashes on-chain, and ke - Append-only encrypted off-chain log, replicated across regions, storing per-trade records keyed by a content address. - Per-trade symmetric key, wrapped to a threshold set of authorities so that disclosure requires a quorum rather than a single custodian. - Atomic settlement contract implementing cross-leg delivery-versus-payment over cash and asset legs. -- Access-logging attestations emitted on chain whenever a scoped key is issued or used. +- Access-logging attestations emitted on-chain whenever a scoped key is issued or used. ## Protocol -1. [user] Negotiate and match the trade off chain; optionally encrypt the routing metadata. -2. [operator] Write the encrypted record to the log, compute its commitment, and submit `AuditCommit` on chain. -3. [operator] Aggregate the window's commitments into a Merkle root and anchor it on chain at the configured cadence. +1. [user] Negotiate and match the trade off-chain; optionally encrypt the routing metadata. +2. [operator] Write the encrypted record to the log, compute its commitment, and submit `AuditCommit` on-chain. +3. [operator] Aggregate the window's commitments into a Merkle root and anchor it on-chain at the configured cadence. 4. [contract] Escrow both legs and finalize atomically through the delivery-versus-payment contract. 5. [regulator] Receive a scoped decryption key or predicate proof for a specific record; the issuance is logged through an on-chain attestation. 6. [auditor] Replay the log against the anchored roots to confirm that no record has been rewritten after the fact. diff --git a/patterns/pattern-lean-ethereum.md b/patterns/pattern-lean-ethereum.md index 4fe5170..7fece5e 100644 --- a/patterns/pattern-lean-ethereum.md +++ b/patterns/pattern-lean-ethereum.md @@ -102,4 +102,3 @@ A consumer-grade laptop runs a solo validator at a stake threshold around 1 ETH. - [Lean Roadmap](https://leanroadmap.org/) - [Lean Specification repository](https://github.com/leanEthereum/leanSpec) -- [Post-Quantum Threats](../domains/post-quantum.md) diff --git a/patterns/pattern-mixnet-anonymity.md b/patterns/pattern-mixnet-anonymity.md index 18d5549..b2e2043 100644 --- a/patterns/pattern-mixnet-anonymity.md +++ b/patterns/pattern-mixnet-anonymity.md @@ -18,7 +18,7 @@ avoid-when: context: both context_differentiation: i2i: "Between institutions the mixnet hides query patterns and transaction timing from counterparty infrastructure and from network-level observers. Both parties can adopt the same routing discipline, and the anonymity set includes other institutional traffic." - i2u: "For user-facing deployments the operator of the RPC endpoint or the wallet backend is often the adversary. The mixnet reduces the operator's ability to correlate incoming queries with specific users by disrupting timing and ordering. Protection strength depends on cover traffic volume, adoption, and route quality, none of which the user can verify unilaterally." + i2u: "For user-facing deployments the operator of the RPC endpoint or the wallet backend is often the adversary. The mixnet reduces the operator's ability to correlate incoming queries with specific users by disrupting timing and ordering. If a route or gateway censors traffic, users can switch to alternate routes/providers or fall back to direct submission (losing anonymity but preserving execution). Protection strength depends on cover traffic volume, adoption, and route quality, none of which the user can verify unilaterally." crops_profile: cr: medium @@ -27,7 +27,7 @@ crops_profile: s: medium crops_context: - cr: "Operating a mix node typically requires staking, so the node set is gated by economic participation. On-chain censorship of mix-routed transactions is no easier than for direct transactions." + cr: "Operating a mix node typically requires staking, so the node set is gated by economic participation. In I2U deployments, users retain escape paths (alternate routes/providers or direct submission) if a mix path is censored, though privacy degrades under direct fallback. On-chain censorship of mix-routed transactions is no easier than for direct transactions." o: "Core mixnet stacks are open source, but live networks have governance constraints on who can operate mix nodes and how rewards are distributed." p: "Sender-anonymity against traffic correlation is strong under sufficient cover volume. Content privacy must be handled by a separate layer; on-chain side channels also persist." s: "Resistance to correlation depends on sustained cover traffic, correct network operation, and the anonymity-set size during the mixing window." @@ -98,7 +98,7 @@ Threat model: ## Example -A compliance team at a custodian needs to query transaction histories for regulatory reporting without revealing which accounts are being monitored. Queries are routed through a five-hop mixnet where each hop batches, delays, and reorders traffic. Cover traffic keeps the RPC provider's view of query volume constant. The provider cannot determine when the custodian queried, which queries came from the same source, or how many real queries were made. Several seconds of latency per query is acceptable for batch compliance reporting. +A compliance team at a custodian needs to query transaction histories for regulatory reporting without revealing which accounts are being monitored. Queries are routed through a five-hop mixnet where each hop batches, delays, and reorders traffic. Cover traffic stabilizes the RPC provider's view of query volume. Under sufficient adoption and cover volume, the provider is less able to infer query timing, link queries to the same source, or estimate the number of real queries. Several seconds of latency per query is acceptable for batch compliance reporting. ## See also diff --git a/patterns/pattern-mpc-custody.md b/patterns/pattern-mpc-custody.md index 556bf02..d2402df 100644 --- a/patterns/pattern-mpc-custody.md +++ b/patterns/pattern-mpc-custody.md @@ -113,7 +113,7 @@ A bank issues a tokenized bond on Ethereum under a 2-of-3 custody policy across - The policy engine checks the destination allowlist and the transaction limit, then notifies compliance for approval. - Compliance approves via the dashboard; the two signing nodes run the threshold-signing protocol and emit a combined signature. - The signed transaction is broadcast; bond tokens move to the investor address. -- The audit log records the approval path, the quorum members that signed, and the resulting transaction hash. +- The audit log records the approval path, the quorum members who signed, and the resulting transaction hash. ## See also diff --git a/patterns/pattern-network-anonymity.md b/patterns/pattern-network-anonymity.md index 2fa6ca2..9dc31b9 100644 --- a/patterns/pattern-network-anonymity.md +++ b/patterns/pattern-network-anonymity.md @@ -27,7 +27,7 @@ sub_patterns: crops_summary: "Medium CR, partial privacy, medium latency. Large external anonymity set; vulnerable to global passive adversaries." - name: "Mixnet anonymity" pattern: pattern-mixnet-anonymity - crops_summary: "Medium CR, partial privacy, very high latency. Strongest resistance to traffic correlation via cover traffic." + crops_summary: "Medium CR, partial privacy, very high latency. Higher resistance to traffic correlation under cover-traffic assumptions." - name: "TEE-assisted network anonymity" pattern: pattern-tee-network-anonymity crops_summary: "Medium CR, partial privacy, low latency. Hardware trust assumption relaxes the anonymity trilemma." diff --git a/patterns/pattern-onion-routing.md b/patterns/pattern-onion-routing.md index 86ae6d7..18d0351 100644 --- a/patterns/pattern-onion-routing.md +++ b/patterns/pattern-onion-routing.md @@ -63,7 +63,7 @@ Hide who is sending transactions or querying state by routing traffic through a ## Components - Circuit of relays: three or more nodes selected from a relay directory, each holding one encryption layer. -- Layered (onion) encryption: the client wraps the message once per relay, outermost layer decryptable only by the first hop. +- Layered (onion) encryption: the client wraps the message once per relay; each hop decrypts its own layer, starting with the entry hop. - Client routing library: negotiates the circuit, applies the encryption layers, and exposes a local proxy (SOCKS5 or WASM) to the dApp or wallet. - Exit relay: decrypts the last layer and forwards the message to the destination (RPC node, mempool, .onion service). diff --git a/patterns/pattern-permissioned-ledger-interoperability.md b/patterns/pattern-permissioned-ledger-interoperability.md index c751122..4ff5d90 100644 --- a/patterns/pattern-permissioned-ledger-interoperability.md +++ b/patterns/pattern-permissioned-ledger-interoperability.md @@ -63,7 +63,7 @@ Enable atomic transactions and data exchange across distinct permissioned ledger - Permissioned ledger domains, each with its own consensus, identity set, and privacy boundary. - Synchronization protocol that coordinates commits across domains (two-phase or view-based atomic commit). -- Smart contract language with explicit participant visibility controls, so contract state is replicated only to actual stakeholders. +- Smart contract language with explicit participant visibility controls, so contract state is replicated to the relevant stakeholders. - Governance model for validator or participant node admission, rotation, and exit. - Selective disclosure mechanism for supervisors and auditors to access relevant state without full replication. @@ -82,7 +82,7 @@ Enable atomic transactions and data exchange across distinct permissioned ledger Guarantees: - Atomicity: cross-ledger operations settle consistently or abort. -- Counterparty privacy: only transacting parties see payload state; other domains observe only commitment envelopes. +- Counterparty privacy: transacting parties see payload state; other domains observe commitment envelopes. - Regulatory audit: scoped access for supervisory entities via dedicated disclosure paths. Threat model: diff --git a/patterns/pattern-noir-private-contracts.md b/patterns/pattern-private-contract-dsl.md similarity index 96% rename from patterns/pattern-noir-private-contracts.md rename to patterns/pattern-private-contract-dsl.md index 222f93e..d06c3d8 100644 --- a/patterns/pattern-noir-private-contracts.md +++ b/patterns/pattern-private-contract-dsl.md @@ -1,5 +1,5 @@ --- -title: "Pattern: Noir Private Contracts" +title: "Pattern: Private Contract DSL" status: ready maturity: production type: standard @@ -111,6 +111,5 @@ Threat model: ## See also -- [Aztec](../vendors/aztec.md) -- [Approach: Private Bonds](../approaches/approach-private-bonds.md) -- [Approach: Private Derivatives](../approaches/approach-private-derivatives.md) +- [Noir language documentation](https://noir-lang.org/) +- [Aztec protocol specification](https://docs.aztec.network/aztec/concepts) diff --git a/patterns/pattern-zk-proof-systems.md b/patterns/pattern-zk-proof-systems.md index bafe63f..12a2333 100644 --- a/patterns/pattern-zk-proof-systems.md +++ b/patterns/pattern-zk-proof-systems.md @@ -86,6 +86,6 @@ Benchmarks for Ethereum block proving workloads available at [ethproofs.org CSP ## See also - [Post-Quantum Threats](../domains/post-quantum.md) — why SNARK-to-STARK migration matters -- [Noir Private Contracts](pattern-noir-private-contracts.md) — PLONK-based ZK (PQ-vulnerable) +- [Private Contract DSL](pattern-private-contract-dsl.md) — PLONK-based ZK (PQ-vulnerable) - [Shielding](pattern-shielding.md) — proof system choice affects shielded pool PQ safety - [Plasma Stateless Privacy](pattern-plasma-stateless-privacy.md) — hash-based ZK (PQ-safe) diff --git a/vendors/aztec.md b/vendors/aztec.md index 43b27a5..0b2faab 100644 --- a/vendors/aztec.md +++ b/vendors/aztec.md @@ -14,7 +14,7 @@ It uses the **Noir** language along with the Aztec.nr framework to write smart c ## Fits with patterns -- [pattern-noir-private-contracts.md](../patterns/pattern-noir-private-contracts.md) - Noir private smart contracts +- [pattern-private-contract-dsl.md](../patterns/pattern-private-contract-dsl.md) - Noir private smart contracts - [pattern-privacy-l2s.md](../patterns/pattern-privacy-l2s.md) - Privacy-native rollup execution - [pattern-shielding.md](../patterns/pattern-shielding.md) - Shielded ERC-20 transfers and confidential balances - [pattern-shielding.md](../patterns/pattern-shielding.md) - Confidential ERC-20 transfers @@ -29,7 +29,7 @@ It uses the **Noir** language along with the Aztec.nr framework to write smart c - Hybrid State Model - Private state (UTXO-based) is managed by the wallet on the user's device. - Public state (Account-based) is managed by the AVM (Aztec Virtual Machine) on nodes. -- Smart contracts are written in [Noir](../patterns/pattern-noir-private-contracts.md) using the Aztec.nr framework. +- Smart contracts are written in [Noir](../patterns/pattern-private-contract-dsl.md) using the Aztec.nr framework. - Proof system: Honk (UltraHonk) and UltraPlonk. Honk allows for fast recursion and removes the need for a trusted setup. - DA model: Rollup posts data to Ethereum L1 using EIP-4844 Blobs. - Settlement: Decentralized sequencers; L2 validity proofs are verified on Ethereum L1. From 58883b32e4281baa55a08fa9e530399cfc39fd31 Mon Sep 17 00:00:00 2001 From: Meyanis95 Date: Fri, 24 Apr 2026 15:55:09 +0200 Subject: [PATCH 06/10] fix(patterns): address CodeRabbit round 3 on #154 Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 3 ++- patterns/pattern-co-snark.md | 2 +- patterns/pattern-icma-bdt-data-model.md | 4 ++-- patterns/pattern-lean-ethereum.md | 2 +- patterns/pattern-modular-privacy-stack.md | 14 +++++--------- patterns/pattern-network-anonymity.md | 2 +- patterns/pattern-oif.md | 5 +++++ patterns/pattern-onion-routing.md | 6 ++---- patterns/pattern-permissionless-spend-auth.md | 2 +- patterns/pattern-privacy-l2s.md | 2 +- 10 files changed, 21 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7640bab..4a1f537 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ All notable changes to the IPTF Map are documented here. - feat(pattern): [zk-promises](patterns/pattern-zk-promises.md) -- stateful anonymous credentials with async callbacks for blind compliance enforcement ([#132](https://github.com/ethereum/iptf-map/pull/132)) - feat(pattern): [Proof of Innocence](patterns/pattern-proof-of-innocence.md) -- association set membership/exclusion proofs for compliance without surveillance ([#132](https://github.com/ethereum/iptf-map/pull/132)) - feat(approach|use-case): [Resilient Identity Continuity](use-cases/resilient-identity-continuity.md) and [added approach](approaches/approach-private-identity.md) ([#145](https://github.com/ethereum/iptf-map/pull/145)) +- refactor(pattern): rename `pattern-noir-private-contracts` to [Private Contract DSL](patterns/pattern-private-contract-dsl.md) for vendor-neutral naming ([#154](https://github.com/ethereum/iptf-map/pull/154)) ### Removed @@ -130,7 +131,7 @@ All notable changes to the IPTF Map are documented here. - feat(pattern): [FOCIL-EIP7805](patterns/pattern-focil-eip7805.md) ([#26](https://github.com/ethereum/iptf-map/pull/26)) - feat(pattern): [Lean Ethereum](patterns/pattern-lean-ethereum.md) ([#26](https://github.com/ethereum/iptf-map/pull/26)) - feat(pattern): [OIF](patterns/pattern-oif.md) - Optimized Integrity Framework ([#26](https://github.com/ethereum/iptf-map/pull/26)) -- feat(pattern): [Private Contract DSL](patterns/pattern-private-contract-dsl.md) ([#21](https://github.com/ethereum/iptf-map/pull/21)) +- feat(pattern): [Noir private contracts](patterns/pattern-private-contract-dsl.md) ([#21](https://github.com/ethereum/iptf-map/pull/21)) - feat(vendor): [Paladin](vendors/paladin.md) ([#19](https://github.com/ethereum/iptf-map/pull/19)) - feat(vendor): [State Labs](vendors/tx-shield.md) - Tx Shield, OpenTMP LLM, Collab-Key ([#7](https://github.com/ethereum/iptf-map/pull/7)) - feat(vendor): [Soda Labs](vendors/soda-labs.md) diff --git a/patterns/pattern-co-snark.md b/patterns/pattern-co-snark.md index 9add84b..d90508f 100644 --- a/patterns/pattern-co-snark.md +++ b/patterns/pattern-co-snark.md @@ -58,7 +58,7 @@ This pattern covers delegated proving for a single prover's witness. For multi-p - User or application holds the witness and wants a proof generated without exposing the witness. - Share-distribution layer splits the witness using secret-sharing (additive or Shamir) and routes shares to proving nodes. -- Distributed prover network runs the MPC protocol to jointly compute the SNARK. Each node sees only its share. +- Distributed prover network runs the MPC protocol to jointly compute the SNARK. Each node sees its share; the full witness is never reconstructed. - Coordinator sequences MPC rounds and assembles the final proof. Can be one of the proving nodes or a separate role. - Verifier checks the final proof exactly as it would check a client-side SNARK. No changes on the verification side. diff --git a/patterns/pattern-icma-bdt-data-model.md b/patterns/pattern-icma-bdt-data-model.md index f798c01..f4ab68e 100644 --- a/patterns/pattern-icma-bdt-data-model.md +++ b/patterns/pattern-icma-bdt-data-model.md @@ -18,13 +18,13 @@ crops_profile: cr: none o: no p: none - s: high + s: medium crops_context: cr: "Schema governance sits with a single standards body (ICMA). Could reach `medium` if the schema is published as a permissionless open registry with attestation-anchored contributions and no approval gate." o: "Specification is publicly documented but governance is centralized under ICMA; no explicit open license or forkability guarantee is established. Reaches `partial` or `yes` if the schema is published under a permissive or copyleft license with a forkable reference implementation." p: "The taxonomy standardizes structure only; it is not a confidentiality primitive. Privacy outcomes depend entirely on companion patterns (selective disclosure, ZK proofs, controlled access, hash anchoring)." - s: "Rides on the correctness of off-chain validators and the integrity of hash anchoring. Well-defined schemas reduce integration errors and make regulator reconciliation straightforward." + s: "Rides on the correctness of off-chain validators, registrar-mapping integrity, and hash-anchoring soundness. These operational trust points cap the pattern at `medium` in the absence of stronger controls (multi-party validation, formally specified mapping procedures). Reaches `high` when validator correctness is cryptographically enforced and mapping operations are multi-party-verified." post_quantum: risk: low diff --git a/patterns/pattern-lean-ethereum.md b/patterns/pattern-lean-ethereum.md index 7fece5e..e313dbf 100644 --- a/patterns/pattern-lean-ethereum.md +++ b/patterns/pattern-lean-ethereum.md @@ -55,7 +55,7 @@ Plan a long-range redesign of the Ethereum consensus layer, targeting a single m - Post-quantum hash-based multisignatures, with an aggregation scheme suited to large validator sets. - Minimal zkVMs used to compress aggregated signatures and consensus proofs into succinct artifacts. -- Networking upgrades: Gossipsub v2 for throughput and DOS resilience, and rateless set reconciliation to support very large validator sets. +- Networking upgrades: Gossipsub v2 for throughput and DOS resilience, and rateless set reconciliation to support large validator sets. - Lower validator thresholds in hardware, bandwidth, and stake, making solo staking accessible on commodity devices. - Formal verification tooling (Lean 4) used to prove key properties of the signature aggregation and consensus logic. - Approximately fifteen client teams implementing the specification across Rust, Zig, C, C++, Go, Java, .NET, TypeScript, Nim, and Elixir. diff --git a/patterns/pattern-modular-privacy-stack.md b/patterns/pattern-modular-privacy-stack.md index db4bf61..3adc8d9 100644 --- a/patterns/pattern-modular-privacy-stack.md +++ b/patterns/pattern-modular-privacy-stack.md @@ -20,17 +20,13 @@ context_differentiation: i2i: "Between institutions the layered model lets counterparties agree on interfaces (data references, settlement proofs, disclosure artifacts) without locking the stack to one vendor per layer. Decentralized orchestration prevents any single provider from gatekeeping settlement." i2u: "For user-facing deployments per-layer exit paths matter: a user must be able to withdraw assets even if one layer's operator becomes unresponsive. Disclosure controls should protect the user from forced correlation across layers." -crops_profile: - cr: medium - o: partial - p: partial - s: medium +crops_profile: "n/a" crops_context: - cr: "Reaches `high` when routing is permissionless and each layer offers an independent exit path. Drops when orchestration concentrates in a single operator or when a settlement layer uses permissioned sequencing." - o: "Improves to `yes` when reference implementations of each layer interface are published and orchestration logic is open source; today vendor SDKs dominate." - p: "Layer isolation contains data leaks, but cross-layer routing reveals timing and access patterns. Reaches `full` only with end-to-end encryption between layers and metadata scrubbing at routing boundaries." - s: "Depends on the weakest layer plus the orchestrator. Threshold cryptography for cross-layer key management and elimination of single-operator trust in orchestration raise this to `high`." + cr: "Inherited from sub-patterns; the meta-pattern itself does not implement CR. Overall CR is bounded by the weakest layer plus orchestration. See each sub-pattern's crops_context." + o: "Inherited from sub-patterns; the meta-pattern itself does not implement openness. Reaches `yes` when every layer's reference implementation is open source." + p: "Inherited from sub-patterns; the meta-pattern itself does not implement privacy. Cross-layer routing can leak timing and access patterns regardless of per-layer choices." + s: "Inherited from sub-patterns; the meta-pattern itself does not implement security. Depends on the weakest layer plus the orchestrator." post_quantum: risk: medium diff --git a/patterns/pattern-network-anonymity.md b/patterns/pattern-network-anonymity.md index 9dc31b9..16642c2 100644 --- a/patterns/pattern-network-anonymity.md +++ b/patterns/pattern-network-anonymity.md @@ -75,7 +75,7 @@ Pure-cryptographic approaches (onion routing, mixnets) must sacrifice at least o | Approach | Latency | Anonymity strength | Trust assumption | | --- | --- | --- | --- | | Onion routing | Moderate (100-500ms) | Strong | No single relay sees full path | -| Mixnet | High (seconds to minutes) | Strongest | Threshold mix nodes and cover traffic | +| Mixnet | High (seconds to minutes) | Higher under cover-traffic assumptions | Threshold mix nodes and cover traffic | | TEE-assisted | Low | Medium | Client TEE and server majority | ## Guarantees & threat model diff --git a/patterns/pattern-oif.md b/patterns/pattern-oif.md index 134ba20..7b6d28c 100644 --- a/patterns/pattern-oif.md +++ b/patterns/pattern-oif.md @@ -31,6 +31,11 @@ crops_context: p: "None by default. Intents are visible during solver discovery. Could reach `full` by adopting encrypted intent encoding with sealed-bid commitments via threshold encryption, revealed only after solver execution and L1 finality." s: "Medium while cross-chain atomicity depends on external settlement and oracle assumptions. Reaches `high` once settlement atomicity and oracle integrity are hardened." +post_quantum: + risk: medium + vector: "Intent signatures use ECDSA, broken by a CRQC. HNDL risk is moderate because intents can carry value-bearing commitments; however, intents are short-lived and public, limiting the harvest-now-decrypt-later window." + mitigation: "Migrate intent signing to post-quantum signatures (hash-based or lattice-based) once standardized. Settlement-contract verification paths must be updated in step." + standards: [ERC-7683] related_patterns: diff --git a/patterns/pattern-onion-routing.md b/patterns/pattern-onion-routing.md index 18d0351..71b1c07 100644 --- a/patterns/pattern-onion-routing.md +++ b/patterns/pattern-onion-routing.md @@ -51,9 +51,6 @@ open_source_implementations: - url: https://pse.dev/projects/tor-js description: "Tor-in-WASM library for browser-side onion routing from dApps (EF PSE)" language: "TypeScript, WASM" - - url: https://docs.flashbots.net/flashbots-protect/quick-start - description: "Public .onion endpoint for private transaction submission" - language: "Service" --- ## Intent @@ -85,7 +82,7 @@ Guarantees: Threat model: -- A global passive adversary able to observe both ends of a circuit can correlate traffic and deanonymise sessions. +- A global passive adversary able to observe both ends of a circuit can correlate traffic and deanonymize sessions. - Exit relays see the final unencrypted payload unless transport-layer encryption (HTTPS, .onion service) is used. - RPC providers that block exit-node IPs degrade the guarantee; pair with decentralised or P2P RPC access. - Does not hide message content. Pair with content-privacy patterns for full-stack privacy. @@ -110,3 +107,4 @@ Threat model: - [Tor Project Arti](https://gitlab.torproject.org/tpo/core/arti) - [Tor specification](https://spec.torproject.org/) +- [Flashbots Protect (.onion endpoint for private transaction submission)](https://docs.flashbots.net/flashbots-protect/quick-start) diff --git a/patterns/pattern-permissionless-spend-auth.md b/patterns/pattern-permissionless-spend-auth.md index 2c530f6..f58b834 100644 --- a/patterns/pattern-permissionless-spend-auth.md +++ b/patterns/pattern-permissionless-spend-auth.md @@ -77,7 +77,7 @@ Guarantees: - Unified anonymity set. All auth methods share one note tree; spends using different methods are indistinguishable on-chain. - Auth method privacy. Observers cannot determine which inner circuit was used. - No fund migration. Changing or adding auth methods does not require moving notes. -- Ownership isolation. A bug in an inner circuit cannot forge ownership; it can produce false authorization claims but nothing else. The outer circuit independently enforces ownership, value conservation, and nullifier correctness. +- Ownership isolation. A bug in an inner circuit can produce false authorization claims but cannot forge ownership: the outer circuit independently enforces ownership, value conservation, and nullifier correctness. The blast radius of an inner-circuit flaw is therefore limited to auth-method bypass within the affected circuit, not fund theft. Threat model: diff --git a/patterns/pattern-privacy-l2s.md b/patterns/pattern-privacy-l2s.md index 30362df..23461d1 100644 --- a/patterns/pattern-privacy-l2s.md +++ b/patterns/pattern-privacy-l2s.md @@ -117,7 +117,7 @@ Threat model: ## Example - Bond issuance and secondary trading on native shielded notes. -- An FHE-based L2 running a private credit risk model where inputs remain encrypted end-to-end and only the final attestation is revealed to the counterparty. +- An FHE-based L2 running a private credit risk model where inputs remain encrypted end-to-end and the final attestation is revealed to the counterparty. ## See also From 79701e6da591440869682f7443581f624c16cb68 Mon Sep 17 00:00:00 2001 From: Meyanis95 Date: Fri, 24 Apr 2026 18:21:28 +0200 Subject: [PATCH 07/10] fix(patterns): address CodeRabbit round 4 on #154 Co-Authored-By: Claude Opus 4.7 (1M context) --- patterns/pattern-modular-privacy-stack.md | 2 +- patterns/pattern-native-account-abstraction.md | 1 - patterns/pattern-plasma-stateless-privacy.md | 10 +++++----- patterns/pattern-privacy-l2s.md | 3 --- patterns/pattern-zk-proof-systems.md | 6 ++---- 5 files changed, 8 insertions(+), 14 deletions(-) diff --git a/patterns/pattern-modular-privacy-stack.md b/patterns/pattern-modular-privacy-stack.md index 3adc8d9..a7ee01c 100644 --- a/patterns/pattern-modular-privacy-stack.md +++ b/patterns/pattern-modular-privacy-stack.md @@ -51,7 +51,7 @@ sub_patterns: crops_summary: "Hardware trust; mitigates prover cost but introduces vendor attestation dependency" - name: "Settlement layer" pattern: pattern-dvp-erc7573 - crops_summary: "Atomic DvP via outcome-key commitments and oracle-driven decryption; assumes non-colluding trade-setup oracle" + crops_summary: "Atomic DvP via outcome-key commitments and oracle-driven decryption; assumes non-colluding decryption oracle operators" - name: "Disclosure layer" pattern: pattern-regulatory-disclosure-keys-proofs crops_summary: "View keys, ZK proofs, and attestations for scoped audit access" diff --git a/patterns/pattern-native-account-abstraction.md b/patterns/pattern-native-account-abstraction.md index cc96807..87a0514 100644 --- a/patterns/pattern-native-account-abstraction.md +++ b/patterns/pattern-native-account-abstraction.md @@ -95,4 +95,3 @@ Threat model: ## See also - [EIP-8141 draft](https://eips.ethereum.org/EIPS/eip-8141) -- [Post-Quantum Threats](../domains/post-quantum.md) diff --git a/patterns/pattern-plasma-stateless-privacy.md b/patterns/pattern-plasma-stateless-privacy.md index 0133503..74c52fb 100644 --- a/patterns/pattern-plasma-stateless-privacy.md +++ b/patterns/pattern-plasma-stateless-privacy.md @@ -30,7 +30,7 @@ crops_profile: crops_context: cr: "Reaches `high` when the L1 anchor enforces forced exits via cryptographic proof-based withdrawals that bypass block producer liveness. Drops to `low` if the only withdrawal path depends on a single block producer's cooperation." o: "Reaches `yes` when the block producer software, circuit code, and client software are all published under permissive or copyleft licenses in forkable repositories." - p: "Transaction amounts, sender, and receiver are hidden from chain observers; only block commitments are visible on L1. Sender-list data stays off-chain with the block producer and included users. Network-layer metadata (IP, timing against the block producer) remains out of scope." + p: "Transaction amounts, sender, and receiver are hidden from chain observers; block commitments are what appears on L1. Sender-list data stays off-chain with the block producer and included users. Network-layer metadata (IP, timing against the block producer) remains out of scope." s: "Rides on L1 security for deposit and exit, on the zero-knowledge proof system for transfer validity, and on the user's ability to preserve their own data. Reaches `high` with post-quantum hash-based ZK primitives and robust self-hosted Data Availability." post_quantum: @@ -59,7 +59,7 @@ open_source_implementations: ## Intent -Use a stateless Plasma architecture to enable private token transfers where transaction data stays with users client-side, only commitments are posted on-chain, and validity is proven via zero-knowledge proofs. This provides strong transaction-graph privacy with L2 scalability, at the cost of moving data-availability responsibility to users. +Use a stateless Plasma architecture to enable private token transfers where transaction data stays with users client-side, commitments are posted on-chain, and validity is proven via zero-knowledge proofs. This provides strong transaction-graph privacy with L2 scalability, at the cost of moving data-availability responsibility to users. ## Components @@ -83,7 +83,7 @@ Use a stateless Plasma architecture to enable private token transfers where tran Guarantees: -- Transaction amounts, sender, and receiver are hidden from chain observers; only block commitments are visible on L1. +- Transaction amounts, sender, and receiver are hidden from chain observers; block commitments are what appears on L1. - zero-knowledge proofs ensure no double-spend or inflation without revealing transaction details. - Users control their own data; no operator can freeze specific balances if forced exit is implemented. - Funds are secured by L1; users can always exit with a valid proof. @@ -108,9 +108,9 @@ Threat model: - Institution A deposits 1m stablecoin to the L1 anchor and receives a private balance commitment. - Institution A transfers 500k privately to Institution B, generates the proof locally, and sends an encrypted note. -- The block producer includes the transaction in a block and posts only the Merkle root to L1. +- The block producer includes the transaction in a block and posts the Merkle root to L1. - Institution B receives the note, verifies the proof, and stores it locally. -- On-chain observers see only that a deposit occurred and that a state root was updated; no amounts and no parties. +- On-chain observers see that a deposit occurred and that a state root was updated; no amounts and no parties. - Institution B can later withdraw to any L1 address, breaking the link to the original depositor. ## See also diff --git a/patterns/pattern-privacy-l2s.md b/patterns/pattern-privacy-l2s.md index 23461d1..bb33bc1 100644 --- a/patterns/pattern-privacy-l2s.md +++ b/patterns/pattern-privacy-l2s.md @@ -125,6 +125,3 @@ Threat model: - [Aleo](https://aleo.org/) - [fhEVM documentation](https://docs.zama.org/protocol/protocol/overview) - [Miden](https://miden.xyz/) -- [Aztec (vendor page)](../vendors/aztec.md) -- [Miden (vendor page)](../vendors/miden.md) -- [Zama (vendor page)](../vendors/zama.md) diff --git a/patterns/pattern-zk-proof-systems.md b/patterns/pattern-zk-proof-systems.md index 12a2333..cb14e46 100644 --- a/patterns/pattern-zk-proof-systems.md +++ b/patterns/pattern-zk-proof-systems.md @@ -85,7 +85,5 @@ Benchmarks for Ethereum block proving workloads available at [ethproofs.org CSP ## See also -- [Post-Quantum Threats](../domains/post-quantum.md) — why SNARK-to-STARK migration matters -- [Private Contract DSL](pattern-private-contract-dsl.md) — PLONK-based ZK (PQ-vulnerable) -- [Shielding](pattern-shielding.md) — proof system choice affects shielded pool PQ safety -- [Plasma Stateless Privacy](pattern-plasma-stateless-privacy.md) — hash-based ZK (PQ-safe) +- [zkresear.ch](https://zkresear.ch/) +- [StarkWare: STARK papers](https://starkware.co/stark/) From 72461192079878f3ac265b2cf581fc89cc537eac Mon Sep 17 00:00:00 2001 From: Meyanis95 Date: Mon, 4 May 2026 10:28:49 -0400 Subject: [PATCH 08/10] fix(patterns): v2 frontmatter conformity - pattern-zk-proof-systems: maturity pilot to concept (taxonomy card, not a specific implementation), add context_differentiation, rename CROPS fields to v2 short codes - pattern-eil, pattern-focil-eip7805: remove unsupported rollout-plan key Co-Authored-By: Claude Opus 4.7 (1M context) --- patterns/pattern-eil.md | 1 - patterns/pattern-focil-eip7805.md | 1 - patterns/pattern-zk-proof-systems.md | 27 +++++++++++++++------------ 3 files changed, 15 insertions(+), 14 deletions(-) diff --git a/patterns/pattern-eil.md b/patterns/pattern-eil.md index d9228b2..1482ebc 100644 --- a/patterns/pattern-eil.md +++ b/patterns/pattern-eil.md @@ -5,7 +5,6 @@ maturity: concept type: standard layer: hybrid last_reviewed: 2026-04-22 -rollout-plan: ready to be integrated in wallets works-best-when: - User needs to execute calls on multiple L2s with one signature. diff --git a/patterns/pattern-focil-eip7805.md b/patterns/pattern-focil-eip7805.md index b2aebc8..6530383 100644 --- a/patterns/pattern-focil-eip7805.md +++ b/patterns/pattern-focil-eip7805.md @@ -5,7 +5,6 @@ maturity: testnet type: standard layer: L1 last_reviewed: 2026-04-22 -rollout-plan: glamsterdam or later forks works-best-when: - Censorship resistance is critical and must not depend on builder honesty. diff --git a/patterns/pattern-zk-proof-systems.md b/patterns/pattern-zk-proof-systems.md index cb14e46..e74b5ba 100644 --- a/patterns/pattern-zk-proof-systems.md +++ b/patterns/pattern-zk-proof-systems.md @@ -1,7 +1,7 @@ --- title: "Pattern: ZK Proof Systems" status: draft -maturity: pilot +maturity: concept layer: hybrid privacy_goal: Taxonomy of ZK proving systems by trust model, PQ safety, and performance assumptions: ZK proof system landscape as of 2026 @@ -14,11 +14,14 @@ avoid-when: - Application does not use ZK proofs dependencies: [] context: both +context_differentiation: + i2i: "Between institutions, ZK proof system choice is a procurement and infrastructure decision. Trusted-setup ceremonies, prover throughput on dedicated hardware, and on-chain verification cost dominate selection. PQ safety is a strategic concern for long-lived bilateral commitments and audit obligations spanning a decade or more." + i2u: "For end user applications, client-side proving cost dominates feasibility on mobile and browser (SRS size, memory needed). Proof size translates directly into user gas costs." crops_profile: cr: medium - os: yes - privacy: full - security: medium + o: yes + p: full + s: medium --- ## Intent @@ -45,14 +48,14 @@ This pattern provides a decision framework for selecting ZK proof systems based ## Proof System Comparison -| System | Trust Setup | PQ-Safe | Proof Size | Prover Cost | Verifier Cost | Used By | -| ----------------- | --------------------- | --------------- | ---------- | ----------- | ------------- | ------------------------------------------------------------------------------------------------------ | -| Groth16 | Trusted (per-circuit) | No (pairings) | ~200 B | Low | Low | [Railgun](../vendors/railgun.md), [EY](../vendors/ey.md), [Privacy Pools](../vendors/privacypools.md) | -| PLONK/KZG | Trusted (universal) | No (pairings) | ~400 B | Medium | Low | [Aztec](../vendors/aztec.md), [zkSync](../vendors/zksync.md) | -| PLONK/IPA | Transparent | No (EC) | ~1 KB | Medium | Medium | ZCash | -| STARKs (FRI) | Transparent | Yes (hash-based) | ~50-200 KB | High | Medium | [Miden](../vendors/miden.md) | -| Hash-based SNARKs | Transparent | Yes (hash-based) | ~70-250 KB | High | Medium | Plonky3, Binius | -| Lattice-based | Transparent | Yes (lattices) | TBD | TBD | TBD | Research stage (Latticefold) | +| System | Trust Setup | PQ-Safe | Proof Size | Prover Cost | Verifier Cost | Used By | +| ----------------- | --------------------- | ---------------- | ---------- | ----------- | ------------- | ----------------------------------------------------------------------------------------------------- | +| Groth16 | Trusted (per-circuit) | No (pairings) | ~200 B | Low | Low | [Railgun](../vendors/railgun.md), [EY](../vendors/ey.md), [Privacy Pools](../vendors/privacypools.md) | +| PLONK/KZG | Trusted (universal) | No (pairings) | ~400 B | Medium | Low | [Aztec](../vendors/aztec.md), [zkSync](../vendors/zksync.md) | +| PLONK/IPA | Transparent | No (EC) | ~1 KB | Medium | Medium | ZCash | +| STARKs (FRI) | Transparent | Yes (hash-based) | ~50-200 KB | High | Medium | [Miden](../vendors/miden.md) | +| Hash-based SNARKs | Transparent | Yes (hash-based) | ~70-250 KB | High | Medium | Plonky3, Binius | +| Lattice-based | Transparent | Yes (lattices) | TBD | TBD | TBD | Research stage (Latticefold) | Benchmarks for Ethereum block proving workloads available at [ethproofs.org CSP benchmarks](https://ethproofs.org/csp-benchmarks). Note: the table above reflects typical privacy-application proof characteristics; block-proving benchmarks differ in scale. From aa0551abfdb7fd61b5527f18c4534a4cc1502f2f Mon Sep 17 00:00:00 2001 From: Meyanis95 Date: Mon, 4 May 2026 11:03:02 -0400 Subject: [PATCH 09/10] fix(patterns): keep Protocol sections high-level per v2 template - pattern-native-account-abstraction: split Protocol into 5 steps (was 4) - pattern-eil: strip auction/lock-duration/slashing mechanics from Protocol; move provider-misbehavior detail into Threat model Co-Authored-By: Claude Opus 4.7 (1M context) --- patterns/pattern-eil.md | 7 ++++--- patterns/pattern-native-account-abstraction.md | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/patterns/pattern-eil.md b/patterns/pattern-eil.md index 1482ebc..c5920de 100644 --- a/patterns/pattern-eil.md +++ b/patterns/pattern-eil.md @@ -66,12 +66,12 @@ Account-based cross-L2 interoperability where users sign once and execute transa ## Protocol 1. [user] Discover registered liquidity providers operating on both source and destination chains. -2. [user] Sign a multichain UserOp. On the source chain, lock funds in the CrossChainPaymaster and request a voucher specifying provider list and fee schedule via reverse Dutch auction. Funds unlock automatically if no voucher arrives promptly. -3. [operator] A liquidity provider claims the source-chain funds by submitting a signed voucher. The same voucher releases provider funds on the destination. Source funds remain locked for one hour before crediting the provider's deposit. +2. [user] Sign a multichain UserOp; on the source chain, lock funds in the CrossChainPaymaster and request a voucher. +3. [operator] A liquidity provider claims the source-chain funds and releases provider funds on the destination by signing the voucher. 4. [user] Append the provider voucher to the destination UserOp signature and submit to the destination chain. 5. [contract] Destination CrossChainPaymaster verifies the voucher, checks provider deposits, pays gas, and releases funds to the user. 6. [user] Calls execute on the destination. The same signature can traverse any number of additional L2s using more vouchers. -7. [contract] If a provider misbehaves, the L1 dispute mechanism slashes the violating stake and rewards any other provider that supplies a violation proof. +7. [contract] If a provider misbehaves, an L1 dispute resolves it. ## Guarantees & threat model @@ -88,6 +88,7 @@ Threat model: - Requires the same account implementation or a compatible validation module on every involved chain. - Requires the same signing key on every chain until an L1 keystore with L1SLOAD is available. - Capital efficiency cost: one-hour fund lock on the source chain after voucher issuance. +- Provider misbehavior: handled via L1 slashing of provider stake; any provider that supplies a violation proof receives a reward. The dispute window is bounded by the L1 canonical bridge. - Reorg risk on destination chains with frequent reorganizations; a deep reorg can invalidate a voucher redemption. - Out of scope: application-layer confidentiality. Call targets, amounts, and account identities are all visible. diff --git a/patterns/pattern-native-account-abstraction.md b/patterns/pattern-native-account-abstraction.md index 87a0514..e8af014 100644 --- a/patterns/pattern-native-account-abstraction.md +++ b/patterns/pattern-native-account-abstraction.md @@ -62,9 +62,10 @@ Make every Ethereum account natively programmable by replacing the hardcoded ECD ## Protocol 1. [user] Sign and submit a frame transaction containing an ordered list of frames to the regular mempool. -2. [contract] Execute `VERIFY` frames as static calls. Each must call `APPROVE` with a scope (`0x0` execution, `0x1` payment, `0x2` both). If no frame approves payment, the transaction is invalid. -3. [contract] After validation passes, execute `SENDER`-mode frames with the sender as caller, and `DEFAULT`-mode frames with the protocol entry point as caller. -4. [contract] Charge gas to whichever account approved payment, which may differ from the sender. +2. [contract] Execute each `VERIFY` frame as a static call. +3. [contract] Each `VERIFY` must invoke `APPROVE` with a scope (`0x0` execution, `0x1` payment, `0x2` both); reject the transaction if no frame approves payment. +4. [contract] Execute `SENDER`-mode frames with the sender as caller, and `DEFAULT`-mode frames with the protocol entry point as caller. +5. [contract] Charge gas to the account that `APPROVE` indicated for payment, which may differ from the sender. ## Guarantees & threat model From 93991ae8e2347404989358f20dc1ca6101541114 Mon Sep 17 00:00:00 2001 From: Meyanis95 Date: Mon, 4 May 2026 11:10:36 -0400 Subject: [PATCH 10/10] fix(patterns): rephrase Lean Ethereum Intent opening Address rymnc review on #154. Co-Authored-By: Claude Opus 4.7 (1M context) --- patterns/pattern-lean-ethereum.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/patterns/pattern-lean-ethereum.md b/patterns/pattern-lean-ethereum.md index e313dbf..cf0d539 100644 --- a/patterns/pattern-lean-ethereum.md +++ b/patterns/pattern-lean-ethereum.md @@ -49,7 +49,7 @@ open_source_implementations: ## Intent -Plan a long-range redesign of the Ethereum consensus layer, targeting a single major fork around 2030 that consolidates several research tracks: post-quantum signatures, minimal zkVMs for signature aggregation and proof compression, reduced hardware and stake thresholds for validators, and networking upgrades that support a larger validator set. The goal is a consensus protocol that is stable for decades, resilient against quantum adversaries, and verifiable on minimal devices. +Lean Ethereum is a long-range redesign of the Ethereum consensus layer, targeting a single major fork around 2030 that consolidates several research tracks: post-quantum signatures, minimal zkVMs for signature aggregation and proof compression, reduced hardware and stake thresholds for validators, and networking upgrades that support a larger validator set. The goal is a consensus protocol that is stable for decades, resilient against quantum adversaries, and verifiable on minimal devices. ## Components