diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7c4ce9b..1ab70bb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -150,19 +150,16 @@ jobs: - name: Vale linter uses: errata-ai/vale-action@d89dee975228ae261d22c15adcd03578634d429c # v2 with: - files: |- - patterns - vendors - approaches - use-cases - jurisdictions - domains - separator: "\n" + # vale-action accepts a single path, a JSON array, or a string split + # on `separator`. A YAML block scalar is none of those, and a + # whitespace `separator` is trimmed away by core.getInput before the + # action reads it, so both forms end in "path is invalid; falling + # back to 'all'" and the whole repository gets linted. + files: '["patterns/", "vendors/", "approaches/", "use-cases/", "jurisdictions/", "domains/"]' fail_on_error: false reporter: github-check env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - continue-on-error: true validate-changelog: runs-on: ubuntu-latest diff --git a/.vale.ini b/.vale.ini index 773e36e..f8b983e 100644 --- a/.vale.ini +++ b/.vale.ini @@ -10,7 +10,9 @@ BasedOnStyles = EthSystems # Skip code blocks and frontmatter BlockIgnores = (?s) *```.*?``` -TokenIgnores = (`[^`]+`) +# Ignore inline code and links whose text is a file name: `pattern-dvp-erc7573.md` +# is an identifier, not prose, and must not be graded as terminology. +TokenIgnores = (`[^`]+`), (\[[^\]]*\.md\]\([^)]*\)) # Content directories - full linting [patterns/*.md] diff --git a/.vale/styles/EthSystems/Marketing.yml b/.vale/styles/EthSystems/Marketing.yml index ed9b288..dde997d 100644 --- a/.vale/styles/EthSystems/Marketing.yml +++ b/.vale/styles/EthSystems/Marketing.yml @@ -1,6 +1,10 @@ # EthSystems Marketing Language Detector # Catches promotional/marketing language that should not appear in technical docs -# Mirrors patterns from .marketing-exceptions.txt +# +# Scope rule: match promotional claims, not ordinary English. Words such as +# "only", "first" and "unique" are normal technical prose ("only the sender +# learns the amount", "the first step", "a unique nullifier"), so they are +# matched only in their promotional forms. extends: existence message: "Avoid marketing language: '%s'. Use neutral, factual terms." @@ -14,7 +18,9 @@ tokens: - world-class - top-tier - premier - - leading + - industry leader + - market leader + - leading (?:provider|platform|solution|protocol|vendor|network) - superior - unmatched - unrivaled @@ -43,26 +49,19 @@ tokens: - comprehensive - one-stop - # Exclusive claims - - unique(?! identifier| ID) - - only(?! works with| supports| available| if| when) - - first(?!-come| step| phase) + # Exclusive claims (promotional forms only) + - the only (?:solution|platform|protocol|provider|network|option|way|choice) + - (?:world's|industry's|market's) (?:first|best|fastest|most) + - first-ever + - first-of-its-kind + - industry-first + - truly unique + - uniquely positioned + - unique (?:advantage|selling|value proposition) - fastest - most secure # Exceptions - these terms are allowed in context exceptions: - - unique identifier - - unique ID - - first-come-first-served - - end-to-end encryption - - end-to-end encrypted - - only works with - - only supports - - only available - - only if - - only when - - first step - - first phase - Best Execution - best execution diff --git a/.vale/styles/EthSystems/Terminology.yml b/.vale/styles/EthSystems/Terminology.yml index 08118c7..2712cc9 100644 --- a/.vale/styles/EthSystems/Terminology.yml +++ b/.vale/styles/EthSystems/Terminology.yml @@ -1,6 +1,12 @@ # EthSystems Terminology Consistency # Enforces canonical spellings from GLOSSARY.md # See also: scripts/check-terminology.js for programmatic checking +# +# Case rule: the swap direction must agree with GLOSSARY.md. The glossary +# writes "MPC (Multi-Party Computation)", "FHE (Fully Homomorphic +# Encryption)" and "TEE (Trusted Execution Environment)" in title case, so +# a swap that forced "Multi-Party Computation" down to lower case +# contradicted both the glossary and the two entries next to it. extends: substitution message: "Use '%s' instead of '%s' for consistency with GLOSSARY.md." @@ -56,7 +62,6 @@ swap: # Cryptographic terms multiparty computation: multi-party computation - Multi-Party Computation: multi-party computation fully homomorphic encryption: Fully Homomorphic Encryption trusted execution environment: Trusted Execution Environment diff --git a/CHANGELOG.md b/CHANGELOG.md index e545c6d..cbd57ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ All notable changes to the EthSystems Map are documented here. ## [Unreleased] +- fix(ci): repair the Vale prose gate. Scope [EthSystems.Marketing](.vale/styles/EthSystems/Marketing.yml) to promotional claims instead of the bare words "only", "first" and "unique"; drop the [EthSystems.Terminology](.vale/styles/EthSystems/Terminology.yml) swap that forced "Multi-Party Computation" to lower case against GLOSSARY.md; ignore file names used as link text; pass `files` to `vale-action` as a JSON array, the one form the action parses, so the job lints the six content directories instead of the whole repository; and drop the `continue-on-error` added in [#196](https://github.com/ethsystems/map/pull/196), which kept the job green while Vale still exited 1 on 207 findings. Also clears the five real marketing terms and the remaining ERC-7573 and DA Layer terminology drift in the prose. Vale findings in the linted scope: 187 to 0 ([#197](https://github.com/ethsystems/map/pull/197)) - feat(vendor): add [Interfold](vendors/interfold.md), plus patterns [Publicly Verifiable DKG and Threshold Decryption](patterns/pattern-verifiable-dkg-threshold-decryption.md) and [Ephemeral Committees](patterns/pattern-ephemeral-committees.md), covering single-use committees that dispose of key material after decryption ([#178](https://github.com/ethsystems/map/pull/178)) - feat(vendor): add [The Graph](vendors/the-graph.md), decentralized indexing and query infrastructure as the audit read path ([#186](https://github.com/ethsystems/map/pull/186), landed via [#193](https://github.com/ethsystems/map/pull/193)) - feat(pattern): add [Reproducible Audit Extraction](patterns/pattern-reproducible-audit-extraction.md), the verifier's data-acquisition leg the disclosure patterns presuppose ([#186](https://github.com/ethsystems/map/pull/186), landed via [#193](https://github.com/ethsystems/map/pull/193)) diff --git a/GLOSSARY.md b/GLOSSARY.md index 5e209fc..f5527b1 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -111,7 +111,7 @@ A dedicated network or service that publishes and stores the data required for D **TEE (Trusted Execution Environment)**: Hardware-based secure computation environment -**MPC (multi-party computation)**: Cryptographic technique for joint computation without revealing inputs +**MPC (Multi-Party Computation)**: Cryptographic technique for joint computation without revealing inputs **OPRF (Oblivious Pseudorandom Function)**: Cryptographic protocol where a server evaluates a pseudorandom function on a client's input without learning the input, and the client learns the output without learning the server's key. Used for private set intersection, password-hardening, and privacy-preserving authentication. diff --git a/patterns/pattern-cross-chain-privacy-bridge.md b/patterns/pattern-cross-chain-privacy-bridge.md index a819b8b..f094d67 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 tested 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. - Deployment topologies: pre-bridge mixing (deposit through a source-chain shielded pool first, then bridge: full sender privacy at added latency); hub-and-spoke (L1 as verification hub; multiple L2s prove deposits via the L1 bridge contract); privacy-to-privacy (shielded pools on both ends: privacy on both sender and receiver ends, more complex verification); asymmetric (one direction private, e.g. public L1 to private L2). diff --git a/patterns/pattern-forced-withdrawal.md b/patterns/pattern-forced-withdrawal.md index 604a3e8..96e7d75 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,7 +106,7 @@ 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. +- 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 materially 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-plasma-stateless-privacy.md b/patterns/pattern-plasma-stateless-privacy.md index 213764f..e5a320f 100644 --- a/patterns/pattern-plasma-stateless-privacy.md +++ b/patterns/pattern-plasma-stateless-privacy.md @@ -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 diff --git a/vendors/chainlink-ace.md b/vendors/chainlink-ace.md index 7da5608..269aab0 100644 --- a/vendors/chainlink-ace.md +++ b/vendors/chainlink-ace.md @@ -11,7 +11,7 @@ Modular compliance layer built on the Chainlink Runtime Environment (CRE) to def ## Fits with patterns - [Regulatory Disclosure Keys Proofs](../patterns/pattern-regulatory-disclosure-keys-proofs.md) - [Crypto Registry Bridge eWpG EAS](../patterns/pattern-crypto-registry-bridge-ewpg-eas.md) -- [DvP ERC7573](../patterns/pattern-dvp-erc7573.md) +- [DvP ERC-7573](../patterns/pattern-dvp-erc7573.md) ## Not a substitute for - Privacy L2 or App-chain diff --git a/vendors/fhenix.md b/vendors/fhenix.md index 8593dc4..3bd1c2d 100644 --- a/vendors/fhenix.md +++ b/vendors/fhenix.md @@ -8,7 +8,7 @@ maturity: testnet ## What it is -Fhenix builds a CoProcessor that brings Fully Homomorphic Encryption (FHE) to EVM chains, enabling developers to compute directly on encrypted data without ever decrypting it. This allows dApps to offer on-chain privacy by default. At its core, Fhenix introduces CoFHE, a decentralized coprocessor that makes encrypted computation fast, scalable, and easy for Solidity developers to adopt. +Fhenix builds a CoProcessor that brings Fully Homomorphic Encryption (FHE) to EVM chains, enabling developers to compute directly on encrypted data without ever decrypting it. This allows dApps to offer on-chain privacy by default. At its core, Fhenix introduces CoFHE, a decentralized coprocessor that runs encrypted computation off-chain and exposes it to Solidity developers. ## Fits with patterns diff --git a/vendors/flashbots.md b/vendors/flashbots.md index 3bb17f2..8b3da77 100644 --- a/vendors/flashbots.md +++ b/vendors/flashbots.md @@ -46,7 +46,7 @@ Flashbots develops MEV infrastructure including private mempools, block building - Established MEV mitigation with significant adoption - Strong relationship with the Ethereum ecosystem -- Active development of next-generation infrastructure (SUAVE) +- Active development of new infrastructure (SUAVE) - Revenue-sharing mechanisms align user incentives ## Risks and open questions diff --git a/vendors/paladin.md b/vendors/paladin.md index 384a947..ff6a671 100644 --- a/vendors/paladin.md +++ b/vendors/paladin.md @@ -19,7 +19,7 @@ A strong design principle of the project is that existing privacy preserving tok ## Fits with patterns - [Shielding](../patterns/pattern-shielding.md) -- [DvP ERC7573](../patterns/pattern-dvp-erc7573.md) +- [DvP ERC-7573](../patterns/pattern-dvp-erc7573.md) - [Private Stablecoin Shielded Payments](../patterns/pattern-private-stablecoin-shielded-payments.md) - [Crypto Registry Bridge eWpG EAS](../patterns/pattern-crypto-registry-bridge-ewpg-eas.md) diff --git a/vendors/tx-shield.md b/vendors/tx-shield.md index 3bb45eb..96135d3 100644 --- a/vendors/tx-shield.md +++ b/vendors/tx-shield.md @@ -85,7 +85,7 @@ OpenTMP LLM: - Privacy-preserving AI model training and inferences for enterprises and regulated sectors, such as healthcare, finance, and government. Collab-Key: -Institutional wallets, custodians, and enterprise-grade signing infrastructure requiring fault-tolerant, hardware-secure (ReRAM) key management to eliminate single points of failure. +Institutional wallets, custodians, and signing infrastructure requiring fault-tolerant, hardware-secure (ReRAM) key management to eliminate single points of failure. --- diff --git a/vendors/zksync.md b/vendors/zksync.md index 525635c..201dae3 100644 --- a/vendors/zksync.md +++ b/vendors/zksync.md @@ -47,7 +47,7 @@ Target segments include financial institutions tokenizing treasuries and fund sh ## Strengths -- Comprehensive enterprise features including compliance, KYC/AML, and selective disclosure +- Enterprise features including compliance, KYC/AML, and selective disclosure - Efficient ZK Proving - Modularity and interop accross Prividiums - L1 as final settlement layer