feat(patterns): propagate batch 1 + 2 v2 migration to master

CHANGELOG.md

@@ -4,6 +4,7 @@ All notable changes to the IPTF Map are documented here.
 
 ## [Unreleased]
 
+- feat(schema): pattern template v2 — structured `crops_context`, `post_quantum`, `context_differentiation`, `related_patterns`, `open_source_implementations`, `sub_patterns`, and `type: meta` flag. `_template.md`, `scripts/schemas/pattern.json`, and `scripts/validate-patterns.js` updated. Validator stays permissive during migration; existing v1 patterns continue to pass with deprecation warnings. ([#150](https://github.com/ethereum/iptf-map/issues/150))
 - feat(pattern): [Onion Routing](patterns/pattern-onion-routing.md) -- Tor-based multi-hop relay for sender IP anonymity (PSE tor-js, Flashbots .onion) ([#146](https://github.com/ethereum/iptf-map/pull/146))
 - feat(pattern): [Mixnet Anonymity](patterns/pattern-mixnet-anonymity.md) -- batching, reordering, and cover traffic for strongest network anonymity (Nym, HOPR) ([#146](https://github.com/ethereum/iptf-map/pull/146))
 - refactor(pattern): split [Network-Level Anonymity](patterns/pattern-network-anonymity.md) into umbrella pattern linking onion routing, mixnet, and TEE sub-patterns ([#146](https://github.com/ethereum/iptf-map/pull/146))

patterns/_template.md

@@ -1,41 +1,154 @@
 ---
+# ─── Identity ───────────────────────────────────────────────────────────────
 title: "Pattern: <short name>"
-status: draft|ready
-maturity: PoC|pilot|prod
-works-best-when: <bulleted, 1–3 lines>
-avoid-when: <bulleted, 1–3 lines>
-dependencies: [ERC-3643, EIP-7573, EAS, ...]
-context: i2i|i2u|both              # applicable relationship type
+status: draft | ready
+# One of: research (paper only), concept (spec, no code), testnet (PoC/pilot),
+#         production (mainnet with real usage).
+maturity: research | concept | testnet | production
+# Optional. `meta` patterns aggregate sub_patterns; see below.
+type: standard | meta
+layer: L1 | L2 | offchain | hybrid
+last_reviewed: YYYY-MM-DD
+
+# ─── When to use ────────────────────────────────────────────────────────────
+works-best-when:
+  - <1-3 bullets>
+avoid-when:
+  - <1-3 bullets>
+
+# ─── Relationship context ───────────────────────────────────────────────────
+# i2i = institution-to-institution, i2u = institution-to-user.
+# If `both`, context_differentiation below must be filled in.
+context: i2i | i2u | both
+
+# Required when context: both. Renders as a two-column callout in the Guide.
+context_differentiation:
+  i2i: "Symmetric trust; both parties have legal recourse"
+  i2u: "Asymmetric; CROPS must protect the user. Forced withdrawal is critical"
+
+# ─── CROPS ──────────────────────────────────────────────────────────────────
+# Badge values. Use the string 'n/a' for meta/evaluation patterns that do not
+# implement privacy directly.
 crops_profile:
-  cr: high|medium|low|none       # censorship resistance impact
-  os: yes|partial|no             # open source and free (source availability, forkability, exit paths)
-  privacy: full|partial|none     # privacy guarantees (who sees what — see CONTRIBUTING.md § Privacy)
-  security: high|medium|low       # strength of security guarantees (see CONTRIBUTING.md § Security)
+  cr: high | medium | low | none # Censorship Resistance
+  o: yes | partial | no # Openness (source availability, open standards, exit paths, forkability)
+  p: full | partial | none # Privacy (who sees what)
+  s: high | medium | low # Security (trust model, assumptions)
+
+# Narrative context for each CROPS dimension — where the badges drift up or
+# down in practice. Replaces the ad-hoc "CROPS context" bullet in Trade-offs.
+crops_context:
+  cr: "Reaches `high` on L1 permissionless pools. Drops to `low` on permissioned L2s with operator-controlled exit."
+  o: "..."
+  p: "..."
+  s: "..."
+
+# ─── Post-quantum exposure ──────────────────────────────────────────────────
+# Replaces the ad-hoc "Post-quantum" bullet in Trade-offs.
+post_quantum:
+  risk: high | medium | low
+  vector: "EC-based commitments (Groth16, PLONK/KZG) broken by CRQC; HNDL risk for encrypted notes"
+  mitigation: "STARK-based pools with hash commitments"
+
+# ─── Visibility matrix (optional) ───────────────────────────────────────────
+# Four-slot model for transaction-level patterns: who sees what. Skip for
+# infrastructure or primitive patterns where the model does not apply.
+visibility:
+  counterparty: [amounts, identities]
+  chain: [commitments, nullifiers]
+  regulator: [full_tx with viewing key]
+  public: []
+
+# ─── Standards & cross-references ───────────────────────────────────────────
+# Standards this pattern relies on. Flow-style array of standard identifiers
+# (ERC-XXX, EIP-XXX, ISO-XXXXX, etc.).
+standards: [ERC-20, ERC-5564, EIP-7573]
+
+# Cross-references to other patterns. Replaces the old `dependencies` field
+# and the pattern-to-pattern links that used to live in `## See also`.
+# Each entry is a slug matching patterns/pattern-<slug>.md — no paths, just
+# the slug. The validator resolves and checks the file exists.
+related_patterns:
+  requires: [pattern-shielding] # hard dependency — can't implement this without it
+  composes_with: [pattern-stealth-addresses] # works well together, optional
+  alternative_to: [pattern-tee-based-privacy] # competing approach to the same problem
+  see_also: [pattern-forced-withdrawal] # related for context
+
+# Known implementations (plural, neutral). Renamed from "reference
+# implementation" — that phrase has a specific meaning in standards contexts.
+open_source_implementations:
+  - url: https://github.com/Railgun-Privacy/contract
+    description: "Railgun shielded pool (L1, production)"
+    language: Solidity
+  - url: https://github.com/AztecProtocol/aztec-packages
+    description: "Aztec Network (privacy L2)"
+    language: Noir
+
+# ─── META-PATTERN ONLY (type: meta) ─────────────────────────────────────────
+# If set, crops_profile may be 'n/a' and ## Protocol / ## Example become
+# optional. Each child is a slug resolved to patterns/pattern-<slug>.md.
+sub_patterns:
+  - name: "Onion routing (Tor-style)"
+    pattern: pattern-onion-routing
+    crops_summary: "High CR, high privacy, high latency"
+  - name: "Mixnet"
+    pattern: pattern-mixnet-anonymity
+    crops_summary: "Medium CR, full privacy, high latency"
 ---
 
 ## Intent
+
 One short paragraph: the job this pattern does.
 
-## Ingredients
-- Standards/ER(C|IP)s
-- Infra (L1/L2, wallets, oracles)
-- Off-chain services (KMS, registry, RFQ, etc.)
+## Components
 
-## Protocol (concise)
-Numbered steps (5–8 max) from intent → settlement/audit.
+What makes up this pattern. Primitives, on-chain code, and off-chain services
+all belong here. Each item gets a short note on its role.
+
+- <Primitive or module> — <role it plays>
+- <Primitive or module> — <role it plays>
+
+If a component is also a standalone pattern in this map, link it via
+`related_patterns` rather than describing it in depth here.
+
+## Protocol
+
+Numbered steps (5-8 max) from intent to settlement/audit. Each step is
+prefixed with the actor performing it in square brackets:
+`[user]`, `[contract]`, `[relayer]`, `[prover]`, `[auditor]`, `[operator]`,
+`[regulator]`, etc.
+
+1. [user] Deposit ERC-20 tokens into shielded pool contract
+2. [contract] Emit commitment on-chain
+3. [user] Execute shielded transfer (generate zero-knowledge proof client-side)
+4. [relayer] Submit the shielded transaction for gas abstraction
+5. [auditor] Verify via viewing key
+
+Optional for `type: meta` patterns (use `sub_patterns` instead).
+
+## Guarantees & threat model
 
-## Guarantees
 - What it hides / proves
 - Atomicity / finality
 - Audit & ops signal
-- How guarantees differ in I2I vs I2U contexts (if applicable)
+- Threat model: who the adversary is, what assumptions break the guarantees,
+  and which failure modes are out of scope
 
 ## Trade-offs
+
+Generic performance, cost, DX notes and failure modes. CROPS context and
+post-quantum exposure now live in frontmatter (`crops_context`, `post_quantum`),
+not here.
+
 - Performance / cost / DX notes
 - Failure modes & mitigations
 
 ## Example
-“Bank A sells €5m zero-coupon to Bank B…” — 3–5 bullets showing flow.
+
+"Bank A sells €5m zero-coupon to Bank B…" — 3-5 bullets showing flow.
+Optional for `type: meta` patterns.
 
 ## See also
-Cross-link to related pattern cards.
+
+External references only: specs, blog posts, docs. Pattern-to-pattern links
+belong in `related_patterns`.

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 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:
-  - 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 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`.
+
+## 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)