From 31bf42a86b8b6f806f60aacd62da0de79128e804 Mon Sep 17 00:00:00 2001 From: oskarth Date: Thu, 10 Sep 2026 10:39:08 +0800 Subject: [PATCH] fix(ci): repair the Vale prose gate The Prose Quality (Vale) job has never worked as a gate. #196 turned it green by adding `continue-on-error: true`, so the step can no longer fail the build. The green run itself proves it: run 34344604531 still logs `##[error]Vale and reviewdog exited with status code: 1` after reporting 207 findings. Three defects stack up. 1. The `files` input never reaches Vale. `.github/workflows/ci.yml` passed it as a YAML block scalar, and #196 changed that to a block scalar plus `separator: "\n"`. Neither works. vale-action reads `separator` through `@actions/core` `getInput`, which trims whitespace, so the newline arrives as an empty string and the multi-line `files` value falls through to `JSON.parse` and throws. The action logs "User-specified path is invalid; falling back to 'all'" and lints the whole repository instead of the six content directories. 2. EthSystems.Marketing flags the bare words "only", "first" and "unique". Those are ordinary technical prose and produce most of the findings in the linted scope. 3. reviewdog exits 1 on any result, whatever `fail_on_error` says, and GitHub caps annotations at 50 per job. So the job fails on volume, and the only way anyone found to stop it failing was to stop it reporting. Changes: - Scope the Marketing rule to promotional claims: "the only solution", "world's first", "first-of-its-kind", "truly unique", "leading provider", and the existing superlative and buzzword lists. - Drop the Terminology swap that forced "Multi-Party Computation" to lower case, and restore the title-case expansion in GLOSSARY.md that #195 changed to satisfy it. The glossary writes "FHE (Fully Homomorphic Encryption)" and "TEE (Trusted Execution Environment)" in title case on the lines around it, and GLOSSARY.md is not one of the files the job lints, so that finding should never have been reported. - Ignore file names used as markdown link text. They are identifiers, not prose. - Pass `files` as a JSON array, the one form the action parses. - Drop `continue-on-error` from the Vale step so it can gate again. - Fix the real content: enterprise-grade, next-generation, scalable, robust and comprehensive in five vendor and pattern cards, plus the remaining ERC-7573 and DA Layer terminology drift. Verified with Vale 3.20.0, the version CI installs. Findings in the linted scope: 187 on master, 0 here. Whole repository: 207 to 7, all in QA-AUDIT.md and the gitignored validation report, neither of which the job lints. On a fixture the rules still catch "leading provider", "enterprise-grade" and "world's first", and no longer flag "only the sender learns the amount", "the first step" or "a unique nullifier". --- .github/workflows/ci.yml | 15 ++++---- .vale.ini | 4 ++- .vale/styles/EthSystems/Marketing.yml | 35 +++++++++---------- .vale/styles/EthSystems/Terminology.yml | 7 +++- CHANGELOG.md | 1 + GLOSSARY.md | 2 +- .../pattern-cross-chain-privacy-bridge.md | 2 +- patterns/pattern-forced-withdrawal.md | 8 ++--- patterns/pattern-plasma-stateless-privacy.md | 2 +- vendors/chainlink-ace.md | 2 +- vendors/fhenix.md | 2 +- vendors/flashbots.md | 2 +- vendors/paladin.md | 2 +- vendors/tx-shield.md | 2 +- vendors/zksync.md | 2 +- 15 files changed, 46 insertions(+), 42 deletions(-) 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