From 68eda9373675a51e32d2703f0eff34d4a0fb6ad2 Mon Sep 17 00:00:00 2001 From: jzaki Date: Tue, 4 Aug 2026 18:19:51 +0100 Subject: [PATCH 01/69] Stub wrapped erc20 rfp --- .github/ISSUE_TEMPLATE/proposal.yml | 1 + README.md | 1 + RFPs/RFP-021-wrapped-erc20.md | 515 ++++++++++++++++++++++++++++ 3 files changed, 517 insertions(+) create mode 100644 RFPs/RFP-021-wrapped-erc20.md diff --git a/.github/ISSUE_TEMPLATE/proposal.yml b/.github/ISSUE_TEMPLATE/proposal.yml index 44172d4d..11113c3a 100644 --- a/.github/ISSUE_TEMPLATE/proposal.yml +++ b/.github/ISSUE_TEMPLATE/proposal.yml @@ -14,6 +14,7 @@ body: - "RFP-015 — Token Launchpad: Bonding Curve" - "RFP-016 — Token Launchpad: LBP" - "RFP-017 — Privacy-Preserving Token Vesting" + - "RFP-021 — Wrapped ERC-20 Bridge for LEZ" validations: required: true diff --git a/README.md b/README.md index 9de0cd9f..646c5bf5 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,7 @@ Click an RFP to view details. Use the Submit Proposal button to apply. | RFP-017 | [Privacy-Preserving Token Vesting](RFPs/RFP-017-token-vesting.md) | L | open | 09/09/26 | Applications & Integrations | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | | RFP-019 | [On-Chain TWAP Oracle](RFPs/RFP-019-twap-oracle.md) | L | closed | - | Developer Tooling & Infrastructure | Closed | | RFP-020 | [RedStone Off-Chain Oracle Adaptor for LEZ](RFPs/RFP-020-redstone-oracle-adaptor.md) | M | closed | - | Developer Tooling & Infrastructure | Closed | +| RFP-021 | [Wrapped ERC-20 Bridge for LEZ](RFPs/RFP-021-wrapped-erc20.md) | L | open | - | Developer Tooling & Infrastructure | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md new file mode 100644 index 00000000..d0133894 --- /dev/null +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -0,0 +1,515 @@ +--- +id: RFP-021 +title: Wrapped ERC-20 Bridge for LEZ +tier: L +status: open +category: Developer Tooling & Infrastructure +dependencies: + - id: RFP-001 + reason: Admin authority governs the supported-token registry and the attestor federation's membership and threshold, as specified in Functionality. + - id: RFP-002 + reason: Freeze authority provides the circuit breaker to halt minting and/or redemption, globally or per token, if the attestor federation or the Ethereum-side vault is suspected compromised. + - id: LP-0013 + reason: Mint/burn token authority primitives are required for the LEZ program to mint wrapped tokens on deposit and burn them on redemption. +--- + + + +# RFP-021 — Wrapped ERC-20 Bridge for LEZ + +> **Note.** This specification describes an outcome that may benefit the Logos +> ecosystem. It is a proposal rather than an instruction. Its requirements +> reflect the technical compatibility with the Logos technology stack and are +> the criteria against which proposals and milestones are evaluated. Logos makes +> no representation as to the legal or regulatory treatment of this +> specification or any implementation of it in any jurisdiction. +> +> Teams implementing it are solely responsible for (i) assessing the risks and +> implications of what they build; (ii) obtaining their own professional advice; +> and (iii) for complying with any legal and regulatory requirements that apply +> to them. Software developed under the Program is published and maintained by +> its developers, not by Logos. +> +> Anyone who chooses to deploy, host, operate or use software developed under +> the Program, whether or not they were awarded a grant under the Program, does +> so at their own risk and is solely responsible for complying with any legal or +> regulatory requirements that apply to them. See the +> [Terms & Conditions](../TERMS_AND_CONDITIONS.md). +> +> Deploying the software described in this RFP, operating any service based on +> it, or carrying on business through it may amount to regulated activity in +> some jurisdictions, including where it involves holding or managing users' +> assets or providing services to others. Whoever conducts any such activity +> does so as principal, in their own name, and is solely responsible for +> assessing its regulatory treatment, including any licensing, registration, +> sanctions or anti-money laundering obligations that may apply to them. Logos +> does not make any representation, provides any advice or assumes any +> responsibility in respect of any such determination or compliance. + +## 🧭 Overview + +Build a lock-and-mint bridge that lets ERC-20 tokens (and native ETH, wrapped as +WETH) held on Ethereum enter LEZ as canonical wrapped assets, and exit back to +Ethereum on redemption. An Ethereum-side vault contract escrows deposits; a +federation of attestors observes finalised deposits and threshold-signs an +attestation; a LEZ-side program verifies the threshold signature and mints the +corresponding wrapped token to the recipient's LEZ account. Redemption reverses +the flow: burning the wrapped token on LEZ triggers a federation-attested +release of the original ERC-20 from the vault. The verification core reuses the +in-program secp256k1 ECDSA + keccak256 path already built for +[RFP-020](./RFP-020-redstone-oracle-adaptor.md), so this RFP is primarily new +protocol wiring (vault contract, mint/burn program, federation daemon) rather +than new cryptographic groundwork. Teams should have experience with Solidity +smart-contract development, cross-chain relayer/federation architecture, and LEZ +program development. + +## 🔥 Why This Matters + +LEZ DeFi cannot function without external collateral. The lending protocol +([RFP-008](./RFP-008-lending-borrowing-protocol.md)), the reflexive stablecoin +([RFP-013](./RFP-013-reflexive-stablecoin-protocol.md)), and the on-chain TWAP +oracle's own design ([RFP-019](./RFP-019-twap-oracle.md)) all assume wrapped +external assets — wBTC, wETH, wXMR, wZEC — are already available as LEZ tokens. +None of those RFPs specify how a token actually gets wrapped; this RFP is that +missing primitive for the Ethereum leg (Bitcoin, Monero, and Zcash have their +own trustless path via atomic swaps in +[RFP-003](./RFP-003-atomic-swaps.md)). + +RFP-003 explicitly carved Ethereum out of its scope for exactly this reason: +"ETH is expected to reach LEZ via wrapping, which requires no swap counterparty +and is a much simpler construction." Bitcoin, Monero, and Zcash lack general +smart-contract expressiveness, so a trustless swap protocol (adaptor +signatures, HTLCs, DLEQ proofs) is the only construction available for them. +Ethereum's programmability makes a lock-and-mint bridge with a vault contract +possible instead, which is the standard architecture used to move value onto +every smart-contract chain that isn't Ethereum itself. It is simpler to build +than a trustless swap, but it is not trustless: it introduces a federation +trust assumption that this RFP must document honestly rather than obscure. + +Stablecoins are the concrete prize. USDT and USDC together account for over 80% +of a stablecoin market that stood above $300B in mid-2026, and are the +settlement asset most DeFi money markets and DEXes actually run on. Without a +wrapped ERC-20 primitive, LEZ has no path to bring USDC, USDT, DAI, or WETH +liquidity onto the chain, which blocks the lending protocol and the reflexive +stablecoin from having any credible collateral base at launch. + +Bridges are also the most attacked category of infrastructure in DeFi: +Chainalysis has tracked more than $2.8B stolen from cross-chain bridges since +2022, the highest-value class of exploit in the industry. This RFP's security +posture — a bounded, capped, admin-governed federation with a freeze-authority +circuit breaker, rather than an unbounded trust-me bridge — is designed +directly against that track record, and is explained in full in Design +Rationale and the Bridge Security requirements below. + +## 🏗 Design Rationale + +### Lock-and-mint via a federated attestor set + +The bridge has two independently deployed halves that share one verification +primitive: + +1. **Ethereum vault contract.** A Solidity contract that accepts deposits of any + ERC-20 token in the supported-token registry (plus native ETH, which the + vault wraps to WETH internally so ETH does not need a separate bridging + path). Each deposit locks the token and emits a + `Deposit(token, depositor, amount, lezRecipient, nonce)` event. +2. **Attestor federation.** An M-of-N set of attestors (default 3-of-5, + configurable, registered and rotated by the admin authority per RFP-001) + watches the Ethereum vault. Once a deposit reaches a configured finality + depth, each attestor independently verifies the deposit and signs a + secp256k1 ECDSA attestation over `(token, depositor, amount, lezRecipient, + nonce)`. +3. **LEZ bridge program.** A public-mode LEZ program verifies the M-of-N + threshold over the attestation — reusing the same in-program secp256k1 ECDSA + + keccak256 verification path built for the RedStone adaptor + ([RFP-020](./RFP-020-redstone-oracle-adaptor.md), Functionality #1–#2) — and + mints the corresponding wrapped token to `lezRecipient`, crediting a private + account directly where the recipient requests it (see "+ Privacy" below). + The deposit `nonce` is recorded on first use and any repeat submission of the + same nonce is rejected, so replaying an attestation cannot double-mint. + +This is the same "signed attestation verified in-program" shape RFP-020 already +proved out for oracle data; the message being signed changes (a deposit tuple +instead of a price) but the verifier, the signer-set management, and the +M-of-N threshold logic are the same problem. Proposals are expected to share +code with, or directly depend on, the RFP-020 verification library rather than +reimplementing ECDSA recovery from scratch. + +### Redemption: burn-and-release + +Redemption is the mirror flow. A holder burns wrapped tokens on LEZ via the +bridge program, which validates the burn and emits a structured redemption +event (per [LP-0012](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md)) +carrying `(token, amount, ethereumRecipient, redemptionNonce)`. Once the burn +transaction reaches LEZ finality, the attestor federation observes the +redemption event and threshold-signs a release authorisation. The Ethereum +vault verifies the M-of-N signature — native `ecrecover` on the EVM, orders of +magnitude cheaper than the in-program RISC-V path, matching the asymmetry +RFP-020 already documented between LEZ-side and EVM-side ECDSA verification +cost — and releases the original ERC-20 to `ethereumRecipient`, tracking +`redemptionNonce` to reject replays on the Ethereum side. + +### Token registry and decimal normalisation + +Each supported ERC-20 is registered individually by the admin authority: its +Ethereum contract address, its LEZ wrapped-token mint, its decimals, and its +per-token deposit/redemption cap (see "Bridge Security" below). ERC-20 tokens +do not share a common decimals convention (6 for USDC, 8 for WBTC, 18 for WETH +and DAI); the wrapped LEZ mint for each token must document its own decimals +and the exact conversion applied on mint and burn, and the registration +instruction must reject a token whose decimals cannot be represented exactly in +the chosen LEZ mint precision. + +### Finality windows and reorg protection + +An attestor must not sign a deposit attestation until the deposit transaction +has reached a configured Ethereum finality depth (a block-count or, once +generally available, a beacon-chain finalised-checkpoint condition). Signing +before finality risks attesting to a deposit that a reorg later removes, which +would mint wrapped tokens against a deposit that no longer exists on Ethereum. +The chosen depth is a direct trade-off between user-facing deposit latency and +reorg risk, and proposals must document the depth chosen and the residual risk +it leaves. The reverse direction (LEZ burn to Ethereum release) is symmetric: +attestors wait for LEZ finality on the burn transaction before co-signing a +release. + +### Trust model: federated custodial, not trustless + +This bridge is **not** trustless. It composes with RFP-003's trustless BTC, +XMR, and ZEC swaps, not with the same security model: a user who bridges an +ERC-20 asset is trusting that at least `M` of the `N` attestors are honest and +that their keys are not simultaneously compromised. Proposals must state this +trust assumption plainly in user-facing documentation (mini-app, README, +SDK docs), rather than presenting the bridge as trust-minimised. Per-token and +global caps, the freeze-authority circuit breaker, and a documented attestor +rotation process (see Bridge Security) are the mitigations this RFP requires in +lieu of trustlessness; they bound the blast radius of a federation compromise, +they do not eliminate it. A fully trustless design — verifying Ethereum +consensus signatures or Merkle-Patricia state proofs inside the LEZ program — +is out of scope (see Out of Scope) and is a candidate for a future RFP once +in-circuit verification cost on RISC0 makes it practical, mirroring the +cost-conditional precompile path RFP-020 already laid out for its own +verification primitive. + +### Fee structure + +This RFP does not mandate a specific fee rate. Proposals must specify who pays +(depositor, redeemer, or both), when fees are collected (deposit, redemption, +or both), the exact rate, and where fees are routed. A governance-activatable +fee switch with an initial zero rate, gated by the admin authority per +RFP-001, is the recommended baseline, consistent with the pattern used +elsewhere in the Logos RFP set (see +[RFP-017](./RFP-017-token-vesting.md), "Fee structure"). + +## ✅ Scope of Work + +### Hard Requirements + +Use FURPS framework. Each numbered item should be a testable statement. + +#### Functionality + +1. Implement an Ethereum vault contract (Solidity) that accepts deposits of any + ERC-20 token in the supported-token registry, plus native ETH (auto-wrapped + to WETH by the vault). Each deposit locks the token and emits a + `Deposit(token, depositor, amount, lezRecipient, nonce)` event with a + monotonically increasing `nonce`. +2. Implement an attestor federation daemon (M-of-N, default 3-of-5) that + observes finalised Ethereum deposits, verifies them independently, and + signs a secp256k1 ECDSA attestation over `(token, depositor, amount, + lezRecipient, nonce)`. Attestors must not sign before the configured + Ethereum finality depth is reached. +3. Implement a public-mode LEZ bridge program that verifies the M-of-N + attestation threshold (reusing the in-program secp256k1 ECDSA + keccak256 + verification path from [RFP-020](./RFP-020-redstone-oracle-adaptor.md)) and + mints the corresponding wrapped token to `lezRecipient` — to a public or a + private LEZ account, at the recipient's choice. Each deposit `nonce` may be + consumed at most once; a repeat submission of an already-processed nonce + must be rejected without minting. +4. Implement a burn instruction on the LEZ bridge program: a holder burns a + specified amount of a wrapped token, and the program emits a structured + redemption event (per LP-0012) carrying `(token, amount, ethereumRecipient, + redemptionNonce)`. +5. Extend the attestor federation daemon to observe finalised LEZ redemption + events and threshold-sign a release authorisation over `(token, amount, + ethereumRecipient, redemptionNonce)`. +6. The Ethereum vault contract verifies the M-of-N release-authorisation + signature and releases the original ERC-20 (or unwrapped ETH, for WETH + redemptions) to `ethereumRecipient`. Each `redemptionNonce` may be consumed + at most once. +7. An admin authority (per RFP-001, integrated via the SPEL framework where + applicable to the LEZ side) can: register a new supported ERC-20 (Ethereum + address, LEZ wrapped mint, decimals, per-token deposit/redemption caps), + deregister a token, update the per-token caps, add or remove attestors, and + change the M-of-N threshold. Registration and attestor-set changes must be + mirrored consistently on both the Ethereum vault and the LEZ bridge program + (document how the two sides stay in sync and what happens if they + temporarily diverge). +8. A freeze authority (per RFP-002) can pause minting and/or redemption, either + globally or for a single registered token, on both the Ethereum vault and + the LEZ bridge program independently. +9. Global and per-token deposit and redemption caps (configurable by the admin + authority) bound the maximum value that can be minted or released within a + rolling window, as a rate-limiting circuit breaker independent of the + freeze authority. + +#### Usability + +1. Provide an SDK that can be used to build Logos modules for: submitting + deposits to the Ethereum vault, querying deposit/attestation/mint status, + initiating a redemption (burn), querying redemption/release status, and + reading the supported-token registry and current attestor set. +2. Provide a Logos mini-app GUI with local build instructions, downloadable + assets, and loadable in Logos app (Basecamp) via git repo. The mini-app must + cover: a deposit flow (connect an Ethereum wallet, approve and deposit, + track attestation progress, confirm LEZ mint, choose public or private + destination account), a redemption flow (burn wrapped tokens, track + federation attestation, confirm Ethereum release), and a registry view + (supported tokens, per-token caps and current utilisation, attestor set, + current M-of-N threshold). +3. Provide a CLI that covers core functionality: deposit, query status, redeem, + and query the token registry and attestor set. The CLI may have fewer + features than the mini-app but must support all essential operations. +4. Provide the attestor federation daemon as a **Logos module accompanied by a + Logos Core headless CLI/daemon**, so federation members can run it as a + standalone long-running process. The daemon must support: configurable + Ethereum and LEZ RPC endpoints, configurable finality depth for both + chains, structured logging of observed deposits/redemptions and submitted + attestations, signer-key management appropriate for production use (the + daemon must not require the attestor's key to be stored in plaintext + configuration), and a clean shutdown path. Document the attestor operator + journey end-to-end: install, configure, run, monitor, rotate keys. +5. Provide an IDL for the LEZ bridge program using the + [SPEL framework](https://github.com/logos-co/spel). +6. Return clear, actionable error messages for all failure modes: unsupported + token, cap exceeded, attestation threshold not met, signer not in the + authorised attestor set, insufficient finality, nonce already processed, + and program or per-token frozen. + +#### Reliability + +1. Minting is atomic: a failed or rejected mint attempt does not consume the + deposit nonce and leaves the deposit mintable on retry. +2. Burn-and-redeem is atomic: a failed redemption attempt does not burn tokens + without a corresponding, retryable redemption record. +3. A deposit or redemption nonce can be consumed at most once; replaying an + already-processed attestation or release authorisation is rejected + deterministically and does not double-mint or double-release. +4. Federation liveness tolerates up to `N - M` attestors being offline or + unresponsive without blocking deposits or redemptions. +5. A temporary RPC or connectivity failure on either chain leaves the attestor + daemon in a recoverable state, able to resume observing and signing once + connectivity is restored, without needing to replay already-attested items. + +#### Performance + +1. Verifying an M-of-N attestation (secp256k1 ECDSA + keccak256, in-program on + LEZ) and minting must complete within a single LEZ public transaction at the + per-transaction compute budget in force at delivery time. Document the + compute-unit cost, extending the measurement methodology from + [RFP-020](./RFP-020-redstone-oracle-adaptor.md). +2. Document the Ethereum-side gas cost of verifying the M-of-N release + authorisation and releasing funds from the vault, and compare it against + the native-ECDSA cost range RFP-020 documents for EVM connectors (roughly + 50K–100K gas), since release-side verification runs as ordinary EVM + `ecrecover`, not in a zkVM circuit. +3. Document end-to-end deposit latency (deposit submission to LEZ mint + confirmation) and end-to-end redemption latency (burn to Ethereum release + confirmation), each broken down by: chain finality wait, attestor + observation and signing time, and on-chain verification time. + +#### Supportability + +1. The Ethereum vault contract and the LEZ bridge program are deployed and + tested on a public Ethereum testnet and LEZ devnet/testnet respectively. +2. End-to-end integration tests exercise the full deposit and redemption round + trip against a LEZ sequencer (standalone mode) and an Ethereum test network + or local fork, and are included in CI. CI must be green on the default + branch. +3. Every hard requirement in Functionality, Usability, Reliability, and + Performance has at least one corresponding test. +4. A README documents end-to-end usage: contract and program addresses, + deployment steps for both chains, and step-by-step instructions for + depositing and redeeming via CLI and mini-app. +5. Submit a + [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) + for the SDK, covering the developer integration journey for both deposit + and redemption flows. +6. Submit a + [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) + for the CLI and the attestor daemon, covering the core user and operator + journeys respectively. +7. Provide Figma designs or equivalent for all mini-app GUI artefacts. +8. The Ethereum vault contract undergoes an independent third-party + smart-contract security audit before mainnet deployment; the audit report + (or a summary, if the full report is not publishable) must be linked from + the README. This requirement exists because cross-chain bridges are the + single most-attacked category of DeFi infrastructure (Chainalysis has + tracked more than $2.8B stolen from bridges since 2022); it is not + optional. +9. Provide a privacy and anonymisation properties document covering: what is + visible on-chain for a deposit and a redemption on both Ethereum and LEZ; + what remains private when minting to, or redeeming from, a LEZ private + account; and what the attestor federation itself can observe about a + depositor or redeemer regardless of the destination account type. + +#### + Bridge Security + +1. No single attestor can mint or release funds alone: the LEZ bridge program + and the Ethereum vault contract must both enforce the configured M-of-N + threshold, and this must be tested with fewer than `M` valid signatures + present. +2. Attestor-set membership and the M-of-N threshold are updatable only by the + admin authority (per RFP-001); the update path must keep the Ethereum vault + and the LEZ bridge program's attestor sets consistent, and the update path + itself must be tested, including a scenario where an attestor's key is + suspected compromised and must be removed. +3. Global and per-token deposit/redemption caps (Functionality #9) bound the + maximum value at risk from a compromised federation within any rolling + window; proposals must document the recommended default caps and the + reasoning behind them. +4. The freeze authority (Functionality #8) must be exercisable independently on + the Ethereum vault and the LEZ bridge program, so that either half can be + paused without requiring the other to be operational or reachable. +5. Attestors must independently re-derive the deposit or redemption tuple from + on-chain data before signing; the daemon must not sign an attestation + supplied to it by a third party without independently verifying it against + the source chain. +6. The bridge's user-facing documentation (mini-app, README, SDK docs) must + state the federated-custodial trust model explicitly (see Design + Rationale, "Trust model") rather than describe the bridge as trustless. + +### Soft Requirements + +1. Batch attestation: amortise verification cost across multiple deposits or + redemptions in a single LEZ transaction, analogous to the multi-feed + batching soft requirement in RFP-020. +2. A configurable per-token redemption delay (in addition to the finality wait) + as an extra circuit-breaker window, allowing the freeze authority to react + to an anomalous large redemption before funds leave the vault. +3. Support for wrapping ERC-20 tokens from additional EVM chains (e.g. + Arbitrum, Base) behind the same federation and program, reusing the token + registry and cap mechanism. +4. A path to reduce the trust model over time: design the attestation + verification as a swappable component (mirroring RFP-020's precompile + swap-out requirement) so that a future light-client or ZK-proof-based + Ethereum verification path can replace the federation without restructuring + the vault or the LEZ bridge program. + +### Out of Scope + +The following are explicitly excluded from this RFP: + +- A trustless bridge design that verifies Ethereum consensus signatures or + Merkle-Patricia state proofs inside the LEZ program. This is a candidate for + a future RFP once in-circuit verification cost on RISC0 makes it practical + (see Design Rationale, "Trust model"). +- Wrapping non-fungible assets (ERC-721, ERC-1155). +- Bitcoin, Monero, and Zcash bridging: these have a dedicated trustless path + via atomic swaps, delivered in [RFP-003](./RFP-003-atomic-swaps.md). +- A governance- or DAO-based attestor selection process. The initial + federation is admin-appointed per RFP-001; a permissionless or + stake-weighted attestor set is a possible future evolution, not required + here. +- Price feeds for wrapped assets. Once a token is wrapped, pricing it (for + lending collateral, DEX pairs, or the reflexive stablecoin) is the + responsibility of the oracle stack + ([RFP-019](./RFP-019-twap-oracle.md), [RFP-020](./RFP-020-redstone-oracle-adaptor.md)), + not this bridge. + +## ⚠ Platform Dependencies + +### Hard dependencies + +#### Admin authority (RFP-001) + +The Functionality requirements specify that an admin authority registers and +deregisters supported tokens, manages the attestor federation's membership and +threshold, and configures caps. These admin-gated functions require the +standardised admin authority library from +[RFP-001](./RFP-001-admin-authority-lib.md). + +#### Freeze authority (RFP-002) + +The Bridge Security requirements specify a freeze authority able to pause +minting and/or redemption, globally or per token, as a circuit breaker +independent of the deposit/redemption caps. This requires the standardised +freeze authority library from +[RFP-002](./RFP-002-freeze-authority-lib.md). + +#### Token mint/burn authorities (LP-0013) + +The LEZ bridge program mints wrapped tokens on verified deposits and burns them +on redemption. This requires the token mint/burn authority primitives in +[LP-0013](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md). + +### Soft dependencies + +#### Event emission (LP-0012) + +Redemption events, and ideally deposit-mint events, are emitted as structured +on-chain events so the attestor daemon and off-chain dashboards can react +without polling every account. +[LP-0012](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) +is **closed** (delivered). + +#### Shared verification core (RFP-020) + +The in-program secp256k1 ECDSA + keccak256 verification path built for the +RedStone oracle adaptor is directly reusable for verifying attestor signatures +here; the message format and signer-set model differ, but the recovery and +hashing primitives do not. This is a soft dependency: the bridge can ship with +its own verifier if RFP-020's library is not yet in a reusable state, but +proposals should default to sharing the audited implementation rather than +duplicating it. + +## 👤 Recommended Team Profile + +Team experienced with: + +- Cross-chain bridge or relayer/federation architecture +- Solidity smart-contract development, including experience preparing a + contract for third-party security audit +- Cryptographic verification (secp256k1 ECDSA recovery, keccak256 hashing, + threshold/multi-signature schemes) +- LEZ / RISC0 program development +- Smart-contract security auditing (signer compromise, replay attacks, + reorg handling, cap/rate-limit bypass) + +## ⏱ Timeline Expectations + +Estimated software delivery duration: **12–14 weeks**. This excludes the +third-party audit lead time required before mainnet deployment (Supportability +#8), which is typically procured and scheduled separately. + +## 🌍 Open Source Requirement + +All code must be released under the **MIT+Apache2.0 dual License**. + +## Resources + +- [RFP-001 — Admin Authority Library](./RFP-001-admin-authority-lib.md) +- [RFP-002 — Freeze Authority Library](./RFP-002-freeze-authority-lib.md) +- [RFP-003 — Atomic Swaps](./RFP-003-atomic-swaps.md) (trustless path for BTC, + XMR, ZEC; explicitly defers ETH to wrapping) +- [RFP-008 — Lending & Borrowing Protocol](./RFP-008-lending-borrowing-protocol.md) + (primary consumer of wrapped collateral) +- [RFP-013 — Reflexive Stablecoin Protocol](./RFP-013-reflexive-stablecoin-protocol.md) + (consumer of wrapped-asset collateral) +- [RFP-019 — On-Chain TWAP Oracle](./RFP-019-twap-oracle.md) (assumes wrapped + external assets as priced collateral) +- [RFP-020 — RedStone Off-Chain Oracle Adaptor for LEZ](./RFP-020-redstone-oracle-adaptor.md) + (source of the reusable secp256k1 ECDSA + keccak256 verification core) +- [LP-0012: Event/Log mechanism for LEZ](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) +- [LP-0013: Token program improvements: mint authorities](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md) +- [Chainalysis — Cross-Chain Bridge Hacks](https://www.chainalysis.com/blog/cross-chain-bridge-hacks-2022/) + (bridge-hack loss data) + +## ✏️ How to Apply + +👉 Submit a proposal using the Issue form: + +**[Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml)** + +We typically respond within **14 days**. For clarification questions, please use +**Discussions**. \ No newline at end of file From 9b277f175d27d809b123ebbbc0f596359f45813d Mon Sep 17 00:00:00 2001 From: jzaki Date: Tue, 4 Aug 2026 18:47:53 +0100 Subject: [PATCH 02/69] Correct to suggest trustless zkproof usage --- RFPs/RFP-021-wrapped-erc20.md | 405 +++++++++++++++++----------------- 1 file changed, 208 insertions(+), 197 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index d0133894..c2a18d4d 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -48,20 +48,19 @@ dependencies: ## 🧭 Overview -Build a lock-and-mint bridge that lets ERC-20 tokens (and native ETH, wrapped as +Build a trustless lock-and-mint bridge that lets ERC-20 tokens (and native ETH, wrapped as WETH) held on Ethereum enter LEZ as canonical wrapped assets, and exit back to Ethereum on redemption. An Ethereum-side vault contract escrows deposits; a -federation of attestors observes finalised deposits and threshold-signs an -attestation; a LEZ-side program verifies the threshold signature and mints the -corresponding wrapped token to the recipient's LEZ account. Redemption reverses -the flow: burning the wrapped token on LEZ triggers a federation-attested -release of the original ERC-20 from the vault. The verification core reuses the -in-program secp256k1 ECDSA + keccak256 path already built for -[RFP-020](./RFP-020-redstone-oracle-adaptor.md), so this RFP is primarily new -protocol wiring (vault contract, mint/burn program, federation daemon) rather -than new cryptographic groundwork. Teams should have experience with Solidity -smart-contract development, cross-chain relayer/federation architecture, and LEZ -program development. +RISC0-based cryptographic proof of the deposit (verifying Ethereum consensus and +state) is generated and submitted to a LEZ-side program, which verifies the proof +in-program and mints the corresponding wrapped token to the recipient's LEZ +account. Redemption reverses the flow: burning the wrapped token on LEZ triggers +generation of a zero-knowledge proof of the burn, which is verified on-chain by +the Ethereum vault via a native precompile, releasing the original ERC-20 from +the vault. The bridge core depends on mature RISC0 implementations (e.g. Zisk) +for consensus and state proof generation, requiring teams experienced with +zero-knowledge proof systems, Solidity smart-contract development, LEZ program +development, and RISC0 guest environments. ## 🔥 Why This Matters @@ -81,10 +80,11 @@ and is a much simpler construction." Bitcoin, Monero, and Zcash lack general smart-contract expressiveness, so a trustless swap protocol (adaptor signatures, HTLCs, DLEQ proofs) is the only construction available for them. Ethereum's programmability makes a lock-and-mint bridge with a vault contract -possible instead, which is the standard architecture used to move value onto -every smart-contract chain that isn't Ethereum itself. It is simpler to build -than a trustless swap, but it is not trustless: it introduces a federation -trust assumption that this RFP must document honestly rather than obscure. +and zero-knowledge proof verification possible instead, which is the trustless +architecture used to move value onto smart-contract chains that verify +cryptographic proofs natively. This RFP delivers that trustless construction +via RISC0 zero-knowledge proofs, matching LEZ's cryptographic verification +capability with Ethereum's native precompile support for proof verification. Stablecoins are the concrete prize. USDT and USDC together account for over 80% of a stablecoin market that stood above $300B in mid-2026, and are the @@ -96,44 +96,42 @@ stablecoin from having any credible collateral base at launch. Bridges are also the most attacked category of infrastructure in DeFi: Chainalysis has tracked more than $2.8B stolen from cross-chain bridges since 2022, the highest-value class of exploit in the industry. This RFP's security -posture — a bounded, capped, admin-governed federation with a freeze-authority -circuit breaker, rather than an unbounded trust-me bridge — is designed -directly against that track record, and is explained in full in Design -Rationale and the Bridge Security requirements below. +posture — cryptographic verification via RISC0 zero-knowledge proofs, eliminating +the trust-in-signers vector entirely, combined with per-token and global +deposit/redemption caps and an admin-governed freeze-authority circuit +breaker — is designed directly against that track record. The trustless +cryptographic core ensures that no signer compromise, key theft, or participant +collusion can lead to spurious minting or release, and is explained in full in +Design Rationale and the Bridge Security requirements below. ## 🏗 Design Rationale -### Lock-and-mint via a federated attestor set +### Trustless lock-and-mint via zero-knowledge proofs -The bridge has two independently deployed halves that share one verification -primitive: +The bridge has two independently deployed halves unified by a cryptographic +proof-verification primitive: 1. **Ethereum vault contract.** A Solidity contract that accepts deposits of any ERC-20 token in the supported-token registry (plus native ETH, which the vault wraps to WETH internally so ETH does not need a separate bridging path). Each deposit locks the token and emits a `Deposit(token, depositor, amount, lezRecipient, nonce)` event. -2. **Attestor federation.** An M-of-N set of attestors (default 3-of-5, - configurable, registered and rotated by the admin authority per RFP-001) - watches the Ethereum vault. Once a deposit reaches a configured finality - depth, each attestor independently verifies the deposit and signs a - secp256k1 ECDSA attestation over `(token, depositor, amount, lezRecipient, - nonce)`. -3. **LEZ bridge program.** A public-mode LEZ program verifies the M-of-N - threshold over the attestation — reusing the same in-program secp256k1 ECDSA - + keccak256 verification path built for the RedStone adaptor - ([RFP-020](./RFP-020-redstone-oracle-adaptor.md), Functionality #1–#2) — and - mints the corresponding wrapped token to `lezRecipient`, crediting a private - account directly where the recipient requests it (see "+ Privacy" below). - The deposit `nonce` is recorded on first use and any repeat submission of the - same nonce is rejected, so replaying an attestation cannot double-mint. - -This is the same "signed attestation verified in-program" shape RFP-020 already -proved out for oracle data; the message being signed changes (a deposit tuple -instead of a price) but the verifier, the signer-set management, and the -M-of-N threshold logic are the same problem. Proposals are expected to share -code with, or directly depend on, the RFP-020 verification library rather than -reimplementing ECDSA recovery from scratch. +2. **RISC0 proof generator (inbound).** An off-chain service (leveraging mature + RISC0 implementations such as Zisk) that observes Ethereum deposits reaching + finality, generates a zero-knowledge proof verifying (1) the Ethereum + consensus state at a specific block height, and (2) the deposit event state + in that block. The proof is deterministically derived from the deposit tuple + `(token, depositor, amount, lezRecipient, nonce)` and Ethereum chain state. +3. **LEZ bridge program (inbound).** A public-mode LEZ program verifies the RISC0 + proof in-program (validating Ethereum consensus and the inclusion of the + deposit event) and mints the corresponding wrapped token to `lezRecipient`, + crediting a private account directly where the recipient requests it (see + "+ Privacy" below). The deposit `nonce` is recorded on first use and any + repeat submission of the same nonce is rejected, preventing double-mint. + +No signer set, threshold signature, or attestor federation is required. The +proof's correctness is cryptographically ensured by the RISC0 circuit; no trust +in external parties is introduced. ### Redemption: burn-and-release @@ -141,13 +139,15 @@ Redemption is the mirror flow. A holder burns wrapped tokens on LEZ via the bridge program, which validates the burn and emits a structured redemption event (per [LP-0012](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md)) carrying `(token, amount, ethereumRecipient, redemptionNonce)`. Once the burn -transaction reaches LEZ finality, the attestor federation observes the -redemption event and threshold-signs a release authorisation. The Ethereum -vault verifies the M-of-N signature — native `ecrecover` on the EVM, orders of -magnitude cheaper than the in-program RISC-V path, matching the asymmetry -RFP-020 already documented between LEZ-side and EVM-side ECDSA verification -cost — and releases the original ERC-20 to `ethereumRecipient`, tracking -`redemptionNonce` to reject replays on the Ethereum side. +transaction reaches LEZ finality, an off-chain service generates a RISC0 +zero-knowledge proof verifying (1) the LEZ consensus state at a specific epoch, +and (2) the burn event in that state. The Ethereum vault receives the proof and +verifies it natively via a precompile (Groth16 verifier on-chain or equivalent) +— a single verification step, orders of magnitude cheaper than the in-program +RISC-V path and matching the cost asymmetry documented in RFP-020 between +LEZ-side and EVM-side cryptographic verification. Upon successful proof +verification, the vault releases the original ERC-20 to `ethereumRecipient`, +tracking `redemptionNonce` to reject replays on the Ethereum side. ### Token registry and decimal normalisation @@ -173,23 +173,21 @@ it leaves. The reverse direction (LEZ burn to Ethereum release) is symmetric: attestors wait for LEZ finality on the burn transaction before co-signing a release. -### Trust model: federated custodial, not trustless - -This bridge is **not** trustless. It composes with RFP-003's trustless BTC, -XMR, and ZEC swaps, not with the same security model: a user who bridges an -ERC-20 asset is trusting that at least `M` of the `N` attestors are honest and -that their keys are not simultaneously compromised. Proposals must state this -trust assumption plainly in user-facing documentation (mini-app, README, -SDK docs), rather than presenting the bridge as trust-minimised. Per-token and -global caps, the freeze-authority circuit breaker, and a documented attestor -rotation process (see Bridge Security) are the mitigations this RFP requires in -lieu of trustlessness; they bound the blast radius of a federation compromise, -they do not eliminate it. A fully trustless design — verifying Ethereum -consensus signatures or Merkle-Patricia state proofs inside the LEZ program — -is out of scope (see Out of Scope) and is a candidate for a future RFP once -in-circuit verification cost on RISC0 makes it practical, mirroring the -cost-conditional precompile path RFP-020 already laid out for its own -verification primitive. +### Trust model: cryptographic, trustless + +This bridge is **trustless**. It requires no trust in external signers, validators, +or attestor federations. A user who bridges an ERC-20 asset relies only on the +correctness of the RISC0 circuit (verifying Ethereum consensus and state inclusion), +the security of the Ethereum network itself, and the security of the LEZ network. +Both inbound and outbound flows are verified by immutable cryptographic proofs, +not by signatures from a bounded set of participants. + +Proposals must state this trustlessness explicitly in user-facing documentation +(mini-app, README, SDK docs). Per-token and global deposit/redemption caps, and +the freeze-authority circuit breaker (see Bridge Security), remain in place as +operational safety mechanisms independent of the cryptographic trust model. They +bound the operational blast radius and provide an administrative pause capability, +but are orthogonal to the bridge's trustlessness. ### Fee structure @@ -214,37 +212,38 @@ Use FURPS framework. Each numbered item should be a testable statement. to WETH by the vault). Each deposit locks the token and emits a `Deposit(token, depositor, amount, lezRecipient, nonce)` event with a monotonically increasing `nonce`. -2. Implement an attestor federation daemon (M-of-N, default 3-of-5) that - observes finalised Ethereum deposits, verifies them independently, and - signs a secp256k1 ECDSA attestation over `(token, depositor, amount, - lezRecipient, nonce)`. Attestors must not sign before the configured - Ethereum finality depth is reached. -3. Implement a public-mode LEZ bridge program that verifies the M-of-N - attestation threshold (reusing the in-program secp256k1 ECDSA + keccak256 - verification path from [RFP-020](./RFP-020-redstone-oracle-adaptor.md)) and - mints the corresponding wrapped token to `lezRecipient` — to a public or a - private LEZ account, at the recipient's choice. Each deposit `nonce` may be - consumed at most once; a repeat submission of an already-processed nonce - must be rejected without minting. +2. Implement an inbound RISC0 proof generator that observes finalised Ethereum + deposits, constructs a proof of the deposit (verifying Ethereum consensus at + a configured finality depth and the deposit event's inclusion in that state), + and outputs a proof artifact ready for on-chain verification. The proof must + encode `(token, depositor, amount, lezRecipient, nonce)` and be + deterministically reproducible from chain state. +3. Implement a public-mode LEZ bridge program that accepts an inbound RISC0 + proof, verifies it in-program (validating Ethereum consensus and state + inclusion), and mints the corresponding wrapped token to `lezRecipient` — to + a public or a private LEZ account, at the recipient's choice. Each deposit + `nonce` may be consumed at most once; a repeat submission of an + already-processed nonce must be rejected without minting. 4. Implement a burn instruction on the LEZ bridge program: a holder burns a specified amount of a wrapped token, and the program emits a structured redemption event (per LP-0012) carrying `(token, amount, ethereumRecipient, redemptionNonce)`. -5. Extend the attestor federation daemon to observe finalised LEZ redemption - events and threshold-sign a release authorisation over `(token, amount, - ethereumRecipient, redemptionNonce)`. -6. The Ethereum vault contract verifies the M-of-N release-authorisation - signature and releases the original ERC-20 (or unwrapped ETH, for WETH - redemptions) to `ethereumRecipient`. Each `redemptionNonce` may be consumed - at most once. +5. Implement an outbound RISC0 proof generator that observes finalised LEZ burn + events, constructs a proof of the burn (verifying LEZ consensus at a + configured finality depth and the burn event's inclusion in that state), and + outputs a proof artifact ready for on-chain Ethereum verification. The proof + must encode `(token, amount, ethereumRecipient, redemptionNonce)` and be + deterministically reproducible from chain state. +6. The Ethereum vault contract accepts an outbound RISC0 proof and verifies it + natively via a precompile (Groth16 verifier or equivalent), releasing the + original ERC-20 (or unwrapped ETH, for WETH redemptions) to + `ethereumRecipient`. Each `redemptionNonce` may be consumed at most once. 7. An admin authority (per RFP-001, integrated via the SPEL framework where applicable to the LEZ side) can: register a new supported ERC-20 (Ethereum - address, LEZ wrapped mint, decimals, per-token deposit/redemption caps), - deregister a token, update the per-token caps, add or remove attestors, and - change the M-of-N threshold. Registration and attestor-set changes must be - mirrored consistently on both the Ethereum vault and the LEZ bridge program - (document how the two sides stay in sync and what happens if they - temporarily diverge). + address, LEZ wrapped mint, decimals, per-token deposit/redemption caps), and + deregister a token. Registration changes must be mirrored consistently on + both the Ethereum vault and the LEZ bridge program (document how the two + sides stay in sync and what happens if they temporarily diverge). 8. A freeze authority (per RFP-002) can pause minting and/or redemption, either globally or for a single registered token, on both the Ethereum vault and the LEZ bridge program independently. @@ -256,35 +255,33 @@ Use FURPS framework. Each numbered item should be a testable statement. #### Usability 1. Provide an SDK that can be used to build Logos modules for: submitting - deposits to the Ethereum vault, querying deposit/attestation/mint status, - initiating a redemption (burn), querying redemption/release status, and - reading the supported-token registry and current attestor set. + deposits to the Ethereum vault, querying deposit/proof/mint status, querying + inbound proof generation progress, initiating a redemption (burn), querying + redemption/proof/release status, and reading the supported-token registry. 2. Provide a Logos mini-app GUI with local build instructions, downloadable assets, and loadable in Logos app (Basecamp) via git repo. The mini-app must cover: a deposit flow (connect an Ethereum wallet, approve and deposit, - track attestation progress, confirm LEZ mint, choose public or private - destination account), a redemption flow (burn wrapped tokens, track - federation attestation, confirm Ethereum release), and a registry view - (supported tokens, per-token caps and current utilisation, attestor set, - current M-of-N threshold). + track proof generation progress, confirm LEZ mint, choose public or private + destination account), a redemption flow (burn wrapped tokens, track proof + generation, confirm Ethereum release), and a registry view (supported tokens, + per-token caps and current utilisation). 3. Provide a CLI that covers core functionality: deposit, query status, redeem, - and query the token registry and attestor set. The CLI may have fewer - features than the mini-app but must support all essential operations. -4. Provide the attestor federation daemon as a **Logos module accompanied by a - Logos Core headless CLI/daemon**, so federation members can run it as a - standalone long-running process. The daemon must support: configurable - Ethereum and LEZ RPC endpoints, configurable finality depth for both - chains, structured logging of observed deposits/redemptions and submitted - attestations, signer-key management appropriate for production use (the - daemon must not require the attestor's key to be stored in plaintext - configuration), and a clean shutdown path. Document the attestor operator - journey end-to-end: install, configure, run, monitor, rotate keys. + and query the token registry. The CLI may have fewer features than the + mini-app but must support all essential operations. +4. Provide the inbound and outbound RISC0 proof generators as **Logos modules + accompanied by Logos Core headless CLI/daemons**, so operators can run them + as standalone long-running processes. Each daemon must support: configurable + Ethereum and/or LEZ RPC endpoints, configurable finality depth for the source + chain, structured logging of observed events and generated proofs, and a + clean shutdown path. The proof generators must integrate with or wrap mature + RISC0 implementations (e.g. Zisk) without reimplementing zero-knowledge + primitives. Document the operator journey end-to-end: install, configure, run, + monitor. 5. Provide an IDL for the LEZ bridge program using the [SPEL framework](https://github.com/logos-co/spel). 6. Return clear, actionable error messages for all failure modes: unsupported - token, cap exceeded, attestation threshold not met, signer not in the - authorised attestor set, insufficient finality, nonce already processed, - and program or per-token frozen. + token, cap exceeded, invalid proof, proof verification failure, insufficient + finality, nonce already processed, and program or per-token frozen. #### Reliability @@ -293,30 +290,38 @@ Use FURPS framework. Each numbered item should be a testable statement. 2. Burn-and-redeem is atomic: a failed redemption attempt does not burn tokens without a corresponding, retryable redemption record. 3. A deposit or redemption nonce can be consumed at most once; replaying an - already-processed attestation or release authorisation is rejected - deterministically and does not double-mint or double-release. -4. Federation liveness tolerates up to `N - M` attestors being offline or - unresponsive without blocking deposits or redemptions. -5. A temporary RPC or connectivity failure on either chain leaves the attestor - daemon in a recoverable state, able to resume observing and signing once - connectivity is restored, without needing to replay already-attested items. + already-verified proof is rejected deterministically and does not + double-mint or double-release. +4. Proof generation is deterministic: given the same chain state and input + parameters, proof generators must produce the same proof (or provably + equivalent proofs if the RISC0 implementation supports non-determinism). + This ensures that multiple independent proof generators can verify each + other's work and that replaying a proof from cache is safe. +5. A temporary RPC or connectivity failure on either chain leaves the proof + generator daemon in a recoverable state, able to resume observing and + generating proofs once connectivity is restored, without needing to replay + already-proven items. #### Performance -1. Verifying an M-of-N attestation (secp256k1 ECDSA + keccak256, in-program on - LEZ) and minting must complete within a single LEZ public transaction at the - per-transaction compute budget in force at delivery time. Document the - compute-unit cost, extending the measurement methodology from - [RFP-020](./RFP-020-redstone-oracle-adaptor.md). -2. Document the Ethereum-side gas cost of verifying the M-of-N release - authorisation and releasing funds from the vault, and compare it against - the native-ECDSA cost range RFP-020 documents for EVM connectors (roughly - 50K–100K gas), since release-side verification runs as ordinary EVM - `ecrecover`, not in a zkVM circuit. +1. Verifying an inbound RISC0 proof (Ethereum consensus + state inclusion, + in-program on LEZ) and minting must complete within a single LEZ public + transaction at the per-transaction compute budget in force at delivery time. + Document the compute-unit cost, including the cost breakdown for the RISC0 + proof verification and the LEZ mint instruction, extending the measurement + methodology from [RFP-020](./RFP-020-redstone-oracle-adaptor.md). +2. Document the Ethereum-side gas cost of verifying the outbound RISC0 proof + via a precompile (Groth16 verifier or equivalent) and releasing funds from + the vault. Benchmark against the gas costs for comparable proof-verification + precompiles on EVM networks where available (e.g. Ethereum's Groth16 + verifier, Arbitrum's curve pairing precompile). 3. Document end-to-end deposit latency (deposit submission to LEZ mint confirmation) and end-to-end redemption latency (burn to Ethereum release - confirmation), each broken down by: chain finality wait, attestor - observation and signing time, and on-chain verification time. + confirmation), each broken down by: chain finality wait, proof generation + time, and on-chain verification time. +4. Document the RISC0 proof generation time for both inbound (Ethereum → LEZ) + and outbound (LEZ → Ethereum) proofs, and characterize the compute resources + (CPU, RAM, time) required to run a proof generator daemon. #### Supportability @@ -337,8 +342,8 @@ Use FURPS framework. Each numbered item should be a testable statement. and redemption flows. 6. Submit a [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for the CLI and the attestor daemon, covering the core user and operator - journeys respectively. + for the CLI and the proof generators (inbound and outbound), covering the + core user and operator journeys respectively. 7. Provide Figma designs or equivalent for all mini-app GUI artefacts. 8. The Ethereum vault contract undergoes an independent third-party smart-contract security audit before mainnet deployment; the audit report @@ -350,67 +355,71 @@ Use FURPS framework. Each numbered item should be a testable statement. 9. Provide a privacy and anonymisation properties document covering: what is visible on-chain for a deposit and a redemption on both Ethereum and LEZ; what remains private when minting to, or redeeming from, a LEZ private - account; and what the attestor federation itself can observe about a - depositor or redeemer regardless of the destination account type. + account; what the proof generators can observe about a depositor or + redeemer from RPC queries to either chain; and what information is + irretrievably obfuscated by the bridge's design. #### + Bridge Security -1. No single attestor can mint or release funds alone: the LEZ bridge program - and the Ethereum vault contract must both enforce the configured M-of-N - threshold, and this must be tested with fewer than `M` valid signatures - present. -2. Attestor-set membership and the M-of-N threshold are updatable only by the - admin authority (per RFP-001); the update path must keep the Ethereum vault - and the LEZ bridge program's attestor sets consistent, and the update path - itself must be tested, including a scenario where an attestor's key is - suspected compromised and must be removed. +1. RISC0 proof verification must be deterministic and verifiable by any + participant independently. The LEZ bridge program and Ethereum vault contract + must both reject proofs that fail verification, and this must be tested with + invalid proofs (e.g. proofs with incorrect public inputs, proofs for incorrect + chain state, proofs with tampered headers). +2. Proof generators must independently derive the deposit or burn tuple and chain + state from RPC calls to the source chain; the daemon must not accept a proof + supplied to it by a third party without independently regenerating and + verifying it against the source chain. 3. Global and per-token deposit/redemption caps (Functionality #9) bound the - maximum value at risk from a compromised federation within any rolling - window; proposals must document the recommended default caps and the - reasoning behind them. + maximum value at risk within any rolling window; proposals must document the + recommended default caps and the reasoning behind them. These caps are + independent of proof verification and operate as an additional administrative + safety valve. 4. The freeze authority (Functionality #8) must be exercisable independently on the Ethereum vault and the LEZ bridge program, so that either half can be paused without requiring the other to be operational or reachable. -5. Attestors must independently re-derive the deposit or redemption tuple from - on-chain data before signing; the daemon must not sign an attestation - supplied to it by a third party without independently verifying it against - the source chain. -6. The bridge's user-facing documentation (mini-app, README, SDK docs) must - state the federated-custodial trust model explicitly (see Design - Rationale, "Trust model") rather than describe the bridge as trustless. +5. The bridge's user-facing documentation (mini-app, README, SDK docs) must + state the trustless cryptographic verification model explicitly (see Design + Rationale, "Trust model") and explain how RISC0 proofs ensure the integrity + of cross-chain transfers without requiring trust in external signers. ### Soft Requirements -1. Batch attestation: amortise verification cost across multiple deposits or - redemptions in a single LEZ transaction, analogous to the multi-feed +1. Batch proof verification: amortise verification cost across multiple deposits + or redemptions in a single LEZ transaction, analogous to the multi-feed batching soft requirement in RFP-020. -2. A configurable per-token redemption delay (in addition to the finality wait) +2. Proof caching and relay: allow pre-generated and verified proofs to be cached + and resubmitted by users or relayers, reducing the need for everyone to + generate proofs independently (proof generators produce canonical proofs that + can be reused). +3. A configurable per-token redemption delay (in addition to the finality wait) as an extra circuit-breaker window, allowing the freeze authority to react to an anomalous large redemption before funds leave the vault. -3. Support for wrapping ERC-20 tokens from additional EVM chains (e.g. - Arbitrum, Base) behind the same federation and program, reusing the token - registry and cap mechanism. -4. A path to reduce the trust model over time: design the attestation - verification as a swappable component (mirroring RFP-020's precompile - swap-out requirement) so that a future light-client or ZK-proof-based - Ethereum verification path can replace the federation without restructuring - the vault or the LEZ bridge program. +4. Support for wrapping ERC-20 tokens from additional EVM chains (e.g. + Arbitrum, Base) behind the same LEZ bridge program, reusing the token + registry and cap mechanism and generating separate RISC0 proofs for each + source chain's consensus and state. +5. A path to improve proof generation over time: design the RISC0 proof + generator as a pluggable component so that optimizations to the RISC0 circuit + (e.g. via future RISC0 zkVM improvements, proof compression, or hardware + acceleration) can be integrated without restructuring the vault or bridge + program. ### Out of Scope The following are explicitly excluded from this RFP: -- A trustless bridge design that verifies Ethereum consensus signatures or - Merkle-Patricia state proofs inside the LEZ program. This is a candidate for - a future RFP once in-circuit verification cost on RISC0 makes it practical - (see Design Rationale, "Trust model"). - Wrapping non-fungible assets (ERC-721, ERC-1155). - Bitcoin, Monero, and Zcash bridging: these have a dedicated trustless path via atomic swaps, delivered in [RFP-003](./RFP-003-atomic-swaps.md). -- A governance- or DAO-based attestor selection process. The initial - federation is admin-appointed per RFP-001; a permissionless or - stake-weighted attestor set is a possible future evolution, not required - here. +- Circuit optimization or custom RISC0 accelerators: proposals should leverage + mature existing RISC0 implementations (e.g. Zisk) rather than implementing + novel circuits or optimization techniques. Future improvements to RISC0 + circuit performance are a separate effort from this bridge implementation. +- Alternative proof systems (e.g. SNARKs, STARKs, other zkVMs): this RFP + specifies RISC0 as the proof system. If future RISC0 versions or alternative + systems become preferable, that is a candidate for a future update or new + RFP. - Price feeds for wrapped assets. Once a token is wrapped, pricing it (for lending collateral, DEX pairs, or the reflexive stablecoin) is the responsibility of the oracle stack @@ -424,9 +433,8 @@ The following are explicitly excluded from this RFP: #### Admin authority (RFP-001) The Functionality requirements specify that an admin authority registers and -deregisters supported tokens, manages the attestor federation's membership and -threshold, and configures caps. These admin-gated functions require the -standardised admin authority library from +deregisters supported tokens and configures deposit/redemption caps. These +admin-gated functions require the standardised admin authority library from [RFP-001](./RFP-001-admin-authority-lib.md). #### Freeze authority (RFP-002) @@ -443,38 +451,39 @@ The LEZ bridge program mints wrapped tokens on verified deposits and burns them on redemption. This requires the token mint/burn authority primitives in [LP-0013](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md). +#### RISC0 zkVM + +The bridge verifies cryptographic proofs in-program (inbound on LEZ) and +natively on Ethereum (outbound). Proof generation and verification require +RISC0, a production-ready zkVM. Proposals must leverage mature RISC0 +implementations (e.g. [Zisk](https://github.com/risc0/zisk)) rather than +building custom circuits. + ### Soft dependencies #### Event emission (LP-0012) Redemption events, and ideally deposit-mint events, are emitted as structured -on-chain events so the attestor daemon and off-chain dashboards can react +on-chain events so off-chain proof generators and dashboards can react without polling every account. [LP-0012](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) is **closed** (delivered). -#### Shared verification core (RFP-020) - -The in-program secp256k1 ECDSA + keccak256 verification path built for the -RedStone oracle adaptor is directly reusable for verifying attestor signatures -here; the message format and signer-set model differ, but the recovery and -hashing primitives do not. This is a soft dependency: the bridge can ship with -its own verifier if RFP-020's library is not yet in a reusable state, but -proposals should default to sharing the audited implementation rather than -duplicating it. - ## 👤 Recommended Team Profile Team experienced with: -- Cross-chain bridge or relayer/federation architecture +- Zero-knowledge proof systems and RISC0 zkVM (guest program development, + proof generation and verification, public/private input handling) - Solidity smart-contract development, including experience preparing a - contract for third-party security audit -- Cryptographic verification (secp256k1 ECDSA recovery, keccak256 hashing, - threshold/multi-signature schemes) -- LEZ / RISC0 program development -- Smart-contract security auditing (signer compromise, replay attacks, + contract for third-party security audit, and EVM precompile integration +- Cryptographic primitives (Groth16 verification, Merkle proofs, consensus + verification, state root inclusion proofs) +- LEZ program development and on-chain proof verification +- Smart-contract security auditing (proof validation, replay attacks, reorg handling, cap/rate-limit bypass) +- Cross-chain system design and integration testing (dual-chain atomic + operations, finality assumptions, determinism and reproducibility) ## ⏱ Timeline Expectations @@ -499,9 +508,11 @@ All code must be released under the **MIT+Apache2.0 dual License**. - [RFP-019 — On-Chain TWAP Oracle](./RFP-019-twap-oracle.md) (assumes wrapped external assets as priced collateral) - [RFP-020 — RedStone Off-Chain Oracle Adaptor for LEZ](./RFP-020-redstone-oracle-adaptor.md) - (source of the reusable secp256k1 ECDSA + keccak256 verification core) + (reference for in-program proof verification cost measurement) - [LP-0012: Event/Log mechanism for LEZ](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) - [LP-0013: Token program improvements: mint authorities](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md) +- [RISC0 — Zero-Knowledge VM](https://github.com/risc0/risc0) +- [Zisk — RISC0 Proof Generation](https://github.com/risc0/zisk) (reference implementation for proof generation) - [Chainalysis — Cross-Chain Bridge Hacks](https://www.chainalysis.com/blog/cross-chain-bridge-hacks-2022/) (bridge-hack loss data) From 275c54d0b960516c6e45cab5e35cfb3fc371b41f Mon Sep 17 00:00:00 2001 From: jzaki Date: Thu, 6 Aug 2026 06:57:26 +0100 Subject: [PATCH 03/69] Suggest privacy design --- RFPs/RFP-021-wrapped-erc20.md | 924 +++++++++++++++++++++++----------- 1 file changed, 620 insertions(+), 304 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index c2a18d4d..daec0882 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -1,21 +1,21 @@ --- id: RFP-021 -title: Wrapped ERC-20 Bridge for LEZ +title: Unlinkable Wrapped ERC-20 Bridge for LEZ tier: L status: open category: Developer Tooling & Infrastructure dependencies: - id: RFP-001 - reason: Admin authority governs the supported-token registry and the attestor federation's membership and threshold, as specified in Functionality. + reason: Admin authority governs the supported-token registry, the per-token denomination ladder, and the deposit/redemption caps, as specified in Functionality. - id: RFP-002 - reason: Freeze authority provides the circuit breaker to halt minting and/or redemption, globally or per token, if the attestor federation or the Ethereum-side vault is suspected compromised. + reason: Freeze authority provides the circuit breaker to halt minting and/or redemption, globally or per token, if a circuit bug or vault vulnerability is suspected. - id: LP-0013 - reason: Mint/burn token authority primitives are required for the LEZ program to mint wrapped tokens on deposit and burn them on redemption. + reason: Mint/burn token authority primitives are required for the LEZ program to mint wrapped tokens into private state on verified deposit, and burn them on redemption. --- -# RFP-021 — Wrapped ERC-20 Bridge for LEZ +# RFP-021 — Unlinkable Wrapped ERC-20 Bridge for LEZ > **Note.** This specification describes an outcome that may benefit the Logos > ecosystem. It is a proposal rather than an instruction. Its requirements @@ -48,18 +48,29 @@ dependencies: ## 🧭 Overview -Build a trustless lock-and-mint bridge that lets ERC-20 tokens (and native ETH, wrapped as -WETH) held on Ethereum enter LEZ as canonical wrapped assets, and exit back to -Ethereum on redemption. An Ethereum-side vault contract escrows deposits; a -RISC0-based cryptographic proof of the deposit (verifying Ethereum consensus and -state) is generated and submitted to a LEZ-side program, which verifies the proof -in-program and mints the corresponding wrapped token to the recipient's LEZ -account. Redemption reverses the flow: burning the wrapped token on LEZ triggers -generation of a zero-knowledge proof of the burn, which is verified on-chain by -the Ethereum vault via a native precompile, releasing the original ERC-20 from -the vault. The bridge core depends on mature RISC0 implementations (e.g. Zisk) -for consensus and state proof generation, requiring teams experienced with -zero-knowledge proof systems, Solidity smart-contract development, LEZ program +Build a trustless, **unlinkable** lock-and-mint bridge that lets ERC-20 tokens +(and native ETH, wrapped as WETH) held on Ethereum enter LEZ as canonical +wrapped assets, and exit back to Ethereum on redemption — without any public +observer being able to connect a specific Ethereum lock to the LEZ mint it +funded, or a specific LEZ burn to the Ethereum unlock it triggered. + +An Ethereum-side vault contract escrows deposits and publishes only a +*commitment* — never a LEZ recipient. A LEZ-side program trustlessly anchors the +Ethereum commitment-tree root by verifying a RISC0 proof of Ethereum consensus +and state in-program. A user then proves, entirely on their own device, that +they own an unspent leaf under that anchored root, and the program mints the +wrapped token into **private LEZ state**. Redemption mirrors this: a burn on LEZ +publishes only a withdrawal commitment — never an Ethereum recipient — and the +Ethereum vault, having anchored the LEZ burn-tree root via a RISC0 proof +verified through a native precompile, releases the original ERC-20 to whoever +proves ownership of an unspent leaf. + +Nullifiers prevent double-spends on both legs without revealing which leaf was +consumed. Permissionless relayers submit the mint and unlock transactions so the +user never needs a funded account on either chain. The bridge core depends on +mature RISC0 implementations (e.g. Zisk) for consensus and state proof +generation, requiring teams experienced with zero-knowledge proof systems, +shielded-pool constructions, Solidity smart-contract development, LEZ program development, and RISC0 guest environments. ## 🔥 Why This Matters @@ -82,122 +93,310 @@ signatures, HTLCs, DLEQ proofs) is the only construction available for them. Ethereum's programmability makes a lock-and-mint bridge with a vault contract and zero-knowledge proof verification possible instead, which is the trustless architecture used to move value onto smart-contract chains that verify -cryptographic proofs natively. This RFP delivers that trustless construction -via RISC0 zero-knowledge proofs, matching LEZ's cryptographic verification -capability with Ethereum's native precompile support for proof verification. - -Stablecoins are the concrete prize. USDT and USDC together account for over 80% -of a stablecoin market that stood above $300B in mid-2026, and are the -settlement asset most DeFi money markets and DEXes actually run on. Without a -wrapped ERC-20 primitive, LEZ has no path to bring USDC, USDT, DAI, or WETH -liquidity onto the chain, which blocks the lending protocol and the reflexive -stablecoin from having any credible collateral base at launch. +cryptographic proofs natively. + +### A transparent bridge would deanonymise the whole chain + +Unlinkability is not a nice-to-have here; it is the difference between this +bridge strengthening LEZ's privacy guarantees and silently destroying them. + +A conventional lock-and-mint bridge emits +`Deposit(token, depositor, amount, lezRecipient, nonce)` on Ethereum. That +single event publicly binds a KYC'd, fully-traced Ethereum address to a LEZ +account, permanently and for anyone to read. Because virtually all external +collateral enters LEZ through this one primitive, such a bridge becomes the +canonical deanonymisation oracle for the entire chain: an observer needs only to +scrape one Ethereum contract's logs to build an identity map covering most of +LEZ's collateral base. Every downstream privacy feature — private accounts, +the privacy-preserving DEX ([RFP-004](./RFP-004-privacy-preserving-dex.md)), +shielded lending positions — is undermined at the point of entry, no matter how +well those components protect data internally. Privacy that leaks at the on-ramp +is not privacy. + +The redemption leg is symmetric and, if anything, worse: a burn event naming +`ethereumRecipient` in the clear publishes the exit address alongside the LEZ +account that funded it, closing the loop and linking a user's entire LEZ +activity to their Ethereum identity on both ends. + +This RFP therefore treats unlinkability as a hard requirement of the same +standing as solvency. The construction is a commitment/nullifier shielded pool +on each leg, specified in full in Design Rationale below. + +### Stablecoins are the concrete prize + +USDT and USDC together account for over 80% of a stablecoin market that stood +above $300B in mid-2026, and are the settlement asset most DeFi money markets +and DEXes actually run on. Without a wrapped ERC-20 primitive, LEZ has no path +to bring USDC, USDT, DAI, or WETH liquidity onto the chain, which blocks the +lending protocol and the reflexive stablecoin from having any credible +collateral base at launch. Bridges are also the most attacked category of infrastructure in DeFi: Chainalysis has tracked more than $2.8B stolen from cross-chain bridges since 2022, the highest-value class of exploit in the industry. This RFP's security -posture — cryptographic verification via RISC0 zero-knowledge proofs, eliminating -the trust-in-signers vector entirely, combined with per-token and global -deposit/redemption caps and an admin-governed freeze-authority circuit -breaker — is designed directly against that track record. The trustless -cryptographic core ensures that no signer compromise, key theft, or participant -collusion can lead to spurious minting or release, and is explained in full in -Design Rationale and the Bridge Security requirements below. +posture — cryptographic verification via RISC0 zero-knowledge proofs, +eliminating the trust-in-signers vector entirely, combined with per-token and +global deposit/redemption caps and an admin-governed freeze-authority circuit +breaker — is designed directly against that track record. No signer compromise, +key theft, or participant collusion can lead to spurious minting or release. ## 🏗 Design Rationale -### Trustless lock-and-mint via zero-knowledge proofs - -The bridge has two independently deployed halves unified by a cryptographic -proof-verification primitive: - -1. **Ethereum vault contract.** A Solidity contract that accepts deposits of any - ERC-20 token in the supported-token registry (plus native ETH, which the - vault wraps to WETH internally so ETH does not need a separate bridging - path). Each deposit locks the token and emits a - `Deposit(token, depositor, amount, lezRecipient, nonce)` event. -2. **RISC0 proof generator (inbound).** An off-chain service (leveraging mature - RISC0 implementations such as Zisk) that observes Ethereum deposits reaching - finality, generates a zero-knowledge proof verifying (1) the Ethereum - consensus state at a specific block height, and (2) the deposit event state - in that block. The proof is deterministically derived from the deposit tuple - `(token, depositor, amount, lezRecipient, nonce)` and Ethereum chain state. -3. **LEZ bridge program (inbound).** A public-mode LEZ program verifies the RISC0 - proof in-program (validating Ethereum consensus and the inclusion of the - deposit event) and mints the corresponding wrapped token to `lezRecipient`, - crediting a private account directly where the recipient requests it (see - "+ Privacy" below). The deposit `nonce` is recorded on first use and any - repeat submission of the same nonce is rejected, preventing double-mint. - -No signer set, threshold signature, or attestor federation is required. The -proof's correctness is cryptographically ensured by the RISC0 circuit; no trust -in external parties is introduced. - -### Redemption: burn-and-release - -Redemption is the mirror flow. A holder burns wrapped tokens on LEZ via the -bridge program, which validates the burn and emits a structured redemption -event (per [LP-0012](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md)) -carrying `(token, amount, ethereumRecipient, redemptionNonce)`. Once the burn -transaction reaches LEZ finality, an off-chain service generates a RISC0 -zero-knowledge proof verifying (1) the LEZ consensus state at a specific epoch, -and (2) the burn event in that state. The Ethereum vault receives the proof and -verifies it natively via a precompile (Groth16 verifier on-chain or equivalent) -— a single verification step, orders of magnitude cheaper than the in-program -RISC-V path and matching the cost asymmetry documented in RFP-020 between -LEZ-side and EVM-side cryptographic verification. Upon successful proof -verification, the vault releases the original ERC-20 to `ethereumRecipient`, -tracking `redemptionNonce` to reject replays on the Ethereum side. +### The unlinkability requirement, stated precisely + +Two properties must hold against an adversary who observes **all** public state +on both chains, indefinitely, and who may themselves deposit and redeem: + +- **P1 (inbound).** Given an Ethereum lock event and the set of all LEZ mint + transactions, the adversary cannot determine which mint consumed that lock + with probability better than uniform over the inbound anonymity set. +- **P2 (outbound).** Given a LEZ burn event and the set of all Ethereum unlock + transactions, the adversary cannot determine which unlock was funded by that + burn with probability better than uniform over the outbound anonymity set. + +Both properties are stated relative to an *anonymity set*, and both degrade to +nothing when that set is small. Sizing, measuring and surfacing the anonymity +set is therefore a first-class requirement, not an implementation detail — see +Usability #7 and the Privacy & Unlinkability requirements. + +Two facts are fixed by the environment and cannot be designed away. Proposals +must not claim otherwise: + +1. **The Ethereum lock amount is public.** It is an ERC-20 `Transfer` into the + vault. So is the depositor's address, since they send the transaction. +2. **The Ethereum unlock amount and recipient are public.** The vault must move + real tokens to a real address. + +Unlinkability is achieved by making these public facts *uninformative about +which counterparty they pair with*, not by hiding them. + +### Fixed denominations + +Amounts are the strongest linkage vector: a lock of 1,337.42 USDC followed by a +mint of 1,337.42 wUSDC is linked by elimination regardless of what cryptography +sits between them. Since the Ethereum-side amount cannot be hidden, its +*fingerprint* must be destroyed instead. + +Every supported token therefore carries an admin-registered **denomination +ladder** (e.g. 1 / 10 / 100 / 1,000 / 10,000 USDC). Locks and unlocks are +permitted only at exactly these values; a user bridging 4,300 USDC does so as +4×1,000 + 3×100 notes. Thousands of users share each rung, so the public amount +identifies only the rung, not the user. Supply accounting remains scalar, which +keeps the LEZ mint authority within what [LP-0013](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md) +provides, and keeps the caps in Functionality #11 straightforwardly enforceable. + +The cost is real and must be handled in the UX: users split large transfers +across several notes, and remainders below the smallest rung cannot be bridged. +Proposals must specify the default ladder per token and justify the rung +spacing against expected transfer sizes. + +Shielded value commitments — hiding amounts entirely via homomorphic supply +accounting and range proofs — are the stronger construction and are specified as +Soft Requirement #1. The note format, circuit interfaces, and tree layout +delivered under this RFP must be chosen so that migration to shielded values +does not require redeploying the vault or re-anchoring the pool. + +### Inbound: lock → anchor → prove → mint into private state + +1. **Ethereum vault contract.** A Solidity contract holding an incremental + Merkle tree of deposit commitments. To deposit, a user picks a denomination + `d` for a registered token, samples secrets locally, and computes + `C = H(nullifierSecret, spendSecret, token, d)`. The vault pulls `d` units of + the token and inserts `C` as a leaf. The emitted event is + `Deposit(token, d, commitment, leafIndex, noteCiphertext)`. + + **There is no `lezRecipient` field and no `depositor` field.** This is the + central change from a conventional bridge. `noteCiphertext` is the note + encrypted to the recipient's LEZ viewing key, allowing a third-party + depositor to fund someone else's LEZ account without an out-of-band secret + handoff; the recipient discovers it by trial decryption. + +2. **Trustless root anchoring on LEZ.** A permissionless daemon submits a RISC0 + proof of (a) Ethereum consensus at a finalised block height and (b) the value + of the vault's commitment-tree root in that state. The LEZ bridge program + verifies this proof **in-program** and records the root. The daemon handles + only public chain data, holds no user secrets, and cannot insert a false root + — the program rejects any root not backed by a valid consensus proof. This is + what makes client-side proving feasible without introducing a trusted party. + +3. **Client-side ownership proof.** The user's own device generates a proof that + it knows the secrets behind *some* leaf under an anchored root, and derives + `nullifier = H(nullifierSecret)`. Public inputs are + `(anchoredRoot, token, d, nullifier, relayer, relayerFee)`. The Merkle path, + the leaf index, and both secrets are private inputs and never leave the + device. Because the proof is only a membership-and-hash argument against an + already-anchored root — not a consensus verification — it is small enough to + generate on the desktop hardware Basecamp already targets. + +4. **Mint.** The LEZ bridge program verifies the proof, rejects the transaction + if `nullifier` is already in the spent set, records it, and mints `d` units + of the wrapped token — `relayerFee` to the relayer's public account and the + remainder **into private LEZ state**, where neither the balance nor the owner + is publicly visible. + +The mint transaction publishes a nullifier and a root. It reveals nothing about +which of the N unconsumed same-denomination deposits it consumed, satisfying P1 +with an anonymity set of N. + +### Outbound: burn → commit → anchor → prove → unlock + +The redemption leg is the inbound leg run backwards, and its critical property +is that **the burn does not name the Ethereum recipient**. Naming it there is +precisely the leak that P2 forbids, so the flow is split into two stages +separated by a user-chosen delay. + +1. **Burn on LEZ.** A holder spends a private wrapped-token note of value `d`, + samples a fresh `ethSecret` locally, and the bridge program inserts a + withdrawal commitment `W = H(ethSecret, token, d)` into an on-chain + burn-commitment tree, emitting a structured event (per + [LP-0012](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md)) + carrying `(token, d, W, leafIndex)` — and nothing else. The spent LEZ note's + own nullifier is recorded to prevent double-burn. + +2. **Trustless root anchoring on Ethereum.** A permissionless daemon submits a + RISC0 proof of LEZ consensus at a finalised epoch and the burn-tree root in + that state. The vault verifies it via a **native precompile** (Groth16 + verifier or equivalent) — a single cheap verification step, matching the + LEZ-side/EVM-side cost asymmetry documented in RFP-020 — and records the + root. + +3. **Client-side unlock proof.** At a time of the user's choosing, their device + proves knowledge of `ethSecret` for some leaf under an anchored burn root, + publishing `nullifier' = H(ethSecret)` and public inputs + `(anchoredBurnRoot, token, d, ethereumRecipient, relayer, relayerFee)`. + +4. **Release.** The vault verifies the proof, rejects a replayed `nullifier'`, + and releases `d - relayerFee` of the original ERC-20 (or unwrapped ETH, for + WETH redemptions) to `ethereumRecipient`, and `relayerFee` to the relayer. + +`ethereumRecipient` is bound inside the proof, so a relayer can neither redirect +the funds nor inflate their fee. The unlock reveals a recipient and an amount, +but not which burn funded it, satisfying P2. + +### Client-side proving, and why no daemon holds a witness + +All proving that touches user-linked data happens on the user's device. The +daemons exist only to anchor roots, and a root is public chain state — a daemon +that observed every deposit and every anchor operation still cannot say which +mint consumed which lock, because it never sees a witness. + +Critically, the daemons are also **trustless, not merely honest-but-curious**: +each anchoring submission carries a consensus proof that the receiving chain +verifies before accepting the root. A malicious or compromised daemon can +withhold service, but cannot forge a root, cannot mint, and cannot deanonymise. +Anchoring is permissionless precisely so that withholding is not a viable +attack — any party can run a daemon, and proposals must document how a user can +run their own or trigger an anchor themselves if none is available. + +Proposals must state explicitly, in the privacy document required by +Supportability #9, that no component other than the user's own client ever +receives a Merkle path, a leaf index, or a note secret. + +### Timing decorrelation + +A perfect commitment scheme is defeated by a user who locks on Ethereum and +mints on LEZ ninety seconds later when no one else is bridging. Timing is a +linkage vector in its own right and the protocol must not force users into +correlated behaviour. + +Accordingly: a proof may be submitted at **any** time after the relevant root is +anchored, with no expiry; the client must default to a randomised delay rather +than immediate submission; and the client must show the user the current +anonymity set for their `(token, denomination)` pair and warn before submitting +into a set below a configurable threshold. Users must be able to override, but +must be told what they are giving up. + +### Relayers and fee payment + +If a user pays their own LEZ gas to mint, the funding source of that account +re-links them to the deposit, and the whole construction collapses. Mint and +unlock transactions are therefore submitted by **permissionless relayers**, paid +out of the bridged amount inside the circuit. + +Because `relayer` and `relayerFee` are public inputs bound into the proof, a +relayer cannot alter the recipient, redirect funds, or claim more than the +agreed fee; the worst they can do is decline to relay. Fee amounts must be drawn +from a small fixed schedule (or a fixed fraction of the denomination) rather +than being freely user-chosen — an arbitrary fee value is itself a fingerprint +that re-identifies the transaction. + +### Note custody and recovery + +In a commitment scheme, losing a note secret means the locked ERC-20 is +permanently unrecoverable — there is no administrative recovery path, by +construction. This is the single largest UX risk in the design and must be +addressed directly, not disclaimed. + +Note secrets must therefore be derived deterministically from a single +recoverable seed (e.g. a signature over a fixed domain-separated message from +the user's existing wallet), so that a user restoring that wallet can rediscover +all their notes by scanning the commitment trees and trial-decrypting note +ciphertexts. Ad-hoc random secrets requiring manual backup are not acceptable. ### Token registry and decimal normalisation Each supported ERC-20 is registered individually by the admin authority: its -Ethereum contract address, its LEZ wrapped-token mint, its decimals, and its -per-token deposit/redemption cap (see "Bridge Security" below). ERC-20 tokens +Ethereum contract address, its LEZ wrapped-token mint, its decimals, its +denomination ladder, and its per-token deposit/redemption caps. ERC-20 tokens do not share a common decimals convention (6 for USDC, 8 for WBTC, 18 for WETH -and DAI); the wrapped LEZ mint for each token must document its own decimals -and the exact conversion applied on mint and burn, and the registration -instruction must reject a token whose decimals cannot be represented exactly in -the chosen LEZ mint precision. +and DAI); the wrapped LEZ mint for each token must document its own decimals and +the exact conversion applied on mint and burn, and the registration instruction +must reject a token whose decimals or denomination ladder cannot be represented +exactly in the chosen LEZ mint precision. + +Fee-on-transfer and rebasing ERC-20s break the invariant that a locked +denomination equals a mintable denomination. The registry must reject them, and +the vault must verify the actual balance delta on deposit rather than trusting +the requested amount. ### Finality windows and reorg protection -An attestor must not sign a deposit attestation until the deposit transaction -has reached a configured Ethereum finality depth (a block-count or, once -generally available, a beacon-chain finalised-checkpoint condition). Signing -before finality risks attesting to a deposit that a reorg later removes, which -would mint wrapped tokens against a deposit that no longer exists on Ethereum. -The chosen depth is a direct trade-off between user-facing deposit latency and -reorg risk, and proposals must document the depth chosen and the residual risk -it leaves. The reverse direction (LEZ burn to Ethereum release) is symmetric: -attestors wait for LEZ finality on the burn transaction before co-signing a -release. +A root must not be anchored until the source-chain state it commits to has +reached a configured finality depth (a block-count or, once generally available, +a beacon-chain finalised-checkpoint condition). Anchoring a pre-finality root +risks admitting deposits that a reorg later removes, which would mint wrapped +tokens against locks that no longer exist. The chosen depth is a direct +trade-off between user-facing latency and reorg risk, and proposals must +document the depth chosen and the residual risk it leaves. The reverse direction +is symmetric: the vault anchors a LEZ burn root only after LEZ finality. + +Because anchoring is decoupled from user proofs, a reorg affects only the +anchoring step. Anchored roots are append-only and never rolled back, so no user +proof is ever invalidated by later chain activity. ### Trust model: cryptographic, trustless -This bridge is **trustless**. It requires no trust in external signers, validators, -or attestor federations. A user who bridges an ERC-20 asset relies only on the -correctness of the RISC0 circuit (verifying Ethereum consensus and state inclusion), -the security of the Ethereum network itself, and the security of the LEZ network. -Both inbound and outbound flows are verified by immutable cryptographic proofs, -not by signatures from a bounded set of participants. +This bridge is **trustless**. It requires no trust in external signers, +validators, attestor federations, or relayers. A user who bridges an ERC-20 +asset relies only on the correctness of the RISC0 circuits, the security of the +Ethereum network, and the security of the LEZ network. Both legs are verified by +cryptographic proofs, not by signatures from a bounded set of participants. + +Relayers are trusted for **liveness only** — they can decline to submit, but +cannot steal, redirect, censor selectively (they cannot tell users apart), or +deanonymise. Anchoring daemons are likewise liveness-only. Proposals must state this trustlessness explicitly in user-facing documentation -(mini-app, README, SDK docs). Per-token and global deposit/redemption caps, and -the freeze-authority circuit breaker (see Bridge Security), remain in place as -operational safety mechanisms independent of the cryptographic trust model. They -bound the operational blast radius and provide an administrative pause capability, -but are orthogonal to the bridge's trustlessness. +(mini-app, README, SDK docs), alongside an honest statement of the +unlinkability guarantee and its dependence on anonymity-set size. Per-token and +global caps and the freeze-authority circuit breaker remain in place as +operational safety mechanisms independent of the cryptographic trust model. + +Note that the freeze authority operates at token and protocol granularity only. +It **cannot** freeze an individual user's funds, because the protocol does not +know which funds belong to whom. This is a designed consequence of +unlinkability, not a gap, and must be documented as such. ### Fee structure -This RFP does not mandate a specific fee rate. Proposals must specify who pays -(depositor, redeemer, or both), when fees are collected (deposit, redemption, -or both), the exact rate, and where fees are routed. A governance-activatable -fee switch with an initial zero rate, gated by the admin authority per -RFP-001, is the recommended baseline, consistent with the pattern used -elsewhere in the Logos RFP set (see -[RFP-017](./RFP-017-token-vesting.md), "Fee structure"). +This RFP does not mandate a specific protocol fee rate (relayer fees are +separate and market-set within the fixed schedule above). Proposals must specify +who pays, when fees are collected, the exact rate, and where fees are routed. +A governance-activatable fee switch with an initial zero rate, gated by the +admin authority per RFP-001, is the recommended baseline, consistent with the +pattern used elsewhere in the Logos RFP set (see +[RFP-017](./RFP-017-token-vesting.md), "Fee structure"). Any protocol fee must +be a fixed function of the denomination, for the fingerprinting reason above. ## ✅ Scope of Work @@ -207,121 +406,164 @@ Use FURPS framework. Each numbered item should be a testable statement. #### Functionality -1. Implement an Ethereum vault contract (Solidity) that accepts deposits of any - ERC-20 token in the supported-token registry, plus native ETH (auto-wrapped - to WETH by the vault). Each deposit locks the token and emits a - `Deposit(token, depositor, amount, lezRecipient, nonce)` event with a - monotonically increasing `nonce`. -2. Implement an inbound RISC0 proof generator that observes finalised Ethereum - deposits, constructs a proof of the deposit (verifying Ethereum consensus at - a configured finality depth and the deposit event's inclusion in that state), - and outputs a proof artifact ready for on-chain verification. The proof must - encode `(token, depositor, amount, lezRecipient, nonce)` and be - deterministically reproducible from chain state. -3. Implement a public-mode LEZ bridge program that accepts an inbound RISC0 - proof, verifies it in-program (validating Ethereum consensus and state - inclusion), and mints the corresponding wrapped token to `lezRecipient` — to - a public or a private LEZ account, at the recipient's choice. Each deposit - `nonce` may be consumed at most once; a repeat submission of an - already-processed nonce must be rejected without minting. -4. Implement a burn instruction on the LEZ bridge program: a holder burns a - specified amount of a wrapped token, and the program emits a structured - redemption event (per LP-0012) carrying `(token, amount, ethereumRecipient, - redemptionNonce)`. -5. Implement an outbound RISC0 proof generator that observes finalised LEZ burn - events, constructs a proof of the burn (verifying LEZ consensus at a - configured finality depth and the burn event's inclusion in that state), and - outputs a proof artifact ready for on-chain Ethereum verification. The proof - must encode `(token, amount, ethereumRecipient, redemptionNonce)` and be - deterministically reproducible from chain state. -6. The Ethereum vault contract accepts an outbound RISC0 proof and verifies it - natively via a precompile (Groth16 verifier or equivalent), releasing the - original ERC-20 (or unwrapped ETH, for WETH redemptions) to - `ethereumRecipient`. Each `redemptionNonce` may be consumed at most once. -7. An admin authority (per RFP-001, integrated via the SPEL framework where - applicable to the LEZ side) can: register a new supported ERC-20 (Ethereum - address, LEZ wrapped mint, decimals, per-token deposit/redemption caps), and - deregister a token. Registration changes must be mirrored consistently on - both the Ethereum vault and the LEZ bridge program (document how the two - sides stay in sync and what happens if they temporarily diverge). -8. A freeze authority (per RFP-002) can pause minting and/or redemption, either - globally or for a single registered token, on both the Ethereum vault and - the LEZ bridge program independently. -9. Global and per-token deposit and redemption caps (configurable by the admin - authority) bound the maximum value that can be minted or released within a - rolling window, as a rate-limiting circuit breaker independent of the - freeze authority. +1. Implement an Ethereum vault contract (Solidity) maintaining an incremental + Merkle tree of deposit commitments. It accepts deposits of any ERC-20 in the + supported-token registry, plus native ETH (auto-wrapped to WETH), **only at + values on that token's registered denomination ladder**. It emits + `Deposit(token, denomination, commitment, leafIndex, noteCiphertext)` and + **must not** emit, store, or otherwise publish a LEZ recipient. The vault + verifies the actual balance delta on deposit and rejects any token whose + transfer does not deliver the exact denomination. +2. Implement a permissionless inbound anchoring path: a RISC0 proof of Ethereum + consensus at a configured finality depth plus the vault's commitment-tree + root in that state, verified **in-program** by the LEZ bridge program before + the root is recorded. Anchored roots are append-only. Submitting an + unbacked, malformed, or pre-finality root must be rejected without recording. +3. Implement a public-mode LEZ bridge program mint instruction accepting a + client-generated ownership proof with public inputs + `(anchoredRoot, token, denomination, nullifier, relayer, relayerFee)`. On + successful verification it mints `relayerFee` to the relayer's public account + and the remainder **into private LEZ state**. The Merkle path, leaf index, + and note secrets must be private inputs to the circuit. +4. Each inbound `nullifier` may be consumed at most once; resubmission of a + spent nullifier must be rejected deterministically without minting, and must + not reveal which leaf the nullifier corresponds to. +5. Implement a burn instruction on the LEZ bridge program: a holder spends a + private wrapped-token note of a registered denomination, and the program + inserts a withdrawal commitment into an on-chain burn-commitment tree and + emits a structured event (per LP-0012) carrying + `(token, denomination, withdrawalCommitment, leafIndex)`. The instruction and + its event **must not** accept, store, or publish an Ethereum recipient + address. +6. Implement a permissionless outbound anchoring path: a RISC0 proof of LEZ + consensus at a configured finality depth plus the burn-tree root in that + state, verified by the Ethereum vault via a native precompile (Groth16 + verifier or equivalent) before the root is recorded. Anchored roots are + append-only. +7. The Ethereum vault accepts a client-generated unlock proof with public inputs + `(anchoredBurnRoot, token, denomination, ethereumRecipient, relayer, relayerFee)`, + verifies it via the precompile, and releases `denomination - relayerFee` of + the original ERC-20 (or unwrapped ETH, for WETH redemptions) to + `ethereumRecipient` and `relayerFee` to `relayer`. Each outbound nullifier + may be consumed at most once. +8. Note secrets are derived deterministically from a single recoverable seed. + Implement note discovery: given the seed, a client can reconstruct its full + note set by scanning both commitment trees and trial-decrypting note + ciphertexts, recovering all unspent notes without any server-side index. +9. `relayerFee` must be constrained on-chain to a value on a registered fee + schedule (or a fixed fraction of the denomination); a proof carrying an + arbitrary fee value must be rejected. +10. An admin authority (per RFP-001, integrated via the SPEL framework where + applicable to the LEZ side) can register a new supported ERC-20 (Ethereum + address, LEZ wrapped mint, decimals, denomination ladder, fee schedule, + per-token caps) and deregister a token. Registration changes must be + mirrored consistently on both sides (document how the two stay in sync and + what happens if they temporarily diverge). The registry must reject + fee-on-transfer and rebasing tokens. +11. Global and per-token deposit and redemption caps (configurable by the admin + authority) bound the maximum value that can be minted or released within a + rolling window, as a rate-limiting circuit breaker independent of the freeze + authority. Cap enforcement must not require identifying individual users. +12. A freeze authority (per RFP-002) can pause minting and/or redemption, either + globally or for a single registered token, on both the Ethereum vault and + the LEZ bridge program independently. #### Usability -1. Provide an SDK that can be used to build Logos modules for: submitting - deposits to the Ethereum vault, querying deposit/proof/mint status, querying - inbound proof generation progress, initiating a redemption (burn), querying - redemption/proof/release status, and reading the supported-token registry. +1. Provide an SDK to build Logos modules for: constructing and submitting + deposits, deriving and managing notes, discovering owned notes by scanning, + generating inbound and outbound proofs locally, submitting via a relayer, + querying anchoring progress and anonymity-set size, initiating a redemption + burn, and reading the supported-token registry and denomination ladders. 2. Provide a Logos mini-app GUI with local build instructions, downloadable - assets, and loadable in Logos app (Basecamp) via git repo. The mini-app must - cover: a deposit flow (connect an Ethereum wallet, approve and deposit, - track proof generation progress, confirm LEZ mint, choose public or private - destination account), a redemption flow (burn wrapped tokens, track proof - generation, confirm Ethereum release), and a registry view (supported tokens, - per-token caps and current utilisation). -3. Provide a CLI that covers core functionality: deposit, query status, redeem, - and query the token registry. The CLI may have fewer features than the - mini-app but must support all essential operations. -4. Provide the inbound and outbound RISC0 proof generators as **Logos modules - accompanied by Logos Core headless CLI/daemons**, so operators can run them - as standalone long-running processes. Each daemon must support: configurable - Ethereum and/or LEZ RPC endpoints, configurable finality depth for the source - chain, structured logging of observed events and generated proofs, and a - clean shutdown path. The proof generators must integrate with or wrap mature - RISC0 implementations (e.g. Zisk) without reimplementing zero-knowledge - primitives. Document the operator journey end-to-end: install, configure, run, - monitor. -5. Provide an IDL for the LEZ bridge program using the + assets, and loadable in Logos app (Basecamp) via git repo. It must cover: a + deposit flow (connect Ethereum wallet, select denomination, approve and + deposit, note derivation and backup confirmation), a mint flow (local proof + generation with progress, delay selection, relayer submission), a redemption + flow (burn, then a separately-timed unlock with recipient entry), a note + inventory and recovery flow, and a registry view (supported tokens, ladders, + caps and current utilisation). +3. Provide a CLI covering core functionality: deposit, discover notes, generate + proof, mint, burn, unlock, and query the registry. The CLI may have fewer + features than the mini-app but must support all essential operations, + including proof generation and note recovery entirely offline. +4. Provide the inbound and outbound anchoring daemons as **Logos modules + accompanied by Logos Core headless CLI/daemons**, runnable as standalone + long-running processes. Each must support: configurable Ethereum and/or LEZ + RPC endpoints, configurable finality depth, configurable anchoring cadence, + structured logging, and a clean shutdown path. They must integrate with or + wrap mature RISC0 implementations (e.g. Zisk) without reimplementing + zero-knowledge primitives. Document the operator journey end-to-end: install, + configure, run, monitor. +5. Provide a reference relayer implementation, runnable permissionlessly, with + documented fee policy and submission logic. Document how a user submits + without a relayer if they accept the privacy cost of paying their own gas. +6. Provide an IDL for the LEZ bridge program using the [SPEL framework](https://github.com/logos-co/spel). -6. Return clear, actionable error messages for all failure modes: unsupported - token, cap exceeded, invalid proof, proof verification failure, insufficient - finality, nonce already processed, and program or per-token frozen. +7. Both the mini-app and CLI must display, before any mint or unlock + submission, the current anonymity set size for the relevant + `(token, denomination)` pair, and must warn when it falls below a + configurable threshold. The default submission delay must be randomised + rather than immediate, with the user able to inspect and override it. +8. Return clear, actionable error messages for all failure modes: unsupported + token, invalid denomination, cap exceeded, invalid proof, proof verification + failure, root not yet anchored, insufficient finality, nullifier already + spent, invalid relayer fee, and program or per-token frozen. Error messages + must not leak which leaf or note a failed proof referred to. #### Reliability 1. Minting is atomic: a failed or rejected mint attempt does not consume the - deposit nonce and leaves the deposit mintable on retry. -2. Burn-and-redeem is atomic: a failed redemption attempt does not burn tokens - without a corresponding, retryable redemption record. -3. A deposit or redemption nonce can be consumed at most once; replaying an - already-verified proof is rejected deterministically and does not - double-mint or double-release. -4. Proof generation is deterministic: given the same chain state and input - parameters, proof generators must produce the same proof (or provably - equivalent proofs if the RISC0 implementation supports non-determinism). - This ensures that multiple independent proof generators can verify each - other's work and that replaying a proof from cache is safe. -5. A temporary RPC or connectivity failure on either chain leaves the proof - generator daemon in a recoverable state, able to resume observing and - generating proofs once connectivity is restored, without needing to replay - already-proven items. + nullifier and leaves the note spendable on retry. +2. Burn-and-unlock is atomic at each stage: a failed burn does not destroy a + note without inserting a corresponding withdrawal commitment, and a failed + unlock does not consume the outbound nullifier. +3. A nullifier can be consumed at most once on each leg; replaying an + already-verified proof is rejected deterministically and does not double-mint + or double-release. +4. Anchored roots are append-only and never invalidated. A proof valid against a + historical anchored root must remain valid indefinitely, so a user who + delays submission for privacy reasons is never forced to regenerate. +5. Note recovery is complete: a client restored from seed alone must rediscover + every unspent note it owns on both legs, verified by a test that wipes all + local state and recovers from seed. +6. A temporary RPC or connectivity failure leaves an anchoring daemon in a + recoverable state, able to resume once connectivity is restored without + re-anchoring already-anchored roots. +7. Client-side proof generation is resumable or cheaply restartable: an + interrupted proof does not consume, corrupt, or expose the note. #### Performance -1. Verifying an inbound RISC0 proof (Ethereum consensus + state inclusion, - in-program on LEZ) and minting must complete within a single LEZ public - transaction at the per-transaction compute budget in force at delivery time. - Document the compute-unit cost, including the cost breakdown for the RISC0 - proof verification and the LEZ mint instruction, extending the measurement - methodology from [RFP-020](./RFP-020-redstone-oracle-adaptor.md). -2. Document the Ethereum-side gas cost of verifying the outbound RISC0 proof - via a precompile (Groth16 verifier or equivalent) and releasing funds from - the vault. Benchmark against the gas costs for comparable proof-verification - precompiles on EVM networks where available (e.g. Ethereum's Groth16 - verifier, Arbitrum's curve pairing precompile). -3. Document end-to-end deposit latency (deposit submission to LEZ mint - confirmation) and end-to-end redemption latency (burn to Ethereum release - confirmation), each broken down by: chain finality wait, proof generation - time, and on-chain verification time. -4. Document the RISC0 proof generation time for both inbound (Ethereum → LEZ) - and outbound (LEZ → Ethereum) proofs, and characterize the compute resources - (CPU, RAM, time) required to run a proof generator daemon. +1. Verifying an inbound ownership proof and minting must complete within a + single LEZ public transaction at the per-transaction compute budget in force + at delivery time. Document the compute-unit cost, broken down between proof + verification, nullifier-set insertion, and the mint instruction, extending + the measurement methodology from + [RFP-020](./RFP-020-redstone-oracle-adaptor.md). +2. Document the compute-unit cost of in-program verification of the inbound + **anchoring** proof (Ethereum consensus + state), separately from #1, and the + amortised per-deposit cost at the recommended anchoring cadence. +3. Document the Ethereum-side gas cost of (a) a deposit, (b) verifying an + outbound anchoring proof via precompile, and (c) verifying an unlock proof + and releasing funds. Benchmark against comparable proof-verification + precompiles on EVM networks where available. +4. **Client-side proof generation must be practical on the desktop hardware + Basecamp runs on.** Measure and document wall-clock generation time and peak + memory for both the inbound ownership proof and the outbound unlock proof, on + at least: a mid-range laptop, and the lowest-specification machine the team + declares as supported. State that minimum specification explicitly, and + report results for the mini-app and the CLI separately if their proving paths + differ. Mobile and browser proving targets are out of scope (see Out of + Scope). +5. Document end-to-end deposit latency (lock to LEZ mint) and redemption latency + (burn to Ethereum release), each broken down by: source-chain finality wait, + anchoring wait, client proof generation, privacy delay, and on-chain + verification. +6. Document anchoring proof generation time for both directions and the compute + resources (CPU, RAM, time) required to run an anchoring daemon. +7. Document the growth rate and on-chain storage cost of both commitment trees + and both nullifier sets, and the projected cost at 1M and 10M notes. #### Supportability @@ -331,97 +573,150 @@ Use FURPS framework. Each numbered item should be a testable statement. trip against a LEZ sequencer (standalone mode) and an Ethereum test network or local fork, and are included in CI. CI must be green on the default branch. -3. Every hard requirement in Functionality, Usability, Reliability, and - Performance has at least one corresponding test. +3. Every hard requirement in Functionality, Usability, Reliability, Performance, + and Privacy & Unlinkability has at least one corresponding test. 4. A README documents end-to-end usage: contract and program addresses, deployment steps for both chains, and step-by-step instructions for - depositing and redeeming via CLI and mini-app. + depositing, minting, burning and unlocking via CLI and mini-app. 5. Submit a [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for the SDK, covering the developer integration journey for both deposit - and redemption flows. + for the SDK, covering the developer integration journey for both legs + including note management and local proof generation. 6. Submit a [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for the CLI and the proof generators (inbound and outbound), covering the + for the CLI, the anchoring daemons, and the reference relayer, covering the core user and operator journeys respectively. -7. Provide Figma designs or equivalent for all mini-app GUI artefacts. +7. Provide Figma designs or equivalent for all mini-app GUI artefacts, including + the anonymity-set disclosure and the note-backup confirmation flows. 8. The Ethereum vault contract undergoes an independent third-party - smart-contract security audit before mainnet deployment; the audit report - (or a summary, if the full report is not publishable) must be linked from - the README. This requirement exists because cross-chain bridges are the - single most-attacked category of DeFi infrastructure (Chainalysis has - tracked more than $2.8B stolen from bridges since 2022); it is not - optional. -9. Provide a privacy and anonymisation properties document covering: what is - visible on-chain for a deposit and a redemption on both Ethereum and LEZ; - what remains private when minting to, or redeeming from, a LEZ private - account; what the proof generators can observe about a depositor or - redeemer from RPC queries to either chain; and what information is - irretrievably obfuscated by the bridge's design. + smart-contract security audit before mainnet deployment; the audit report (or + a summary, if the full report is not publishable) must be linked from the + README. This requirement exists because cross-chain bridges are the single + most-attacked category of DeFi infrastructure (Chainalysis has tracked more + than $2.8B stolen from bridges since 2022); it is not optional. +9. Provide a **privacy and unlinkability properties document** covering: a + formal statement of P1 and P2 and the anonymity set each is measured against; + exactly what is visible on-chain for every operation on both chains; what an + adversary observing all public state can and cannot infer; confirmation that + no component other than the user's client ever receives a Merkle path, leaf + index, or note secret; what a relayer, an anchoring daemon operator, and an + RPC provider can each observe; residual leakage from timing, denomination + choice, gas payment, IP-level metadata, and note-splitting patterns; and the + conditions under which unlinkability degrades or fails. +10. Document the anonymity-set growth model: expected set size over time at + projected volumes, the minimum set size below which the guarantee is + considered not to hold, and guidance for users bridging before the pool has + matured. #### + Bridge Security -1. RISC0 proof verification must be deterministic and verifiable by any - participant independently. The LEZ bridge program and Ethereum vault contract - must both reject proofs that fail verification, and this must be tested with - invalid proofs (e.g. proofs with incorrect public inputs, proofs for incorrect - chain state, proofs with tampered headers). -2. Proof generators must independently derive the deposit or burn tuple and chain - state from RPC calls to the source chain; the daemon must not accept a proof - supplied to it by a third party without independently regenerating and - verifying it against the source chain. -3. Global and per-token deposit/redemption caps (Functionality #9) bound the - maximum value at risk within any rolling window; proposals must document the - recommended default caps and the reasoning behind them. These caps are - independent of proof verification and operate as an additional administrative - safety valve. -4. The freeze authority (Functionality #8) must be exercisable independently on - the Ethereum vault and the LEZ bridge program, so that either half can be - paused without requiring the other to be operational or reachable. -5. The bridge's user-facing documentation (mini-app, README, SDK docs) must - state the trustless cryptographic verification model explicitly (see Design - Rationale, "Trust model") and explain how RISC0 proofs ensure the integrity - of cross-chain transfers without requiring trust in external signers. +1. RISC0 proof verification must be deterministic and independently verifiable. + The LEZ program and Ethereum vault must both reject proofs that fail + verification, tested with invalid proofs (incorrect public inputs, proofs for + incorrect chain state, tampered headers, proofs against unanchored roots, + proofs reusing a spent nullifier). +2. Anchoring daemons must independently derive chain state from RPC calls to the + source chain; a daemon must not accept and forward a root or proof supplied + by a third party without independently regenerating and verifying it. +3. A malicious relayer must not be able to alter `ethereumRecipient`, inflate + `relayerFee`, or replay a user's proof to a different destination. Test each + case explicitly. +4. Global and per-token caps (Functionality #11) bound the maximum value at risk + in any rolling window; proposals must document recommended default caps and + the reasoning behind them. +5. The freeze authority (Functionality #12) must be exercisable independently on + each half, so either can be paused without the other being operational or + reachable. +6. Soundness of supply: the total wrapped supply on LEZ must never exceed the + vault's holdings. Provide a test that attempts to mint without a valid + deposit, mint twice from one deposit, and unlock without a valid burn. +7. User-facing documentation must state the trustless verification model and the + liveness-only role of relayers and anchoring daemons (see Design Rationale, + "Trust model"). + +#### + Privacy & Unlinkability + +1. **P1 must hold under test.** Provide an automated test that constructs a + population of deposits and mints and asserts that no public-state-derived + correlation identifies the true lock↔mint pairing better than chance across + the anonymity set. +2. **P2 must hold under test.** The equivalent test for burn↔unlock pairings. +3. No deposit event, burn event, transaction argument, log, or account-state + change on either chain may contain a LEZ recipient at deposit time or an + Ethereum recipient at burn time. Provide a test that asserts this over full + event and state diffs for a complete round trip. +4. Merkle paths, leaf indices, and note secrets must be private circuit inputs. + Provide a test asserting they are absent from all public inputs and all + submitted transaction data. +5. Failure and error paths must not leak note identity: a rejected proof, a + spent nullifier, and a cap rejection must be indistinguishable with respect + to which leaf was involved. +6. The client must not contact any network endpoint that reveals which note it + is proving over. Document all network calls made during proof generation and + justify each; a note-specific query to a third-party RPC is a defect. +7. Relayer selection and submission must not create a linkage channel: document + what a relayer learns, and ensure a user can switch relayers per operation. +8. The default configuration must be the private one. No user action should be + required to obtain unlinkability, and any override that weakens it must + require explicit confirmation. ### Soft Requirements -1. Batch proof verification: amortise verification cost across multiple deposits - or redemptions in a single LEZ transaction, analogous to the multi-feed - batching soft requirement in RFP-020. -2. Proof caching and relay: allow pre-generated and verified proofs to be cached - and resubmitted by users or relayers, reducing the need for everyone to - generate proofs independently (proof generators produce canonical proofs that - can be reused). -3. A configurable per-token redemption delay (in addition to the finality wait) - as an extra circuit-breaker window, allowing the freeze authority to react - to an anomalous large redemption before funds leave the vault. -4. Support for wrapping ERC-20 tokens from additional EVM chains (e.g. - Arbitrum, Base) behind the same LEZ bridge program, reusing the token - registry and cap mechanism and generating separate RISC0 proofs for each - source chain's consensus and state. -5. A path to improve proof generation over time: design the RISC0 proof - generator as a pluggable component so that optimizations to the RISC0 circuit - (e.g. via future RISC0 zkVM improvements, proof compression, or hardware - acceleration) can be integrated without restructuring the vault or bridge - program. +1. **Shielded value commitments.** Replace fixed denominations with hidden + amounts via Pedersen or equivalent value commitments, range proofs, and + join-split notes, with homomorphic supply accounting on the LEZ mint + authority. This removes the denomination ladder entirely and merges all + per-rung anonymity sets into one. The note format, circuit interfaces, and + tree layout delivered under the hard requirements must be designed so this + migration does not require redeploying the vault or re-anchoring the pool; + document the intended migration path even if it is not implemented. +2. Batch verification: amortise proof verification across multiple mints or + unlocks in a single transaction, analogous to the multi-feed batching soft + requirement in RFP-020. Batching also improves unlinkability by making + individual operations harder to isolate. +3. Optional viewing keys allowing a user to *voluntarily* disclose their own + bridge activity to a chosen third party, without weakening unlinkability for + anyone else and without any protocol-level disclosure capability. +4. A configurable per-token unlock delay (in addition to finality and the user's + own privacy delay) as an extra circuit-breaker window, allowing the freeze + authority to react to anomalous redemption volume before funds leave the + vault. +5. Support for wrapping ERC-20 tokens from additional EVM chains (e.g. Arbitrum, + Base) behind the same LEZ bridge program, reusing the registry, ladders, and + caps, with separate anchoring paths per source chain. Consider whether pools + should be shared across source chains to enlarge anonymity sets. +6. Hardware-accelerated or GPU-assisted client proving as an optional path for + users with capable hardware, without making it a requirement. +7. Design the RISC0 anchoring components as pluggable so that future zkVM + improvements, proof compression, or hardware acceleration can be integrated + without restructuring the vault, the bridge program, or the note format. ### Out of Scope The following are explicitly excluded from this RFP: - Wrapping non-fungible assets (ERC-721, ERC-1155). -- Bitcoin, Monero, and Zcash bridging: these have a dedicated trustless path - via atomic swaps, delivered in [RFP-003](./RFP-003-atomic-swaps.md). +- Bitcoin, Monero, and Zcash bridging: these have a dedicated trustless path via + atomic swaps, delivered in [RFP-003](./RFP-003-atomic-swaps.md). +- Mobile and in-browser proving. Basecamp is a desktop application and is the + delivery surface for the mini-app, so the prover targets desktop only. + Proposals must not constrain circuit design to fit mobile-class resource + budgets. +- Network-level anonymity. Unlinkability here is a property of on-chain state. + IP-level correlation between a user's Ethereum deposit and their relayer + submission is out of scope as an implementation concern, but must be disclosed + as residual leakage under Supportability #9. +- Protocol-level compliance, disclosure, or selective-deanonymisation + mechanisms. Voluntary user-held viewing keys are Soft Requirement #3; any + capability allowing a third party to deanonymise a user without their consent + is contrary to the design and out of scope. - Circuit optimization or custom RISC0 accelerators: proposals should leverage mature existing RISC0 implementations (e.g. Zisk) rather than implementing - novel circuits or optimization techniques. Future improvements to RISC0 - circuit performance are a separate effort from this bridge implementation. -- Alternative proof systems (e.g. SNARKs, STARKs, other zkVMs): this RFP - specifies RISC0 as the proof system. If future RISC0 versions or alternative - systems become preferable, that is a candidate for a future update or new - RFP. -- Price feeds for wrapped assets. Once a token is wrapped, pricing it (for - lending collateral, DEX pairs, or the reflexive stablecoin) is the + novel circuits or optimization techniques. +- Alternative proof systems (e.g. other zkVMs): this RFP specifies RISC0. If + future RISC0 versions or alternative systems become preferable, that is a + candidate for a future update or new RFP. +- Price feeds for wrapped assets. Once a token is wrapped, pricing it is the responsibility of the oracle stack ([RFP-019](./RFP-019-twap-oracle.md), [RFP-020](./RFP-020-redstone-oracle-adaptor.md)), not this bridge. @@ -433,28 +728,39 @@ The following are explicitly excluded from this RFP: #### Admin authority (RFP-001) The Functionality requirements specify that an admin authority registers and -deregisters supported tokens and configures deposit/redemption caps. These -admin-gated functions require the standardised admin authority library from -[RFP-001](./RFP-001-admin-authority-lib.md). +deregisters supported tokens and configures denomination ladders, fee schedules +and caps. These admin-gated functions require the standardised admin authority +library from [RFP-001](./RFP-001-admin-authority-lib.md). #### Freeze authority (RFP-002) The Bridge Security requirements specify a freeze authority able to pause minting and/or redemption, globally or per token, as a circuit breaker -independent of the deposit/redemption caps. This requires the standardised -freeze authority library from -[RFP-002](./RFP-002-freeze-authority-lib.md). +independent of the caps. This requires the standardised freeze authority library +from [RFP-002](./RFP-002-freeze-authority-lib.md). #### Token mint/burn authorities (LP-0013) -The LEZ bridge program mints wrapped tokens on verified deposits and burns them -on redemption. This requires the token mint/burn authority primitives in +The LEZ bridge program mints wrapped tokens into private state on verified +deposits and burns them on redemption. This requires the token mint/burn +authority primitives in [LP-0013](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md). +The fixed-denomination design keeps supply accounting scalar and therefore +within what LP-0013 provides; Soft Requirement #1 (shielded values) would +require homomorphic supply accounting beyond it, and proposals pursuing that +path must state what extension is needed. + +#### Private LEZ account state + +Inbound mints deliver into private LEZ state, and outbound burns spend from it. +Unlinkability depends on this: a mint into a public account re-links the +recipient immediately. Proposals must state which LEZ private-state primitives +they rely on and their maturity. #### RISC0 zkVM -The bridge verifies cryptographic proofs in-program (inbound on LEZ) and -natively on Ethereum (outbound). Proof generation and verification require +The bridge verifies consensus proofs in-program (inbound on LEZ) and natively on +Ethereum (outbound), and generates ownership proofs client-side. This requires RISC0, a production-ready zkVM. Proposals must leverage mature RISC0 implementations (e.g. [Zisk](https://github.com/risc0/zisk)) rather than building custom circuits. @@ -463,9 +769,8 @@ building custom circuits. #### Event emission (LP-0012) -Redemption events, and ideally deposit-mint events, are emitted as structured -on-chain events so off-chain proof generators and dashboards can react -without polling every account. +Burn and anchoring events are emitted as structured on-chain events so clients +and anchoring daemons can react without polling every account. [LP-0012](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) is **closed** (delivered). @@ -473,21 +778,30 @@ is **closed** (delivered). Team experienced with: -- Zero-knowledge proof systems and RISC0 zkVM (guest program development, - proof generation and verification, public/private input handling) -- Solidity smart-contract development, including experience preparing a - contract for third-party security audit, and EVM precompile integration +- Zero-knowledge proof systems and RISC0 zkVM (guest program development, proof + generation and verification, public/private input handling) +- **Shielded-pool constructions**: commitment/nullifier schemes, incremental + Merkle trees, note encryption and discovery, deterministic key derivation, and + the anonymity-set analysis that goes with them +- Solidity smart-contract development, including experience preparing a contract + for third-party security audit, and EVM precompile integration - Cryptographic primitives (Groth16 verification, Merkle proofs, consensus verification, state root inclusion proofs) -- LEZ program development and on-chain proof verification -- Smart-contract security auditing (proof validation, replay attacks, - reorg handling, cap/rate-limit bypass) +- LEZ program development, private-state programs, and on-chain proof + verification +- Client-side proving on desktop targets, including packaging a prover inside a + Basecamp mini-app and a headless CLI +- Smart-contract security auditing (proof validation, replay attacks, reorg + handling, cap/rate-limit bypass, privacy-leak analysis) - Cross-chain system design and integration testing (dual-chain atomic operations, finality assumptions, determinism and reproducibility) ## ⏱ Timeline Expectations -Estimated software delivery duration: **12–14 weeks**. This excludes the +Estimated software delivery duration: **16–20 weeks**. This is longer than a +transparent lock-and-mint bridge would require; the shielded-pool construction, +client-side proving targets, note discovery and recovery, the relayer layer, and +the unlinkability test suite are the additional scope. This excludes the third-party audit lead time required before mainnet deployment (Supportability #8), which is typically procured and scheduled separately. @@ -501,6 +815,8 @@ All code must be released under the **MIT+Apache2.0 dual License**. - [RFP-002 — Freeze Authority Library](./RFP-002-freeze-authority-lib.md) - [RFP-003 — Atomic Swaps](./RFP-003-atomic-swaps.md) (trustless path for BTC, XMR, ZEC; explicitly defers ETH to wrapping) +- [RFP-004 — Privacy-Preserving DEX](./RFP-004-privacy-preserving-dex.md) + (downstream consumer whose privacy guarantees depend on a private on-ramp) - [RFP-008 — Lending & Borrowing Protocol](./RFP-008-lending-borrowing-protocol.md) (primary consumer of wrapped collateral) - [RFP-013 — Reflexive Stablecoin Protocol](./RFP-013-reflexive-stablecoin-protocol.md) @@ -523,4 +839,4 @@ All code must be released under the **MIT+Apache2.0 dual License**. **[Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml)** We typically respond within **14 days**. For clarification questions, please use -**Discussions**. \ No newline at end of file +**Discussions**. From 440c1c37d35bf5ed356a063ce5a5ccabc591f5ee Mon Sep 17 00:00:00 2001 From: jzaki Date: Sat, 8 Aug 2026 07:01:19 +0100 Subject: [PATCH 04/69] Rephrase privacy preserving --- RFPs/RFP-021-wrapped-erc20.md | 56 ++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index daec0882..22c03d61 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -1,6 +1,6 @@ --- id: RFP-021 -title: Unlinkable Wrapped ERC-20 Bridge for LEZ +title: Privacy-Preserving Wrapped ERC-20 Bridge for LEZ tier: L status: open category: Developer Tooling & Infrastructure @@ -15,7 +15,7 @@ dependencies: -# RFP-021 — Unlinkable Wrapped ERC-20 Bridge for LEZ +# RFP-021 — Privacy-Preserving Wrapped ERC-20 Bridge for LEZ > **Note.** This specification describes an outcome that may benefit the Logos > ecosystem. It is a proposal rather than an instruction. Its requirements @@ -48,7 +48,7 @@ dependencies: ## 🧭 Overview -Build a trustless, **unlinkable** lock-and-mint bridge that lets ERC-20 tokens +Build a trustless, **privacy-preserving** lock-and-mint bridge that lets ERC-20 tokens (and native ETH, wrapped as WETH) held on Ethereum enter LEZ as canonical wrapped assets, and exit back to Ethereum on redemption — without any public observer being able to connect a specific Ethereum lock to the LEZ mint it @@ -97,8 +97,8 @@ cryptographic proofs natively. ### A transparent bridge would deanonymise the whole chain -Unlinkability is not a nice-to-have here; it is the difference between this -bridge strengthening LEZ's privacy guarantees and silently destroying them. +Privacy is not a nice-to-have here; it is the difference between this bridge +strengthening LEZ's privacy guarantees and silently destroying them. A conventional lock-and-mint bridge emits `Deposit(token, depositor, amount, lezRecipient, nonce)` on Ethereum. That @@ -118,7 +118,7 @@ The redemption leg is symmetric and, if anything, worse: a burn event naming account that funded it, closing the loop and linking a user's entire LEZ activity to their Ethereum identity on both ends. -This RFP therefore treats unlinkability as a hard requirement of the same +This RFP therefore treats privacy preservation as a hard requirement of the same standing as solvency. The construction is a commitment/nullifier shielded pool on each leg, specified in full in Design Rationale below. @@ -142,10 +142,11 @@ key theft, or participant collusion can lead to spurious minting or release. ## 🏗 Design Rationale -### The unlinkability requirement, stated precisely +### The privacy requirement, stated precisely -Two properties must hold against an adversary who observes **all** public state -on both chains, indefinitely, and who may themselves deposit and redeem: +Two privacy properties must hold against an adversary who observes **all** +public state on both chains, indefinitely, and who may themselves deposit and +redeem: - **P1 (inbound).** Given an Ethereum lock event and the set of all LEZ mint transactions, the adversary cannot determine which mint consumed that lock @@ -157,7 +158,7 @@ on both chains, indefinitely, and who may themselves deposit and redeem: Both properties are stated relative to an *anonymity set*, and both degrade to nothing when that set is small. Sizing, measuring and surfacing the anonymity set is therefore a first-class requirement, not an implementation detail — see -Usability #7 and the Privacy & Unlinkability requirements. +Usability #7 and the Privacy Preservation requirements. Two facts are fixed by the environment and cannot be designed away. Proposals must not claim otherwise: @@ -167,8 +168,8 @@ must not claim otherwise: 2. **The Ethereum unlock amount and recipient are public.** The vault must move real tokens to a real address. -Unlinkability is achieved by making these public facts *uninformative about -which counterparty they pair with*, not by hiding them. +Privacy is preserved by making these public facts *uninformative about which +counterparty they pair with*, not by hiding them. ### Fixed denominations @@ -378,14 +379,14 @@ deanonymise. Anchoring daemons are likewise liveness-only. Proposals must state this trustlessness explicitly in user-facing documentation (mini-app, README, SDK docs), alongside an honest statement of the -unlinkability guarantee and its dependence on anonymity-set size. Per-token and +privacy guarantees and their dependence on anonymity-set size. Per-token and global caps and the freeze-authority circuit breaker remain in place as operational safety mechanisms independent of the cryptographic trust model. Note that the freeze authority operates at token and protocol granularity only. It **cannot** freeze an individual user's funds, because the protocol does not -know which funds belong to whom. This is a designed consequence of -unlinkability, not a gap, and must be documented as such. +know which funds belong to whom. This is a designed consequence of the privacy +guarantees, not a gap, and must be documented as such. ### Fee structure @@ -574,7 +575,7 @@ Use FURPS framework. Each numbered item should be a testable statement. or local fork, and are included in CI. CI must be green on the default branch. 3. Every hard requirement in Functionality, Usability, Reliability, Performance, - and Privacy & Unlinkability has at least one corresponding test. + and Privacy Preservation has at least one corresponding test. 4. A README documents end-to-end usage: contract and program addresses, deployment steps for both chains, and step-by-step instructions for depositing, minting, burning and unlocking via CLI and mini-app. @@ -594,7 +595,7 @@ Use FURPS framework. Each numbered item should be a testable statement. README. This requirement exists because cross-chain bridges are the single most-attacked category of DeFi infrastructure (Chainalysis has tracked more than $2.8B stolen from bridges since 2022); it is not optional. -9. Provide a **privacy and unlinkability properties document** covering: a +9. Provide a **privacy properties document** covering: a formal statement of P1 and P2 and the anonymity set each is measured against; exactly what is visible on-chain for every operation on both chains; what an adversary observing all public state can and cannot infer; confirmation that @@ -602,7 +603,7 @@ Use FURPS framework. Each numbered item should be a testable statement. index, or note secret; what a relayer, an anchoring daemon operator, and an RPC provider can each observe; residual leakage from timing, denomination choice, gas payment, IP-level metadata, and note-splitting patterns; and the - conditions under which unlinkability degrades or fails. + conditions under which these privacy guarantees degrade or fail. 10. Document the anonymity-set growth model: expected set size over time at projected volumes, the minimum set size below which the guarantee is considered not to hold, and guidance for users bridging before the pool has @@ -634,7 +635,7 @@ Use FURPS framework. Each numbered item should be a testable statement. liveness-only role of relayers and anchoring daemons (see Design Rationale, "Trust model"). -#### + Privacy & Unlinkability +#### + Privacy Preservation 1. **P1 must hold under test.** Provide an automated test that constructs a population of deposits and mints and asserts that no public-state-derived @@ -657,8 +658,8 @@ Use FURPS framework. Each numbered item should be a testable statement. 7. Relayer selection and submission must not create a linkage channel: document what a relayer learns, and ensure a user can switch relayers per operation. 8. The default configuration must be the private one. No user action should be - required to obtain unlinkability, and any override that weakens it must - require explicit confirmation. + required to obtain these privacy guarantees, and any override that weakens + them must require explicit confirmation. ### Soft Requirements @@ -672,10 +673,10 @@ Use FURPS framework. Each numbered item should be a testable statement. document the intended migration path even if it is not implemented. 2. Batch verification: amortise proof verification across multiple mints or unlocks in a single transaction, analogous to the multi-feed batching soft - requirement in RFP-020. Batching also improves unlinkability by making - individual operations harder to isolate. + requirement in RFP-020. Batching also improves privacy by making individual + operations harder to isolate. 3. Optional viewing keys allowing a user to *voluntarily* disclose their own - bridge activity to a chosen third party, without weakening unlinkability for + bridge activity to a chosen third party, without weakening privacy for anyone else and without any protocol-level disclosure capability. 4. A configurable per-token unlock delay (in addition to finality and the user's own privacy delay) as an extra circuit-breaker window, allowing the freeze @@ -702,7 +703,8 @@ The following are explicitly excluded from this RFP: delivery surface for the mini-app, so the prover targets desktop only. Proposals must not constrain circuit design to fit mobile-class resource budgets. -- Network-level anonymity. Unlinkability here is a property of on-chain state. +- Network-level anonymity. The privacy guarantees here are properties of + on-chain state. IP-level correlation between a user's Ethereum deposit and their relayer submission is out of scope as an implementation concern, but must be disclosed as residual leakage under Supportability #9. @@ -753,7 +755,7 @@ path must state what extension is needed. #### Private LEZ account state Inbound mints deliver into private LEZ state, and outbound burns spend from it. -Unlinkability depends on this: a mint into a public account re-links the +The privacy guarantees depend on this: a mint into a public account exposes the recipient immediately. Proposals must state which LEZ private-state primitives they rely on and their maturity. @@ -801,7 +803,7 @@ Team experienced with: Estimated software delivery duration: **16–20 weeks**. This is longer than a transparent lock-and-mint bridge would require; the shielded-pool construction, client-side proving targets, note discovery and recovery, the relayer layer, and -the unlinkability test suite are the additional scope. This excludes the +the privacy test suite are the additional scope. This excludes the third-party audit lead time required before mainnet deployment (Supportability #8), which is typically procured and scheduled separately. From 72a53b5064104d73e06c9723800155c15442627e Mon Sep 17 00:00:00 2001 From: jzaki Date: Sat, 8 Aug 2026 07:01:46 +0100 Subject: [PATCH 05/69] Reduce implementation details --- RFPs/RFP-021-wrapped-erc20.md | 957 ++++++++++++++-------------------- 1 file changed, 397 insertions(+), 560 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 22c03d61..89158884 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -6,11 +6,11 @@ status: open category: Developer Tooling & Infrastructure dependencies: - id: RFP-001 - reason: Admin authority governs the supported-token registry, the per-token denomination ladder, and the deposit/redemption caps, as specified in Functionality. + reason: Admin authority governs the supported-token registry and the deposit/redemption caps, as specified in Functionality. - id: RFP-002 - reason: Freeze authority provides the circuit breaker to halt minting and/or redemption, globally or per token, if a circuit bug or vault vulnerability is suspected. + reason: Freeze authority provides the circuit breaker to halt minting and/or redemption, globally or per token, if a proof-system or vault vulnerability is suspected. - id: LP-0013 - reason: Mint/burn token authority primitives are required for the LEZ program to mint wrapped tokens into private state on verified deposit, and burn them on redemption. + reason: Mint/burn token authority primitives are required for the LEZ program to mint wrapped tokens on verified deposit, and burn them on redemption. --- @@ -48,30 +48,29 @@ dependencies: ## 🧭 Overview -Build a trustless, **privacy-preserving** lock-and-mint bridge that lets ERC-20 tokens -(and native ETH, wrapped as WETH) held on Ethereum enter LEZ as canonical -wrapped assets, and exit back to Ethereum on redemption — without any public -observer being able to connect a specific Ethereum lock to the LEZ mint it -funded, or a specific LEZ burn to the Ethereum unlock it triggered. - -An Ethereum-side vault contract escrows deposits and publishes only a -*commitment* — never a LEZ recipient. A LEZ-side program trustlessly anchors the -Ethereum commitment-tree root by verifying a RISC0 proof of Ethereum consensus -and state in-program. A user then proves, entirely on their own device, that -they own an unspent leaf under that anchored root, and the program mints the -wrapped token into **private LEZ state**. Redemption mirrors this: a burn on LEZ -publishes only a withdrawal commitment — never an Ethereum recipient — and the -Ethereum vault, having anchored the LEZ burn-tree root via a RISC0 proof -verified through a native precompile, releases the original ERC-20 to whoever -proves ownership of an unspent leaf. - -Nullifiers prevent double-spends on both legs without revealing which leaf was -consumed. Permissionless relayers submit the mint and unlock transactions so the -user never needs a funded account on either chain. The bridge core depends on -mature RISC0 implementations (e.g. Zisk) for consensus and state proof -generation, requiring teams experienced with zero-knowledge proof systems, -shielded-pool constructions, Solidity smart-contract development, LEZ program -development, and RISC0 guest environments. +Build a trustless, privacy-preserving lock-and-mint bridge that lets ERC-20 +tokens (and native ETH, wrapped as WETH) held on Ethereum enter LEZ as canonical +wrapped assets, and exit back to Ethereum on redemption. + +An Ethereum-side vault contract escrows deposits. A LEZ-side program mints the +corresponding wrapped token once it has cryptographically verified — with no +trusted intermediary — that the deposit really happened on Ethereum. Redemption +reverses the flow: burning the wrapped token on LEZ entitles the holder to +release the original ERC-20 from the vault, again on cryptographic proof alone. +Verification rests on RISC0 zero-knowledge proofs of consensus and state, +verified in-program on LEZ and via a native precompile on Ethereum. + +Crucially, the bridge must achieve this **without letting a public observer +connect a specific Ethereum deposit to the LEZ mint it funded, or a specific LEZ +burn to the Ethereum release it triggered.** That privacy property is a hard +requirement of the same standing as solvency, and it shapes the whole design: +the deposit cannot name its LEZ destination, the burn cannot name its Ethereum +destination, and no component other than the user may hold the information that +connects them. + +Teams will need experience with zero-knowledge proof systems, privacy-preserving +protocol design, Solidity smart-contract development, and LEZ program +development. ## 🔥 Why This Matters @@ -88,39 +87,32 @@ own trustless path via atomic swaps in RFP-003 explicitly carved Ethereum out of its scope for exactly this reason: "ETH is expected to reach LEZ via wrapping, which requires no swap counterparty and is a much simpler construction." Bitcoin, Monero, and Zcash lack general -smart-contract expressiveness, so a trustless swap protocol (adaptor -signatures, HTLCs, DLEQ proofs) is the only construction available for them. -Ethereum's programmability makes a lock-and-mint bridge with a vault contract -and zero-knowledge proof verification possible instead, which is the trustless -architecture used to move value onto smart-contract chains that verify -cryptographic proofs natively. +smart-contract expressiveness, so a trustless swap protocol is the only +construction available for them. Ethereum's programmability makes a lock-and-mint +bridge with a vault contract and zero-knowledge proof verification possible +instead. ### A transparent bridge would deanonymise the whole chain Privacy is not a nice-to-have here; it is the difference between this bridge strengthening LEZ's privacy guarantees and silently destroying them. -A conventional lock-and-mint bridge emits -`Deposit(token, depositor, amount, lezRecipient, nonce)` on Ethereum. That -single event publicly binds a KYC'd, fully-traced Ethereum address to a LEZ -account, permanently and for anyone to read. Because virtually all external -collateral enters LEZ through this one primitive, such a bridge becomes the -canonical deanonymisation oracle for the entire chain: an observer needs only to -scrape one Ethereum contract's logs to build an identity map covering most of -LEZ's collateral base. Every downstream privacy feature — private accounts, -the privacy-preserving DEX ([RFP-004](./RFP-004-privacy-preserving-dex.md)), -shielded lending positions — is undermined at the point of entry, no matter how -well those components protect data internally. Privacy that leaks at the on-ramp -is not privacy. - -The redemption leg is symmetric and, if anything, worse: a burn event naming -`ethereumRecipient` in the clear publishes the exit address alongside the LEZ -account that funded it, closing the loop and linking a user's entire LEZ -activity to their Ethereum identity on both ends. - -This RFP therefore treats privacy preservation as a hard requirement of the same -standing as solvency. The construction is a commitment/nullifier shielded pool -on each leg, specified in full in Design Rationale below. +A conventional lock-and-mint bridge publishes a deposit event naming both the +Ethereum depositor and the LEZ recipient. That single event permanently binds a +traceable Ethereum address to a LEZ account, for anyone to read. Because +virtually all external collateral would enter LEZ through this one primitive, +such a bridge becomes the canonical deanonymisation oracle for the entire chain: +an observer needs only to scrape one Ethereum contract's logs to build an +identity map covering most of LEZ's collateral base. Every downstream privacy +feature — private accounts, the privacy-preserving DEX +([RFP-004](./RFP-004-privacy-preserving-dex.md)), shielded lending positions — is +undermined at the point of entry, no matter how well those components protect +data internally. Privacy that leaks at the on-ramp is not privacy. + +The redemption leg is symmetric and, if anything, worse: a burn naming its +Ethereum destination publishes the exit address alongside the LEZ account that +funded it, closing the loop and connecting a user's entire LEZ activity to their +Ethereum identity at both ends. ### Stablecoins are the concrete prize @@ -134,270 +126,152 @@ collateral base at launch. Bridges are also the most attacked category of infrastructure in DeFi: Chainalysis has tracked more than $2.8B stolen from cross-chain bridges since 2022, the highest-value class of exploit in the industry. This RFP's security -posture — cryptographic verification via RISC0 zero-knowledge proofs, -eliminating the trust-in-signers vector entirely, combined with per-token and -global deposit/redemption caps and an admin-governed freeze-authority circuit -breaker — is designed directly against that track record. No signer compromise, -key theft, or participant collusion can lead to spurious minting or release. +posture — cryptographic verification eliminating the trust-in-signers vector +entirely, combined with per-token and global caps and an admin-governed freeze +authority — is designed directly against that track record. ## 🏗 Design Rationale ### The privacy requirement, stated precisely -Two privacy properties must hold against an adversary who observes **all** -public state on both chains, indefinitely, and who may themselves deposit and -redeem: +Two properties must hold against an adversary who observes **all** public state +on both chains, indefinitely, and who may themselves deposit and redeem: -- **P1 (inbound).** Given an Ethereum lock event and the set of all LEZ mint - transactions, the adversary cannot determine which mint consumed that lock - with probability better than uniform over the inbound anonymity set. -- **P2 (outbound).** Given a LEZ burn event and the set of all Ethereum unlock - transactions, the adversary cannot determine which unlock was funded by that - burn with probability better than uniform over the outbound anonymity set. +- **P1 (inbound).** Given an Ethereum deposit, the adversary cannot determine + which LEZ mint it funded, with probability better than uniform over the + inbound anonymity set. +- **P2 (outbound).** Given a LEZ burn, the adversary cannot determine which + Ethereum release it triggered, with probability better than uniform over the + outbound anonymity set. Both properties are stated relative to an *anonymity set*, and both degrade to nothing when that set is small. Sizing, measuring and surfacing the anonymity -set is therefore a first-class requirement, not an implementation detail — see -Usability #7 and the Privacy Preservation requirements. +set is therefore a first-class requirement, not an implementation detail. + +### What cannot be hidden Two facts are fixed by the environment and cannot be designed away. Proposals must not claim otherwise: -1. **The Ethereum lock amount is public.** It is an ERC-20 `Transfer` into the - vault. So is the depositor's address, since they send the transaction. -2. **The Ethereum unlock amount and recipient are public.** The vault must move - real tokens to a real address. - -Privacy is preserved by making these public facts *uninformative about which -counterparty they pair with*, not by hiding them. - -### Fixed denominations - -Amounts are the strongest linkage vector: a lock of 1,337.42 USDC followed by a -mint of 1,337.42 wUSDC is linked by elimination regardless of what cryptography -sits between them. Since the Ethereum-side amount cannot be hidden, its -*fingerprint* must be destroyed instead. - -Every supported token therefore carries an admin-registered **denomination -ladder** (e.g. 1 / 10 / 100 / 1,000 / 10,000 USDC). Locks and unlocks are -permitted only at exactly these values; a user bridging 4,300 USDC does so as -4×1,000 + 3×100 notes. Thousands of users share each rung, so the public amount -identifies only the rung, not the user. Supply accounting remains scalar, which -keeps the LEZ mint authority within what [LP-0013](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md) -provides, and keeps the caps in Functionality #11 straightforwardly enforceable. - -The cost is real and must be handled in the UX: users split large transfers -across several notes, and remainders below the smallest rung cannot be bridged. -Proposals must specify the default ladder per token and justify the rung -spacing against expected transfer sizes. - -Shielded value commitments — hiding amounts entirely via homomorphic supply -accounting and range proofs — are the stronger construction and are specified as -Soft Requirement #1. The note format, circuit interfaces, and tree layout -delivered under this RFP must be chosen so that migration to shielded values -does not require redeploying the vault or re-anchoring the pool. - -### Inbound: lock → anchor → prove → mint into private state - -1. **Ethereum vault contract.** A Solidity contract holding an incremental - Merkle tree of deposit commitments. To deposit, a user picks a denomination - `d` for a registered token, samples secrets locally, and computes - `C = H(nullifierSecret, spendSecret, token, d)`. The vault pulls `d` units of - the token and inserts `C` as a leaf. The emitted event is - `Deposit(token, d, commitment, leafIndex, noteCiphertext)`. - - **There is no `lezRecipient` field and no `depositor` field.** This is the - central change from a conventional bridge. `noteCiphertext` is the note - encrypted to the recipient's LEZ viewing key, allowing a third-party - depositor to fund someone else's LEZ account without an out-of-band secret - handoff; the recipient discovers it by trial decryption. - -2. **Trustless root anchoring on LEZ.** A permissionless daemon submits a RISC0 - proof of (a) Ethereum consensus at a finalised block height and (b) the value - of the vault's commitment-tree root in that state. The LEZ bridge program - verifies this proof **in-program** and records the root. The daemon handles - only public chain data, holds no user secrets, and cannot insert a false root - — the program rejects any root not backed by a valid consensus proof. This is - what makes client-side proving feasible without introducing a trusted party. - -3. **Client-side ownership proof.** The user's own device generates a proof that - it knows the secrets behind *some* leaf under an anchored root, and derives - `nullifier = H(nullifierSecret)`. Public inputs are - `(anchoredRoot, token, d, nullifier, relayer, relayerFee)`. The Merkle path, - the leaf index, and both secrets are private inputs and never leave the - device. Because the proof is only a membership-and-hash argument against an - already-anchored root — not a consensus verification — it is small enough to - generate on the desktop hardware Basecamp already targets. - -4. **Mint.** The LEZ bridge program verifies the proof, rejects the transaction - if `nullifier` is already in the spent set, records it, and mints `d` units - of the wrapped token — `relayerFee` to the relayer's public account and the - remainder **into private LEZ state**, where neither the balance nor the owner - is publicly visible. - -The mint transaction publishes a nullifier and a root. It reveals nothing about -which of the N unconsumed same-denomination deposits it consumed, satisfying P1 -with an anonymity set of N. - -### Outbound: burn → commit → anchor → prove → unlock - -The redemption leg is the inbound leg run backwards, and its critical property -is that **the burn does not name the Ethereum recipient**. Naming it there is -precisely the leak that P2 forbids, so the flow is split into two stages -separated by a user-chosen delay. - -1. **Burn on LEZ.** A holder spends a private wrapped-token note of value `d`, - samples a fresh `ethSecret` locally, and the bridge program inserts a - withdrawal commitment `W = H(ethSecret, token, d)` into an on-chain - burn-commitment tree, emitting a structured event (per - [LP-0012](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md)) - carrying `(token, d, W, leafIndex)` — and nothing else. The spent LEZ note's - own nullifier is recorded to prevent double-burn. - -2. **Trustless root anchoring on Ethereum.** A permissionless daemon submits a - RISC0 proof of LEZ consensus at a finalised epoch and the burn-tree root in - that state. The vault verifies it via a **native precompile** (Groth16 - verifier or equivalent) — a single cheap verification step, matching the - LEZ-side/EVM-side cost asymmetry documented in RFP-020 — and records the - root. - -3. **Client-side unlock proof.** At a time of the user's choosing, their device - proves knowledge of `ethSecret` for some leaf under an anchored burn root, - publishing `nullifier' = H(ethSecret)` and public inputs - `(anchoredBurnRoot, token, d, ethereumRecipient, relayer, relayerFee)`. - -4. **Release.** The vault verifies the proof, rejects a replayed `nullifier'`, - and releases `d - relayerFee` of the original ERC-20 (or unwrapped ETH, for - WETH redemptions) to `ethereumRecipient`, and `relayerFee` to the relayer. - -`ethereumRecipient` is bound inside the proof, so a relayer can neither redirect -the funds nor inflate their fee. The unlock reveals a recipient and an amount, -but not which burn funded it, satisfying P2. - -### Client-side proving, and why no daemon holds a witness - -All proving that touches user-linked data happens on the user's device. The -daemons exist only to anchor roots, and a root is public chain state — a daemon -that observed every deposit and every anchor operation still cannot say which -mint consumed which lock, because it never sees a witness. - -Critically, the daemons are also **trustless, not merely honest-but-curious**: -each anchoring submission carries a consensus proof that the receiving chain -verifies before accepting the root. A malicious or compromised daemon can -withhold service, but cannot forge a root, cannot mint, and cannot deanonymise. -Anchoring is permissionless precisely so that withholding is not a viable -attack — any party can run a daemon, and proposals must document how a user can -run their own or trigger an anchor themselves if none is available. - -Proposals must state explicitly, in the privacy document required by -Supportability #9, that no component other than the user's own client ever -receives a Merkle path, a leaf index, or a note secret. - -### Timing decorrelation - -A perfect commitment scheme is defeated by a user who locks on Ethereum and -mints on LEZ ninety seconds later when no one else is bridging. Timing is a -linkage vector in its own right and the protocol must not force users into -correlated behaviour. - -Accordingly: a proof may be submitted at **any** time after the relevant root is -anchored, with no expiry; the client must default to a randomised delay rather -than immediate submission; and the client must show the user the current -anonymity set for their `(token, denomination)` pair and warn before submitting -into a set below a configurable threshold. Users must be able to override, but -must be told what they are giving up. - -### Relayers and fee payment - -If a user pays their own LEZ gas to mint, the funding source of that account -re-links them to the deposit, and the whole construction collapses. Mint and -unlock transactions are therefore submitted by **permissionless relayers**, paid -out of the bridged amount inside the circuit. - -Because `relayer` and `relayerFee` are public inputs bound into the proof, a -relayer cannot alter the recipient, redirect funds, or claim more than the -agreed fee; the worst they can do is decline to relay. Fee amounts must be drawn -from a small fixed schedule (or a fixed fraction of the denomination) rather -than being freely user-chosen — an arbitrary fee value is itself a fingerprint -that re-identifies the transaction. - -### Note custody and recovery - -In a commitment scheme, losing a note secret means the locked ERC-20 is -permanently unrecoverable — there is no administrative recovery path, by -construction. This is the single largest UX risk in the design and must be -addressed directly, not disclaimed. - -Note secrets must therefore be derived deterministically from a single -recoverable seed (e.g. a signature over a fixed domain-separated message from -the user's existing wallet), so that a user restoring that wallet can rediscover -all their notes by scanning the commitment trees and trial-decrypting note -ciphertexts. Ad-hoc random secrets requiring manual backup are not acceptable. +1. **The Ethereum deposit amount is public**, as is the depositor's address — + it is an ordinary ERC-20 transfer into the vault, sent by the depositor. +2. **The Ethereum release amount and recipient are public** — the vault must + move real tokens to a real address. + +Privacy is therefore preserved by making these public facts *uninformative about +which counterparty they pair with*, not by attempting to hide them. Three +consequences follow, and proposals must address each: + +- **Amounts correlate.** A deposit of 1,337.42 USDC followed by a mint of + 1,337.42 wUSDC is matched by elimination regardless of what cryptography sits + between them. The amount visible on the Ethereum side must not act as a + fingerprint. +- **Timing correlates.** A deposit followed promptly by a mint, at a quiet + moment, is matched by inspection. The protocol must not force users into + correlated timing. +- **Fee payers correlate.** If the user pays their own gas to mint or release, + the funding source of that account re-identifies them and the construction + collapses. + +### Suggested approach + +The following is offered as orientation, not prescription. Proposals are free to +achieve the required properties by other means, provided they argue the case. + +A commitment-and-nullifier shielded pool on each leg is the well-understood +construction for this problem: the deposit publishes a commitment rather than a +destination, and the claimant later proves entitlement without revealing which +deposit they are claiming, with a nullifier preventing double-claims. The +redemption leg works the same way in reverse, which requires splitting redemption +into two separately-timed stages so that the burn need not name its Ethereum +destination. + +Minting into **private LEZ state** is the natural fit for the destination side, +and keeps the recipient and balance off public view without additional +machinery. + +For the amount-correlation problem, restricting transfers to a fixed set of +per-token denominations is the simpler and better-understood option, and is the +expected baseline for this RFP; hiding amounts outright via value commitments is +stronger but considerably heavier, and is specified as a soft requirement below. + +For the fee-payer problem, permissionless relayers paid out of the bridged amount +are the conventional answer, with the destination bound into the proof so a +relayer cannot redirect funds or overcharge. + +For the trust problem, note that a proof of source-chain consensus and state +contains no user-specific data, so it can be produced by anyone and anchored +on-chain permissionlessly, leaving the user's own device to prove only their +entitlement against it. This keeps user-specific proving cheap enough to run +locally, which matters because whoever generates the entitlement proof learns +the connection the design exists to protect. + +### Trust model + +This bridge is **trustless**. It requires no trust in signers, validators, +attestor federations, relayers, or proof-generation services. A user relies only +on the correctness of the proof system, the security of the Ethereum network, +and the security of the LEZ network. + +Any off-chain participant in the design may be trusted for **liveness only** — +able to decline service, but never able to steal, redirect, forge, censor +selectively, or deanonymise. Proposals must identify every such participant and +justify that each is liveness-only. + +Caps and the freeze authority remain in place as operational safety mechanisms +independent of the cryptographic trust model. Note that the freeze authority can +necessarily operate at token and protocol granularity only: it cannot freeze an +individual user's holdings, because the protocol does not know whose are whose. +This is a designed consequence of the privacy guarantees, not a gap, and must be +documented as such. + +### Loss of access + +In any design meeting these requirements, the protocol cannot identify who owns +what, so there is no administrative recovery path when a user loses access. This +is the largest UX risk in the RFP and must be designed against rather than +disclaimed: a user must be able to recover their full bridge position from +credentials they already hold and already back up. Requiring users to separately +back up new secrets generated during a deposit is not acceptable. ### Token registry and decimal normalisation Each supported ERC-20 is registered individually by the admin authority: its Ethereum contract address, its LEZ wrapped-token mint, its decimals, its -denomination ladder, and its per-token deposit/redemption caps. ERC-20 tokens -do not share a common decimals convention (6 for USDC, 8 for WBTC, 18 for WETH -and DAI); the wrapped LEZ mint for each token must document its own decimals and -the exact conversion applied on mint and burn, and the registration instruction -must reject a token whose decimals or denomination ladder cannot be represented -exactly in the chosen LEZ mint precision. - -Fee-on-transfer and rebasing ERC-20s break the invariant that a locked -denomination equals a mintable denomination. The registry must reject them, and -the vault must verify the actual balance delta on deposit rather than trusting -the requested amount. - -### Finality windows and reorg protection - -A root must not be anchored until the source-chain state it commits to has -reached a configured finality depth (a block-count or, once generally available, -a beacon-chain finalised-checkpoint condition). Anchoring a pre-finality root -risks admitting deposits that a reorg later removes, which would mint wrapped -tokens against locks that no longer exist. The chosen depth is a direct -trade-off between user-facing latency and reorg risk, and proposals must -document the depth chosen and the residual risk it leaves. The reverse direction -is symmetric: the vault anchors a LEZ burn root only after LEZ finality. - -Because anchoring is decoupled from user proofs, a reorg affects only the -anchoring step. Anchored roots are append-only and never rolled back, so no user -proof is ever invalidated by later chain activity. - -### Trust model: cryptographic, trustless - -This bridge is **trustless**. It requires no trust in external signers, -validators, attestor federations, or relayers. A user who bridges an ERC-20 -asset relies only on the correctness of the RISC0 circuits, the security of the -Ethereum network, and the security of the LEZ network. Both legs are verified by -cryptographic proofs, not by signatures from a bounded set of participants. - -Relayers are trusted for **liveness only** — they can decline to submit, but -cannot steal, redirect, censor selectively (they cannot tell users apart), or -deanonymise. Anchoring daemons are likewise liveness-only. - -Proposals must state this trustlessness explicitly in user-facing documentation -(mini-app, README, SDK docs), alongside an honest statement of the -privacy guarantees and their dependence on anonymity-set size. Per-token and -global caps and the freeze-authority circuit breaker remain in place as -operational safety mechanisms independent of the cryptographic trust model. - -Note that the freeze authority operates at token and protocol granularity only. -It **cannot** freeze an individual user's funds, because the protocol does not -know which funds belong to whom. This is a designed consequence of the privacy -guarantees, not a gap, and must be documented as such. +permitted transfer amounts, and its per-token caps. ERC-20 tokens do not share a +common decimals convention (6 for USDC, 8 for WBTC, 18 for WETH and DAI); the +wrapped LEZ mint for each token must document its own decimals and the exact +conversion applied on mint and burn, and registration must reject any token +whose values cannot be represented exactly in the chosen LEZ mint precision. + +Fee-on-transfer and rebasing ERC-20s break the invariant that the amount +deposited equals the amount mintable. The registry must reject them, and the +vault must verify the actual balance delta on deposit rather than trusting the +requested amount. + +### Finality and reorg protection + +Wrapped tokens must not be minted against an Ethereum deposit that a reorg could +still remove, and the vault must not release against a LEZ burn that is not yet +final. Both directions require a configured finality condition on the source +chain. The chosen depth is a direct trade-off between user-facing latency and +reorg risk; proposals must document the depth chosen and the residual risk it +leaves. + +Once a user's claim is valid it must remain valid indefinitely, since users are +expected to delay their own submissions for privacy reasons and must never be +forced to act promptly to avoid expiry. ### Fee structure -This RFP does not mandate a specific protocol fee rate (relayer fees are -separate and market-set within the fixed schedule above). Proposals must specify -who pays, when fees are collected, the exact rate, and where fees are routed. -A governance-activatable fee switch with an initial zero rate, gated by the -admin authority per RFP-001, is the recommended baseline, consistent with the -pattern used elsewhere in the Logos RFP set (see -[RFP-017](./RFP-017-token-vesting.md), "Fee structure"). Any protocol fee must -be a fixed function of the denomination, for the fingerprinting reason above. +This RFP does not mandate a specific protocol fee rate. Proposals must specify +who pays, when fees are collected, the exact rate, and where fees are routed. A +governance-activatable fee switch with an initial zero rate, gated by the admin +authority per RFP-001, is the recommended baseline, consistent with the pattern +used elsewhere in the Logos RFP set (see +[RFP-017](./RFP-017-token-vesting.md), "Fee structure"). Any fee paid by a user — +protocol or relayer — must take a value that does not distinguish their +transaction from others, since a distinctive fee is itself a fingerprint. ## ✅ Scope of Work @@ -407,164 +281,137 @@ Use FURPS framework. Each numbered item should be a testable statement. #### Functionality -1. Implement an Ethereum vault contract (Solidity) maintaining an incremental - Merkle tree of deposit commitments. It accepts deposits of any ERC-20 in the - supported-token registry, plus native ETH (auto-wrapped to WETH), **only at - values on that token's registered denomination ladder**. It emits - `Deposit(token, denomination, commitment, leafIndex, noteCiphertext)` and - **must not** emit, store, or otherwise publish a LEZ recipient. The vault - verifies the actual balance delta on deposit and rejects any token whose - transfer does not deliver the exact denomination. -2. Implement a permissionless inbound anchoring path: a RISC0 proof of Ethereum - consensus at a configured finality depth plus the vault's commitment-tree - root in that state, verified **in-program** by the LEZ bridge program before - the root is recorded. Anchored roots are append-only. Submitting an - unbacked, malformed, or pre-finality root must be rejected without recording. -3. Implement a public-mode LEZ bridge program mint instruction accepting a - client-generated ownership proof with public inputs - `(anchoredRoot, token, denomination, nullifier, relayer, relayerFee)`. On - successful verification it mints `relayerFee` to the relayer's public account - and the remainder **into private LEZ state**. The Merkle path, leaf index, - and note secrets must be private inputs to the circuit. -4. Each inbound `nullifier` may be consumed at most once; resubmission of a - spent nullifier must be rejected deterministically without minting, and must - not reveal which leaf the nullifier corresponds to. -5. Implement a burn instruction on the LEZ bridge program: a holder spends a - private wrapped-token note of a registered denomination, and the program - inserts a withdrawal commitment into an on-chain burn-commitment tree and - emits a structured event (per LP-0012) carrying - `(token, denomination, withdrawalCommitment, leafIndex)`. The instruction and - its event **must not** accept, store, or publish an Ethereum recipient - address. -6. Implement a permissionless outbound anchoring path: a RISC0 proof of LEZ - consensus at a configured finality depth plus the burn-tree root in that - state, verified by the Ethereum vault via a native precompile (Groth16 - verifier or equivalent) before the root is recorded. Anchored roots are - append-only. -7. The Ethereum vault accepts a client-generated unlock proof with public inputs - `(anchoredBurnRoot, token, denomination, ethereumRecipient, relayer, relayerFee)`, - verifies it via the precompile, and releases `denomination - relayerFee` of - the original ERC-20 (or unwrapped ETH, for WETH redemptions) to - `ethereumRecipient` and `relayerFee` to `relayer`. Each outbound nullifier - may be consumed at most once. -8. Note secrets are derived deterministically from a single recoverable seed. - Implement note discovery: given the seed, a client can reconstruct its full - note set by scanning both commitment trees and trial-decrypting note - ciphertexts, recovering all unspent notes without any server-side index. -9. `relayerFee` must be constrained on-chain to a value on a registered fee - schedule (or a fixed fraction of the denomination); a proof carrying an - arbitrary fee value must be rejected. -10. An admin authority (per RFP-001, integrated via the SPEL framework where - applicable to the LEZ side) can register a new supported ERC-20 (Ethereum - address, LEZ wrapped mint, decimals, denomination ladder, fee schedule, - per-token caps) and deregister a token. Registration changes must be - mirrored consistently on both sides (document how the two stay in sync and - what happens if they temporarily diverge). The registry must reject - fee-on-transfer and rebasing tokens. -11. Global and per-token deposit and redemption caps (configurable by the admin - authority) bound the maximum value that can be minted or released within a - rolling window, as a rate-limiting circuit breaker independent of the freeze - authority. Cap enforcement must not require identifying individual users. -12. A freeze authority (per RFP-002) can pause minting and/or redemption, either - globally or for a single registered token, on both the Ethereum vault and - the LEZ bridge program independently. +1. Implement an Ethereum vault contract (Solidity) that escrows deposits of any + ERC-20 in the supported-token registry, plus native ETH (auto-wrapped to + WETH). The vault must verify the actual balance delta received and reject any + deposit that does not deliver the expected amount. +2. A deposit must not publish, store, or otherwise reveal its LEZ destination. + No Ethereum transaction argument, event, or contract state may identify the + account that will receive the wrapped tokens. +3. Implement a LEZ bridge program that mints the corresponding wrapped token on + cryptographic verification of a valid Ethereum deposit, using RISC0 proofs of + Ethereum consensus and state verified in-program. Verification must require + no trusted party. +4. Wrapped tokens are minted into private LEZ state by default, so that neither + the recipient nor the balance is publicly visible. +5. Each deposit may be claimed at most once. A repeat claim must be rejected + deterministically, without minting, and without revealing which deposit it + referred to. +6. Implement a burn path on the LEZ bridge program that entitles the holder to + release the original asset from the Ethereum vault. The burn must not + publish, store, or otherwise reveal its Ethereum destination. +7. The Ethereum vault releases the original ERC-20 (or unwrapped ETH, for WETH + redemptions) on cryptographic verification of a valid LEZ burn, using a RISC0 + proof verified natively via a precompile (Groth16 verifier or equivalent). + Each burn may be redeemed at most once. +8. The amounts visible on Ethereum must not identify which mint or burn they + correspond to. Proposals must state the mechanism chosen (fixed + denominations are the expected baseline) and its effect on anonymity-set + size. +9. A user must be able to complete both flows without holding a funded account + on either chain, and whoever submits or pays for a transaction on the user's + behalf must not thereby learn, or be able to prove, which deposit or burn it + corresponds to. That party must not be able to alter the destination or take + more than an agreed fee. +10. A user must be able to recover their full bridge position — every claimable + deposit and every unredeemed burn — from credentials they already hold, with + no dependence on any server-side index and no separately-backed-up secret + generated during the flow. +11. An admin authority (per RFP-001, integrated via the SPEL framework where + applicable to the LEZ side) can register a supported ERC-20 (Ethereum + address, LEZ wrapped mint, decimals, permitted amounts, caps) and deregister + a token. Registration changes must be mirrored consistently on both sides; + document how the two stay in sync and what happens if they temporarily + diverge. The registry must reject fee-on-transfer and rebasing tokens. +12. Global and per-token deposit and redemption caps, configurable by the admin + authority, bound the maximum value that can be minted or released within a + rolling window, as a rate limiter independent of the freeze authority. Cap + enforcement must not require identifying individual users. +13. A freeze authority (per RFP-002) can pause minting and/or redemption, either + globally or for a single registered token, on the Ethereum vault and the LEZ + bridge program independently. #### Usability -1. Provide an SDK to build Logos modules for: constructing and submitting - deposits, deriving and managing notes, discovering owned notes by scanning, - generating inbound and outbound proofs locally, submitting via a relayer, - querying anchoring progress and anonymity-set size, initiating a redemption - burn, and reading the supported-token registry and denomination ladders. +1. Provide an SDK that can be used to build Logos modules for: depositing, + claiming a deposit on LEZ, redeeming, releasing on Ethereum, recovering a + position from user credentials, and reading the supported-token registry and + its permitted amounts. 2. Provide a Logos mini-app GUI with local build instructions, downloadable - assets, and loadable in Logos app (Basecamp) via git repo. It must cover: a - deposit flow (connect Ethereum wallet, select denomination, approve and - deposit, note derivation and backup confirmation), a mint flow (local proof - generation with progress, delay selection, relayer submission), a redemption - flow (burn, then a separately-timed unlock with recipient entry), a note - inventory and recovery flow, and a registry view (supported tokens, ladders, - caps and current utilisation). -3. Provide a CLI covering core functionality: deposit, discover notes, generate - proof, mint, burn, unlock, and query the registry. The CLI may have fewer - features than the mini-app but must support all essential operations, - including proof generation and note recovery entirely offline. -4. Provide the inbound and outbound anchoring daemons as **Logos modules - accompanied by Logos Core headless CLI/daemons**, runnable as standalone - long-running processes. Each must support: configurable Ethereum and/or LEZ - RPC endpoints, configurable finality depth, configurable anchoring cadence, - structured logging, and a clean shutdown path. They must integrate with or - wrap mature RISC0 implementations (e.g. Zisk) without reimplementing - zero-knowledge primitives. Document the operator journey end-to-end: install, - configure, run, monitor. -5. Provide a reference relayer implementation, runnable permissionlessly, with - documented fee policy and submission logic. Document how a user submits - without a relayer if they accept the privacy cost of paying their own gas. -6. Provide an IDL for the LEZ bridge program using the + assets, and loadable in Logos app (Basecamp) via git repo. It must cover the + deposit and redemption flows end to end, position recovery, and a registry + view showing supported tokens, permitted amounts, caps and current + utilisation. +3. Provide a CLI that covers core functionality: deposit, claim, redeem, + release, recover, and query the registry. The CLI may have fewer features + than the mini-app but must support all essential operations. +4. Any long-running off-chain component the design requires must be provided as + a **Logos module accompanied by a Logos Core headless CLI/daemon**, runnable + standalone, supporting configurable RPC endpoints for both chains, + configurable finality depth, structured logging, and a clean shutdown path. + Proposals must integrate mature RISC0 implementations (e.g. Zisk) rather than + reimplementing zero-knowledge primitives. Document the operator journey + end-to-end: install, configure, run, monitor. +5. Provide an IDL for the LEZ bridge program using the [SPEL framework](https://github.com/logos-co/spel). -7. Both the mini-app and CLI must display, before any mint or unlock - submission, the current anonymity set size for the relevant - `(token, denomination)` pair, and must warn when it falls below a - configurable threshold. The default submission delay must be randomised - rather than immediate, with the user able to inspect and override it. +6. Before any privacy-sensitive submission, the mini-app and CLI must show the + user the current anonymity set their transaction would join, and warn when it + falls below a configurable threshold. Where delaying a submission improves + privacy, the client must default to doing so rather than submitting + immediately, with the user able to inspect and override. +7. Documentation and UI must clearly explain what is public and what is private + at each step on both chains, in the manner of + [RFP-004](./RFP-004-privacy-preserving-dex.md), so users can judge their own + exposure. 8. Return clear, actionable error messages for all failure modes: unsupported - token, invalid denomination, cap exceeded, invalid proof, proof verification - failure, root not yet anchored, insufficient finality, nullifier already - spent, invalid relayer fee, and program or per-token frozen. Error messages - must not leak which leaf or note a failed proof referred to. + token, invalid amount, cap exceeded, verification failure, insufficient + finality, already claimed, and program or per-token frozen. Error messages + must not reveal which deposit or burn a failed attempt referred to. #### Reliability -1. Minting is atomic: a failed or rejected mint attempt does not consume the - nullifier and leaves the note spendable on retry. -2. Burn-and-unlock is atomic at each stage: a failed burn does not destroy a - note without inserting a corresponding withdrawal commitment, and a failed - unlock does not consume the outbound nullifier. -3. A nullifier can be consumed at most once on each leg; replaying an - already-verified proof is rejected deterministically and does not double-mint - or double-release. -4. Anchored roots are append-only and never invalidated. A proof valid against a - historical anchored root must remain valid indefinitely, so a user who - delays submission for privacy reasons is never forced to regenerate. -5. Note recovery is complete: a client restored from seed alone must rediscover - every unspent note it owns on both legs, verified by a test that wipes all - local state and recovers from seed. -6. A temporary RPC or connectivity failure leaves an anchoring daemon in a - recoverable state, able to resume once connectivity is restored without - re-anchoring already-anchored roots. -7. Client-side proof generation is resumable or cheaply restartable: an - interrupted proof does not consume, corrupt, or expose the note. +1. Minting is atomic: a failed or rejected claim leaves the deposit claimable on + retry and consumes nothing. +2. Redemption is atomic at each stage: a failed burn does not destroy wrapped + tokens without preserving the holder's entitlement to release, and a failed + release leaves that entitlement intact. +3. No deposit can be claimed twice and no burn redeemed twice, deterministically + and under adversarial retry. +4. A valid claim remains valid indefinitely; later chain activity must never + invalidate a user's outstanding entitlement. +5. Position recovery is complete: a client restored from user credentials alone + must rediscover every claimable deposit and unredeemed burn, verified by a + test that wipes all local state. +6. Temporary RPC or connectivity failure on either chain leaves any off-chain + component in a recoverable state, able to resume without duplicating work + already done. +7. An interrupted user-side operation does not consume, corrupt, or expose the + user's entitlement. #### Performance -1. Verifying an inbound ownership proof and minting must complete within a - single LEZ public transaction at the per-transaction compute budget in force - at delivery time. Document the compute-unit cost, broken down between proof - verification, nullifier-set insertion, and the mint instruction, extending +1. Verifying an inbound claim and minting must complete within a single LEZ + public transaction at the per-transaction compute budget in force at delivery + time. Document the compute-unit cost with a breakdown by component, extending the measurement methodology from [RFP-020](./RFP-020-redstone-oracle-adaptor.md). -2. Document the compute-unit cost of in-program verification of the inbound - **anchoring** proof (Ethereum consensus + state), separately from #1, and the - amortised per-deposit cost at the recommended anchoring cadence. -3. Document the Ethereum-side gas cost of (a) a deposit, (b) verifying an - outbound anchoring proof via precompile, and (c) verifying an unlock proof - and releasing funds. Benchmark against comparable proof-verification - precompiles on EVM networks where available. -4. **Client-side proof generation must be practical on the desktop hardware - Basecamp runs on.** Measure and document wall-clock generation time and peak - memory for both the inbound ownership proof and the outbound unlock proof, on - at least: a mid-range laptop, and the lowest-specification machine the team - declares as supported. State that minimum specification explicitly, and - report results for the mini-app and the CLI separately if their proving paths - differ. Mobile and browser proving targets are out of scope (see Out of - Scope). -5. Document end-to-end deposit latency (lock to LEZ mint) and redemption latency - (burn to Ethereum release), each broken down by: source-chain finality wait, - anchoring wait, client proof generation, privacy delay, and on-chain +2. Document the compute-unit cost of any additional LEZ-side verification the + design requires beyond the per-claim path, and its amortised per-deposit cost + at the recommended operating cadence. +3. Document the Ethereum-side gas cost of a deposit, of a release, and of any + additional on-chain verification the design requires. +4. Any proving the user's own device must perform has to be practical on the + desktop hardware Basecamp runs on. Measure and document wall-clock time and + peak memory on a mid-range laptop and on the lowest specification the team + declares as supported, and state that minimum explicitly. +5. Document end-to-end deposit latency (deposit to LEZ mint) and redemption + latency (burn to Ethereum release), each broken down by source-chain finality + wait, proof generation, any privacy-motivated delay, and on-chain verification. -6. Document anchoring proof generation time for both directions and the compute - resources (CPU, RAM, time) required to run an anchoring daemon. -7. Document the growth rate and on-chain storage cost of both commitment trees - and both nullifier sets, and the projected cost at 1M and 10M notes. +6. Document the compute resources (CPU, RAM, time) required to run any + off-chain component the design requires. +7. Document the growth rate and on-chain storage cost of all bridge state that + accumulates with usage, with projections at 1M and 10M operations. #### Supportability @@ -578,119 +425,116 @@ Use FURPS framework. Each numbered item should be a testable statement. and Privacy Preservation has at least one corresponding test. 4. A README documents end-to-end usage: contract and program addresses, deployment steps for both chains, and step-by-step instructions for - depositing, minting, burning and unlocking via CLI and mini-app. + depositing and redeeming via CLI and mini-app. 5. Submit a [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for the SDK, covering the developer integration journey for both legs - including note management and local proof generation. + for the SDK, covering the developer integration journey for both flows + including position recovery. 6. Submit a [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for the CLI, the anchoring daemons, and the reference relayer, covering the - core user and operator journeys respectively. + for the CLI and any operator-facing components, covering the core user and + operator journeys respectively. 7. Provide Figma designs or equivalent for all mini-app GUI artefacts, including - the anonymity-set disclosure and the note-backup confirmation flows. + the anonymity-set disclosure and the recovery flow. 8. The Ethereum vault contract undergoes an independent third-party smart-contract security audit before mainnet deployment; the audit report (or a summary, if the full report is not publishable) must be linked from the README. This requirement exists because cross-chain bridges are the single most-attacked category of DeFi infrastructure (Chainalysis has tracked more than $2.8B stolen from bridges since 2022); it is not optional. -9. Provide a **privacy properties document** covering: a - formal statement of P1 and P2 and the anonymity set each is measured against; - exactly what is visible on-chain for every operation on both chains; what an - adversary observing all public state can and cannot infer; confirmation that - no component other than the user's client ever receives a Merkle path, leaf - index, or note secret; what a relayer, an anchoring daemon operator, and an - RPC provider can each observe; residual leakage from timing, denomination - choice, gas payment, IP-level metadata, and note-splitting patterns; and the - conditions under which these privacy guarantees degrade or fail. +9. Provide a **privacy properties document** covering: a formal statement of P1 + and P2 and the anonymity set each is measured against; exactly what is + visible on-chain at every step on both chains; what an adversary observing + all public state can and cannot infer; what every off-chain participant in + the design can observe; residual leakage from timing, amount selection, fee + payment, network metadata and usage patterns; and the conditions under which + the guarantees degrade or fail. 10. Document the anonymity-set growth model: expected set size over time at - projected volumes, the minimum set size below which the guarantee is - considered not to hold, and guidance for users bridging before the pool has - matured. + projected volumes, the minimum below which the guarantees are considered not + to hold, and guidance for users bridging before the pool has matured. #### + Bridge Security -1. RISC0 proof verification must be deterministic and independently verifiable. - The LEZ program and Ethereum vault must both reject proofs that fail - verification, tested with invalid proofs (incorrect public inputs, proofs for - incorrect chain state, tampered headers, proofs against unanchored roots, - proofs reusing a spent nullifier). -2. Anchoring daemons must independently derive chain state from RPC calls to the - source chain; a daemon must not accept and forward a root or proof supplied - by a third party without independently regenerating and verifying it. -3. A malicious relayer must not be able to alter `ethereumRecipient`, inflate - `relayerFee`, or replay a user's proof to a different destination. Test each - case explicitly. -4. Global and per-token caps (Functionality #11) bound the maximum value at risk - in any rolling window; proposals must document recommended default caps and - the reasoning behind them. -5. The freeze authority (Functionality #12) must be exercisable independently on +1. Proof verification must be deterministic and independently verifiable. Both + the LEZ program and the Ethereum vault must reject invalid proofs, tested + with incorrect public inputs, proofs for incorrect chain state, tampered + headers, and replayed proofs. +2. Any off-chain component must independently derive chain state from the source + chain rather than accepting data supplied by a third party without + verification. +3. A malicious party submitting on a user's behalf must not be able to redirect + funds, inflate their fee, or replay the user's submission to a different + destination. Test each case explicitly. +4. Caps (Functionality #12) bound the maximum value at risk in any rolling + window; proposals must document recommended defaults and the reasoning behind + them. +5. The freeze authority (Functionality #13) must be exercisable independently on each half, so either can be paused without the other being operational or reachable. -6. Soundness of supply: the total wrapped supply on LEZ must never exceed the - vault's holdings. Provide a test that attempts to mint without a valid - deposit, mint twice from one deposit, and unlock without a valid burn. +6. Soundness of supply: total wrapped supply on LEZ must never exceed the + vault's holdings. Provide tests attempting to mint without a valid deposit, + mint twice from one deposit, and release without a valid burn. 7. User-facing documentation must state the trustless verification model and the - liveness-only role of relayers and anchoring daemons (see Design Rationale, - "Trust model"). + liveness-only role of any off-chain participant (see Design Rationale, "Trust + model"). #### + Privacy Preservation 1. **P1 must hold under test.** Provide an automated test that constructs a - population of deposits and mints and asserts that no public-state-derived - correlation identifies the true lock↔mint pairing better than chance across - the anonymity set. -2. **P2 must hold under test.** The equivalent test for burn↔unlock pairings. -3. No deposit event, burn event, transaction argument, log, or account-state - change on either chain may contain a LEZ recipient at deposit time or an - Ethereum recipient at burn time. Provide a test that asserts this over full - event and state diffs for a complete round trip. -4. Merkle paths, leaf indices, and note secrets must be private circuit inputs. - Provide a test asserting they are absent from all public inputs and all - submitted transaction data. -5. Failure and error paths must not leak note identity: a rejected proof, a - spent nullifier, and a cap rejection must be indistinguishable with respect - to which leaf was involved. -6. The client must not contact any network endpoint that reveals which note it - is proving over. Document all network calls made during proof generation and - justify each; a note-specific query to a third-party RPC is a defect. -7. Relayer selection and submission must not create a linkage channel: document - what a relayer learns, and ensure a user can switch relayers per operation. -8. The default configuration must be the private one. No user action should be - required to obtain these privacy guarantees, and any override that weakens - them must require explicit confirmation. + population of deposits and mints and asserts that no correlation derivable + from public state identifies the true pairing better than chance across the + anonymity set. +2. **P2 must hold under test.** The equivalent test for burn-to-release + pairings. +3. No transaction argument, event, log, or account-state change on either chain + may reveal a deposit's LEZ destination or a burn's Ethereum destination. + Provide a test asserting this over full event and state diffs for a complete + round trip. +4. Information that would connect the two legs must never leave the user's + control. Document every component that handles user data, and provide a test + asserting such information is absent from all submitted transaction data. +5. Failure and error paths must not reveal which deposit or burn was involved: a + rejected claim, a repeat claim, and a cap rejection must be + indistinguishable in that respect. +6. The client must not make any network request that reveals which deposit or + burn it is acting on. Document every network call made during a + privacy-sensitive operation and justify each. +7. Where a third party submits on the user's behalf, document precisely what + that party learns, and ensure the user can switch between such parties per + operation. +8. The default configuration must be the private one. No user action may be + required to obtain the privacy guarantees, and any override that weakens them + must require explicit confirmation. ### Soft Requirements -1. **Shielded value commitments.** Replace fixed denominations with hidden - amounts via Pedersen or equivalent value commitments, range proofs, and - join-split notes, with homomorphic supply accounting on the LEZ mint - authority. This removes the denomination ladder entirely and merges all - per-rung anonymity sets into one. The note format, circuit interfaces, and - tree layout delivered under the hard requirements must be designed so this - migration does not require redeploying the vault or re-anchoring the pool; - document the intended migration path even if it is not implemented. -2. Batch verification: amortise proof verification across multiple mints or - unlocks in a single transaction, analogous to the multi-feed batching soft - requirement in RFP-020. Batching also improves privacy by making individual - operations harder to isolate. +1. **Hidden amounts.** Remove the amount-visibility constraint entirely by + concealing transferred values on the LEZ side, rather than relying on a fixed + set of permitted amounts. This merges all per-amount anonymity sets into one + and removes the need for users to split transfers. Whatever is delivered + under the hard requirements should be designed so this can be adopted later + without redeploying the vault or resetting accumulated anonymity; document the + intended migration path even if it is not implemented. +2. Batching: amortise verification cost across multiple operations in a single + transaction, analogous to the multi-feed batching soft requirement in + RFP-020. Batching also improves privacy by making individual operations + harder to isolate. 3. Optional viewing keys allowing a user to *voluntarily* disclose their own - bridge activity to a chosen third party, without weakening privacy for - anyone else and without any protocol-level disclosure capability. -4. A configurable per-token unlock delay (in addition to finality and the user's - own privacy delay) as an extra circuit-breaker window, allowing the freeze + bridge activity to a chosen third party, without weakening privacy for anyone + else and without any protocol-level disclosure capability. +4. A configurable per-token release delay, in addition to finality and any + user-chosen delay, as an extra circuit-breaker window allowing the freeze authority to react to anomalous redemption volume before funds leave the vault. 5. Support for wrapping ERC-20 tokens from additional EVM chains (e.g. Arbitrum, - Base) behind the same LEZ bridge program, reusing the registry, ladders, and - caps, with separate anchoring paths per source chain. Consider whether pools - should be shared across source chains to enlarge anonymity sets. -6. Hardware-accelerated or GPU-assisted client proving as an optional path for - users with capable hardware, without making it a requirement. -7. Design the RISC0 anchoring components as pluggable so that future zkVM - improvements, proof compression, or hardware acceleration can be integrated - without restructuring the vault, the bridge program, or the note format. + Base) behind the same LEZ bridge program, reusing the registry and caps. + Consider whether anonymity sets should be shared across source chains to + enlarge them. +6. Hardware acceleration as an optional path for users with capable machines, + without making it a requirement. +7. Design the proof-system components as pluggable, so that future zkVM + improvements, proof compression, or hardware acceleration can be adopted + without restructuring the vault or the bridge program. ### Out of Scope @@ -700,13 +544,12 @@ The following are explicitly excluded from this RFP: - Bitcoin, Monero, and Zcash bridging: these have a dedicated trustless path via atomic swaps, delivered in [RFP-003](./RFP-003-atomic-swaps.md). - Mobile and in-browser proving. Basecamp is a desktop application and is the - delivery surface for the mini-app, so the prover targets desktop only. - Proposals must not constrain circuit design to fit mobile-class resource + delivery surface for the mini-app, so any user-side proving targets desktop + only. Proposals must not constrain their design to fit mobile-class resource budgets. -- Network-level anonymity. The privacy guarantees here are properties of - on-chain state. - IP-level correlation between a user's Ethereum deposit and their relayer - submission is out of scope as an implementation concern, but must be disclosed +- Network-level anonymity. The guarantees here are properties of on-chain state. + IP-level correlation between a user's Ethereum deposit and their later LEZ + activity is out of scope as an implementation concern, but must be disclosed as residual leakage under Supportability #9. - Protocol-level compliance, disclosure, or selective-deanonymisation mechanisms. Voluntary user-held viewing keys are Soft Requirement #3; any @@ -730,9 +573,9 @@ The following are explicitly excluded from this RFP: #### Admin authority (RFP-001) The Functionality requirements specify that an admin authority registers and -deregisters supported tokens and configures denomination ladders, fee schedules -and caps. These admin-gated functions require the standardised admin authority -library from [RFP-001](./RFP-001-admin-authority-lib.md). +deregisters supported tokens and configures permitted amounts and caps. These +admin-gated functions require the standardised admin authority library from +[RFP-001](./RFP-001-admin-authority-lib.md). #### Freeze authority (RFP-002) @@ -743,36 +586,33 @@ from [RFP-002](./RFP-002-freeze-authority-lib.md). #### Token mint/burn authorities (LP-0013) -The LEZ bridge program mints wrapped tokens into private state on verified -deposits and burns them on redemption. This requires the token mint/burn -authority primitives in +The LEZ bridge program mints wrapped tokens on verified deposits and burns them +on redemption. This requires the token mint/burn authority primitives in [LP-0013](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md). -The fixed-denomination design keeps supply accounting scalar and therefore -within what LP-0013 provides; Soft Requirement #1 (shielded values) would -require homomorphic supply accounting beyond it, and proposals pursuing that -path must state what extension is needed. +Note that Soft Requirement #1 (hidden amounts) would require supply accounting +over concealed values, which is likely an extension beyond what LP-0013 +provides; proposals pursuing that path must state what extension is needed. #### Private LEZ account state -Inbound mints deliver into private LEZ state, and outbound burns spend from it. -The privacy guarantees depend on this: a mint into a public account exposes the +Wrapped tokens are minted into private LEZ state, and redemptions spend from it. +The privacy guarantees depend on this: minting into a public account exposes the recipient immediately. Proposals must state which LEZ private-state primitives they rely on and their maturity. #### RISC0 zkVM -The bridge verifies consensus proofs in-program (inbound on LEZ) and natively on -Ethereum (outbound), and generates ownership proofs client-side. This requires -RISC0, a production-ready zkVM. Proposals must leverage mature RISC0 -implementations (e.g. [Zisk](https://github.com/risc0/zisk)) rather than -building custom circuits. +The bridge verifies proofs of consensus and state in-program on LEZ and natively +on Ethereum. This requires RISC0, a production-ready zkVM. Proposals must +leverage mature RISC0 implementations (e.g. +[Zisk](https://github.com/risc0/zisk)) rather than building custom circuits. ### Soft dependencies #### Event emission (LP-0012) -Burn and anchoring events are emitted as structured on-chain events so clients -and anchoring daemons can react without polling every account. +Structured on-chain events allow clients and off-chain components to react +without polling every account. [LP-0012](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) is **closed** (delivered). @@ -782,30 +622,27 @@ Team experienced with: - Zero-knowledge proof systems and RISC0 zkVM (guest program development, proof generation and verification, public/private input handling) -- **Shielded-pool constructions**: commitment/nullifier schemes, incremental - Merkle trees, note encryption and discovery, deterministic key derivation, and - the anonymity-set analysis that goes with them +- Privacy-preserving protocol design, including anonymity-set analysis and the + ability to reason rigorously about what public state does and does not reveal - Solidity smart-contract development, including experience preparing a contract for third-party security audit, and EVM precompile integration - Cryptographic primitives (Groth16 verification, Merkle proofs, consensus verification, state root inclusion proofs) - LEZ program development, private-state programs, and on-chain proof verification -- Client-side proving on desktop targets, including packaging a prover inside a - Basecamp mini-app and a headless CLI - Smart-contract security auditing (proof validation, replay attacks, reorg - handling, cap/rate-limit bypass, privacy-leak analysis) + handling, cap bypass, privacy-leak analysis) - Cross-chain system design and integration testing (dual-chain atomic operations, finality assumptions, determinism and reproducibility) ## ⏱ Timeline Expectations Estimated software delivery duration: **16–20 weeks**. This is longer than a -transparent lock-and-mint bridge would require; the shielded-pool construction, -client-side proving targets, note discovery and recovery, the relayer layer, and -the privacy test suite are the additional scope. This excludes the -third-party audit lead time required before mainnet deployment (Supportability -#8), which is typically procured and scheduled separately. +transparent lock-and-mint bridge would require; the privacy construction, +user-side proving, position recovery, and the privacy test suite are the +additional scope. This excludes the third-party audit lead time required before +mainnet deployment (Supportability #8), which is typically procured and +scheduled separately. ## 🌍 Open Source Requirement From c53f2a42e6e585e988afbaba0a7bcbb4d03f0291 Mon Sep 17 00:00:00 2001 From: jzaki Date: Sat, 8 Aug 2026 07:07:07 +0100 Subject: [PATCH 06/69] Clarify auto-wrap from comment --- RFPs/RFP-021-wrapped-erc20.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 89158884..c5f6093f 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -283,7 +283,7 @@ Use FURPS framework. Each numbered item should be a testable statement. 1. Implement an Ethereum vault contract (Solidity) that escrows deposits of any ERC-20 in the supported-token registry, plus native ETH (auto-wrapped to - WETH). The vault must verify the actual balance delta received and reject any + WETH, ie sends ETH to the canonical WETH contract to immediately receive WETH). The vault must verify the actual balance delta received and reject any deposit that does not deliver the expected amount. 2. A deposit must not publish, store, or otherwise reveal its LEZ destination. No Ethereum transaction argument, event, or contract state may identify the From 70189e50fcff3a354bf3c78bc3a19182c7e36050 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:01:56 +1000 Subject: [PATCH 07/69] RFP-021: remove prose em-dashes and an unsupported intensifier Project style avoids em-dashes and punctuation hyphens in prose; replace the ones in body text with commas, colons, or parentheses depending on the clause (title-line and Resources-list separators are an unrelated repo-wide convention and are left as-is). Also drop the bare "Crucially," opener in the Overview, which asserts importance without adding information. Reformatted with mdformat per repo convention. --- RFPs/RFP-021-wrapped-erc20.md | 228 +++++++++++++++++----------------- 1 file changed, 114 insertions(+), 114 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index c5f6093f..3bf0a034 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -53,20 +53,20 @@ tokens (and native ETH, wrapped as WETH) held on Ethereum enter LEZ as canonical wrapped assets, and exit back to Ethereum on redemption. An Ethereum-side vault contract escrows deposits. A LEZ-side program mints the -corresponding wrapped token once it has cryptographically verified — with no -trusted intermediary — that the deposit really happened on Ethereum. Redemption +corresponding wrapped token once it has cryptographically verified, with no +trusted intermediary, that the deposit really happened on Ethereum. Redemption reverses the flow: burning the wrapped token on LEZ entitles the holder to release the original ERC-20 from the vault, again on cryptographic proof alone. Verification rests on RISC0 zero-knowledge proofs of consensus and state, verified in-program on LEZ and via a native precompile on Ethereum. -Crucially, the bridge must achieve this **without letting a public observer -connect a specific Ethereum deposit to the LEZ mint it funded, or a specific LEZ -burn to the Ethereum release it triggered.** That privacy property is a hard -requirement of the same standing as solvency, and it shapes the whole design: -the deposit cannot name its LEZ destination, the burn cannot name its Ethereum -destination, and no component other than the user may hold the information that -connects them. +The bridge must achieve this **without letting a public observer connect a +specific Ethereum deposit to the LEZ mint it funded, or a specific LEZ burn to +the Ethereum release it triggered.** That privacy property is a hard requirement +of the same standing as solvency, and it shapes the whole design: the deposit +cannot name its LEZ destination, the burn cannot name its Ethereum destination, +and no component other than the user may hold the information that connects +them. Teams will need experience with zero-knowledge proof systems, privacy-preserving protocol design, Solidity smart-contract development, and LEZ program @@ -78,19 +78,18 @@ LEZ DeFi cannot function without external collateral. The lending protocol ([RFP-008](./RFP-008-lending-borrowing-protocol.md)), the reflexive stablecoin ([RFP-013](./RFP-013-reflexive-stablecoin-protocol.md)), and the on-chain TWAP oracle's own design ([RFP-019](./RFP-019-twap-oracle.md)) all assume wrapped -external assets — wBTC, wETH, wXMR, wZEC — are already available as LEZ tokens. +external assets (wBTC, wETH, wXMR, wZEC) are already available as LEZ tokens. None of those RFPs specify how a token actually gets wrapped; this RFP is that missing primitive for the Ethereum leg (Bitcoin, Monero, and Zcash have their -own trustless path via atomic swaps in -[RFP-003](./RFP-003-atomic-swaps.md)). +own trustless path via atomic swaps in [RFP-003](./RFP-003-atomic-swaps.md)). RFP-003 explicitly carved Ethereum out of its scope for exactly this reason: "ETH is expected to reach LEZ via wrapping, which requires no swap counterparty and is a much simpler construction." Bitcoin, Monero, and Zcash lack general smart-contract expressiveness, so a trustless swap protocol is the only -construction available for them. Ethereum's programmability makes a lock-and-mint -bridge with a vault contract and zero-knowledge proof verification possible -instead. +construction available for them. Ethereum's programmability makes a +lock-and-mint bridge with a vault contract and zero-knowledge proof verification +possible instead. ### A transparent bridge would deanonymise the whole chain @@ -104,10 +103,10 @@ virtually all external collateral would enter LEZ through this one primitive, such a bridge becomes the canonical deanonymisation oracle for the entire chain: an observer needs only to scrape one Ethereum contract's logs to build an identity map covering most of LEZ's collateral base. Every downstream privacy -feature — private accounts, the privacy-preserving DEX -([RFP-004](./RFP-004-privacy-preserving-dex.md)), shielded lending positions — is -undermined at the point of entry, no matter how well those components protect -data internally. Privacy that leaks at the on-ramp is not privacy. +feature is undermined at the point of entry, no matter how well those components +protect data internally: private accounts, the privacy-preserving DEX +([RFP-004](./RFP-004-privacy-preserving-dex.md)), shielded lending positions. +Privacy that leaks at the on-ramp is not privacy. The redemption leg is symmetric and, if anything, worse: a burn naming its Ethereum destination publishes the exit address alongside the LEZ account that @@ -126,9 +125,9 @@ collateral base at launch. Bridges are also the most attacked category of infrastructure in DeFi: Chainalysis has tracked more than $2.8B stolen from cross-chain bridges since 2022, the highest-value class of exploit in the industry. This RFP's security -posture — cryptographic verification eliminating the trust-in-signers vector +posture (cryptographic verification eliminating the trust-in-signers vector entirely, combined with per-token and global caps and an admin-governed freeze -authority — is designed directly against that track record. +authority) is designed directly against that track record. ## 🏗 Design Rationale @@ -153,10 +152,10 @@ set is therefore a first-class requirement, not an implementation detail. Two facts are fixed by the environment and cannot be designed away. Proposals must not claim otherwise: -1. **The Ethereum deposit amount is public**, as is the depositor's address — - it is an ordinary ERC-20 transfer into the vault, sent by the depositor. -2. **The Ethereum release amount and recipient are public** — the vault must - move real tokens to a real address. +1. **The Ethereum deposit amount is public**, as is the depositor's address: it + is an ordinary ERC-20 transfer into the vault, sent by the depositor. +2. **The Ethereum release amount and recipient are public**: the vault must move + real tokens to a real address. Privacy is therefore preserved by making these public facts *uninformative about which counterparty they pair with*, not by attempting to hide them. Three @@ -182,9 +181,9 @@ A commitment-and-nullifier shielded pool on each leg is the well-understood construction for this problem: the deposit publishes a commitment rather than a destination, and the claimant later proves entitlement without revealing which deposit they are claiming, with a nullifier preventing double-claims. The -redemption leg works the same way in reverse, which requires splitting redemption -into two separately-timed stages so that the burn need not name its Ethereum -destination. +redemption leg works the same way in reverse, which requires splitting +redemption into two separately-timed stages so that the burn need not name its +Ethereum destination. Minting into **private LEZ state** is the natural fit for the destination side, and keeps the recipient and balance off public view without additional @@ -195,9 +194,9 @@ per-token denominations is the simpler and better-understood option, and is the expected baseline for this RFP; hiding amounts outright via value commitments is stronger but considerably heavier, and is specified as a soft requirement below. -For the fee-payer problem, permissionless relayers paid out of the bridged amount -are the conventional answer, with the destination bound into the proof so a -relayer cannot redirect funds or overcharge. +For the fee-payer problem, permissionless relayers paid out of the bridged +amount are the conventional answer, with the destination bound into the proof so +a relayer cannot redirect funds or overcharge. For the trust problem, note that a proof of source-chain consensus and state contains no user-specific data, so it can be produced by anyone and anchored @@ -213,7 +212,7 @@ attestor federations, relayers, or proof-generation services. A user relies only on the correctness of the proof system, the security of the Ethereum network, and the security of the LEZ network. -Any off-chain participant in the design may be trusted for **liveness only** — +Any off-chain participant in the design may be trusted for **liveness only**: able to decline service, but never able to steal, redirect, forge, censor selectively, or deanonymise. Proposals must identify every such participant and justify that each is liveness-only. @@ -268,10 +267,10 @@ This RFP does not mandate a specific protocol fee rate. Proposals must specify who pays, when fees are collected, the exact rate, and where fees are routed. A governance-activatable fee switch with an initial zero rate, gated by the admin authority per RFP-001, is the recommended baseline, consistent with the pattern -used elsewhere in the Logos RFP set (see -[RFP-017](./RFP-017-token-vesting.md), "Fee structure"). Any fee paid by a user — -protocol or relayer — must take a value that does not distinguish their -transaction from others, since a distinctive fee is itself a fingerprint. +used elsewhere in the Logos RFP set (see [RFP-017](./RFP-017-token-vesting.md), +"Fee structure"). Any fee paid by a user (protocol or relayer) must take a value +that does not distinguish their transaction from others, since a distinctive fee +is itself a fingerprint. ## ✅ Scope of Work @@ -281,40 +280,41 @@ Use FURPS framework. Each numbered item should be a testable statement. #### Functionality -1. Implement an Ethereum vault contract (Solidity) that escrows deposits of any - ERC-20 in the supported-token registry, plus native ETH (auto-wrapped to - WETH, ie sends ETH to the canonical WETH contract to immediately receive WETH). The vault must verify the actual balance delta received and reject any - deposit that does not deliver the expected amount. -2. A deposit must not publish, store, or otherwise reveal its LEZ destination. - No Ethereum transaction argument, event, or contract state may identify the - account that will receive the wrapped tokens. -3. Implement a LEZ bridge program that mints the corresponding wrapped token on - cryptographic verification of a valid Ethereum deposit, using RISC0 proofs of - Ethereum consensus and state verified in-program. Verification must require - no trusted party. -4. Wrapped tokens are minted into private LEZ state by default, so that neither - the recipient nor the balance is publicly visible. -5. Each deposit may be claimed at most once. A repeat claim must be rejected - deterministically, without minting, and without revealing which deposit it - referred to. -6. Implement a burn path on the LEZ bridge program that entitles the holder to - release the original asset from the Ethereum vault. The burn must not - publish, store, or otherwise reveal its Ethereum destination. -7. The Ethereum vault releases the original ERC-20 (or unwrapped ETH, for WETH - redemptions) on cryptographic verification of a valid LEZ burn, using a RISC0 - proof verified natively via a precompile (Groth16 verifier or equivalent). - Each burn may be redeemed at most once. -8. The amounts visible on Ethereum must not identify which mint or burn they - correspond to. Proposals must state the mechanism chosen (fixed - denominations are the expected baseline) and its effect on anonymity-set - size. -9. A user must be able to complete both flows without holding a funded account - on either chain, and whoever submits or pays for a transaction on the user's - behalf must not thereby learn, or be able to prove, which deposit or burn it - corresponds to. That party must not be able to alter the destination or take - more than an agreed fee. -10. A user must be able to recover their full bridge position — every claimable - deposit and every unredeemed burn — from credentials they already hold, with +01. Implement an Ethereum vault contract (Solidity) that escrows deposits of any + ERC-20 in the supported-token registry, plus native ETH (auto-wrapped to + WETH, ie sends ETH to the canonical WETH contract to immediately receive + WETH). The vault must verify the actual balance delta received and reject + any deposit that does not deliver the expected amount. +02. A deposit must not publish, store, or otherwise reveal its LEZ destination. + No Ethereum transaction argument, event, or contract state may identify the + account that will receive the wrapped tokens. +03. Implement a LEZ bridge program that mints the corresponding wrapped token on + cryptographic verification of a valid Ethereum deposit, using RISC0 proofs + of Ethereum consensus and state verified in-program. Verification must + require no trusted party. +04. Wrapped tokens are minted into private LEZ state by default, so that neither + the recipient nor the balance is publicly visible. +05. Each deposit may be claimed at most once. A repeat claim must be rejected + deterministically, without minting, and without revealing which deposit it + referred to. +06. Implement a burn path on the LEZ bridge program that entitles the holder to + release the original asset from the Ethereum vault. The burn must not + publish, store, or otherwise reveal its Ethereum destination. +07. The Ethereum vault releases the original ERC-20 (or unwrapped ETH, for WETH + redemptions) on cryptographic verification of a valid LEZ burn, using a + RISC0 proof verified natively via a precompile (Groth16 verifier or + equivalent). Each burn may be redeemed at most once. +08. The amounts visible on Ethereum must not identify which mint or burn they + correspond to. Proposals must state the mechanism chosen (fixed + denominations are the expected baseline) and its effect on anonymity-set + size. +09. A user must be able to complete both flows without holding a funded account + on either chain, and whoever submits or pays for a transaction on the user's + behalf must not thereby learn, or be able to prove, which deposit or burn it + corresponds to. That party must not be able to alter the destination or take + more than an agreed fee. +10. A user must be able to recover their full bridge position (every claimable + deposit and every unredeemed burn) from credentials they already hold, with no dependence on any server-side index and no separately-backed-up secret generated during the flow. 11. An admin authority (per RFP-001, integrated via the SPEL framework where @@ -408,47 +408,47 @@ Use FURPS framework. Each numbered item should be a testable statement. latency (burn to Ethereum release), each broken down by source-chain finality wait, proof generation, any privacy-motivated delay, and on-chain verification. -6. Document the compute resources (CPU, RAM, time) required to run any - off-chain component the design requires. +6. Document the compute resources (CPU, RAM, time) required to run any off-chain + component the design requires. 7. Document the growth rate and on-chain storage cost of all bridge state that accumulates with usage, with projections at 1M and 10M operations. #### Supportability -1. The Ethereum vault contract and the LEZ bridge program are deployed and - tested on a public Ethereum testnet and LEZ devnet/testnet respectively. -2. End-to-end integration tests exercise the full deposit and redemption round - trip against a LEZ sequencer (standalone mode) and an Ethereum test network - or local fork, and are included in CI. CI must be green on the default - branch. -3. Every hard requirement in Functionality, Usability, Reliability, Performance, - and Privacy Preservation has at least one corresponding test. -4. A README documents end-to-end usage: contract and program addresses, - deployment steps for both chains, and step-by-step instructions for - depositing and redeeming via CLI and mini-app. -5. Submit a - [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for the SDK, covering the developer integration journey for both flows - including position recovery. -6. Submit a - [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for the CLI and any operator-facing components, covering the core user and - operator journeys respectively. -7. Provide Figma designs or equivalent for all mini-app GUI artefacts, including - the anonymity-set disclosure and the recovery flow. -8. The Ethereum vault contract undergoes an independent third-party - smart-contract security audit before mainnet deployment; the audit report (or - a summary, if the full report is not publishable) must be linked from the - README. This requirement exists because cross-chain bridges are the single - most-attacked category of DeFi infrastructure (Chainalysis has tracked more - than $2.8B stolen from bridges since 2022); it is not optional. -9. Provide a **privacy properties document** covering: a formal statement of P1 - and P2 and the anonymity set each is measured against; exactly what is - visible on-chain at every step on both chains; what an adversary observing - all public state can and cannot infer; what every off-chain participant in - the design can observe; residual leakage from timing, amount selection, fee - payment, network metadata and usage patterns; and the conditions under which - the guarantees degrade or fail. +01. The Ethereum vault contract and the LEZ bridge program are deployed and + tested on a public Ethereum testnet and LEZ devnet/testnet respectively. +02. End-to-end integration tests exercise the full deposit and redemption round + trip against a LEZ sequencer (standalone mode) and an Ethereum test network + or local fork, and are included in CI. CI must be green on the default + branch. +03. Every hard requirement in Functionality, Usability, Reliability, + Performance, and Privacy Preservation has at least one corresponding test. +04. A README documents end-to-end usage: contract and program addresses, + deployment steps for both chains, and step-by-step instructions for + depositing and redeeming via CLI and mini-app. +05. Submit a + [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) + for the SDK, covering the developer integration journey for both flows + including position recovery. +06. Submit a + [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) + for the CLI and any operator-facing components, covering the core user and + operator journeys respectively. +07. Provide Figma designs or equivalent for all mini-app GUI artefacts, + including the anonymity-set disclosure and the recovery flow. +08. The Ethereum vault contract undergoes an independent third-party + smart-contract security audit before mainnet deployment; the audit report + (or a summary, if the full report is not publishable) must be linked from + the README. This requirement exists because cross-chain bridges are the + single most-attacked category of DeFi infrastructure (Chainalysis has + tracked more than $2.8B stolen from bridges since 2022); it is not optional. +09. Provide a **privacy properties document** covering: a formal statement of P1 + and P2 and the anonymity set each is measured against; exactly what is + visible on-chain at every step on both chains; what an adversary observing + all public state can and cannot infer; what every off-chain participant in + the design can observe; residual leakage from timing, amount selection, fee + payment, network metadata and usage patterns; and the conditions under which + the guarantees degrade or fail. 10. Document the anonymity-set growth model: expected set size over time at projected volumes, the minimum below which the guarantees are considered not to hold, and guidance for users bridging before the pool has matured. @@ -494,8 +494,8 @@ Use FURPS framework. Each numbered item should be a testable statement. control. Document every component that handles user data, and provide a test asserting such information is absent from all submitted transaction data. 5. Failure and error paths must not reveal which deposit or burn was involved: a - rejected claim, a repeat claim, and a cap rejection must be - indistinguishable in that respect. + rejected claim, a repeat claim, and a cap rejection must be indistinguishable + in that respect. 6. The client must not make any network request that reveals which deposit or burn it is acting on. Document every network call made during a privacy-sensitive operation and justify each. @@ -513,8 +513,8 @@ Use FURPS framework. Each numbered item should be a testable statement. set of permitted amounts. This merges all per-amount anonymity sets into one and removes the need for users to split transfers. Whatever is delivered under the hard requirements should be designed so this can be adopted later - without redeploying the vault or resetting accumulated anonymity; document the - intended migration path even if it is not implemented. + without redeploying the vault or resetting accumulated anonymity; document + the intended migration path even if it is not implemented. 2. Batching: amortise verification cost across multiple operations in a single transaction, analogous to the multi-feed batching soft requirement in RFP-020. Batching also improves privacy by making individual operations @@ -562,9 +562,8 @@ The following are explicitly excluded from this RFP: future RISC0 versions or alternative systems become preferable, that is a candidate for a future update or new RFP. - Price feeds for wrapped assets. Once a token is wrapped, pricing it is the - responsibility of the oracle stack - ([RFP-019](./RFP-019-twap-oracle.md), [RFP-020](./RFP-020-redstone-oracle-adaptor.md)), - not this bridge. + responsibility of the oracle stack ([RFP-019](./RFP-019-twap-oracle.md), + [RFP-020](./RFP-020-redstone-oracle-adaptor.md)), not this bridge. ## ⚠ Platform Dependencies @@ -667,7 +666,8 @@ All code must be released under the **MIT+Apache2.0 dual License**. - [LP-0012: Event/Log mechanism for LEZ](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) - [LP-0013: Token program improvements: mint authorities](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md) - [RISC0 — Zero-Knowledge VM](https://github.com/risc0/risc0) -- [Zisk — RISC0 Proof Generation](https://github.com/risc0/zisk) (reference implementation for proof generation) +- [Zisk — RISC0 Proof Generation](https://github.com/risc0/zisk) (reference + implementation for proof generation) - [Chainalysis — Cross-Chain Bridge Hacks](https://www.chainalysis.com/blog/cross-chain-bridge-hacks-2022/) (bridge-hack loss data) From bebf0aa034e075691d12d2148e07f07c387ce56f Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:02:43 +1000 Subject: [PATCH 08/69] RFP-021: remove RISC0 implementation detail from Overview The Overview stated verification "rests on RISC0 zero-knowledge proofs of consensus and state, verified in-program on LEZ and via a native precompile on Ethereum." This RFP should specify the required outcome (trustless cryptographic verification) and not dictate the specific proof system or verification mechanism teams must use to achieve it. --- RFPs/RFP-021-wrapped-erc20.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 3bf0a034..cb87d8b6 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -57,8 +57,6 @@ corresponding wrapped token once it has cryptographically verified, with no trusted intermediary, that the deposit really happened on Ethereum. Redemption reverses the flow: burning the wrapped token on LEZ entitles the holder to release the original ERC-20 from the vault, again on cryptographic proof alone. -Verification rests on RISC0 zero-knowledge proofs of consensus and state, -verified in-program on LEZ and via a native precompile on Ethereum. The bridge must achieve this **without letting a public observer connect a specific Ethereum deposit to the LEZ mint it funded, or a specific LEZ burn to From 9a9ab6af272b161f491763d79f833c75484cca74 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:04:51 +1000 Subject: [PATCH 09/69] RFP-021: correct framing of atomic swaps vs wrapping Both references to RFP-003 described atomic swaps as a "trustless path" or "bridging" mechanism parallel to wrapping, which is inaccurate: atomic swaps trade assets directly and never mint a wrapped representation on LEZ. Rephrase both mentions (Why This Matters, Out of Scope) to describe atomic swaps as the liquidity route for BTC/XMR/ZEC, distinct in kind from the wrapped-token primitive this RFP defines for ETH/ERC-20. --- RFPs/RFP-021-wrapped-erc20.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index cb87d8b6..e9a9dc67 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -78,8 +78,9 @@ LEZ DeFi cannot function without external collateral. The lending protocol oracle's own design ([RFP-019](./RFP-019-twap-oracle.md)) all assume wrapped external assets (wBTC, wETH, wXMR, wZEC) are already available as LEZ tokens. None of those RFPs specify how a token actually gets wrapped; this RFP is that -missing primitive for the Ethereum leg (Bitcoin, Monero, and Zcash have their -own trustless path via atomic swaps in [RFP-003](./RFP-003-atomic-swaps.md)). +missing primitive for the Ethereum leg. Bitcoin, Monero, and Zcash reach LEZ +liquidity through a different route: direct, trustless swaps against LEZ assets +via [RFP-003](./RFP-003-atomic-swaps.md), rather than a wrapped representation. RFP-003 explicitly carved Ethereum out of its scope for exactly this reason: "ETH is expected to reach LEZ via wrapping, which requires no swap counterparty @@ -539,8 +540,9 @@ Use FURPS framework. Each numbered item should be a testable statement. The following are explicitly excluded from this RFP: - Wrapping non-fungible assets (ERC-721, ERC-1155). -- Bitcoin, Monero, and Zcash bridging: these have a dedicated trustless path via - atomic swaps, delivered in [RFP-003](./RFP-003-atomic-swaps.md). +- Bitcoin, Monero, and Zcash liquidity: these reach LEZ via direct, trustless + swaps against LEZ assets, delivered in [RFP-003](./RFP-003-atomic-swaps.md), + not via a wrapped representation. - Mobile and in-browser proving. Basecamp is a desktop application and is the delivery surface for the mini-app, so any user-side proving targets desktop only. Proposals must not constrain their design to fit mobile-class resource From 705352ffad4dfa8d616818f3a63ad909abb426b9 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:06:34 +1000 Subject: [PATCH 10/69] RFP-021: state the actual reasons wrapping beats atomic swaps for ETH Addresses review comment https://github.com/logos-co/rfp/pull/158/changes#r3733249831. The previous text quoted RFP-003's unexplained claim that wrapping "is a much simpler construction" without saying why. State the real reasons directly: atomic swaps require an online counterparty, so wrapping is non-interactive; wrapping needs no added infrastructure (counterparty matching); and wrapping produces a genuine LEZ-native token, not just a trade, which is what lets it be composed with AMMs, lending markets, and other DeFi programs. --- RFPs/RFP-021-wrapped-erc20.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index e9a9dc67..937aee12 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -82,13 +82,18 @@ missing primitive for the Ethereum leg. Bitcoin, Monero, and Zcash reach LEZ liquidity through a different route: direct, trustless swaps against LEZ assets via [RFP-003](./RFP-003-atomic-swaps.md), rather than a wrapped representation. -RFP-003 explicitly carved Ethereum out of its scope for exactly this reason: -"ETH is expected to reach LEZ via wrapping, which requires no swap counterparty -and is a much simpler construction." Bitcoin, Monero, and Zcash lack general -smart-contract expressiveness, so a trustless swap protocol is the only -construction available for them. Ethereum's programmability makes a -lock-and-mint bridge with a vault contract and zero-knowledge proof verification -possible instead. +RFP-003 explicitly carved Ethereum out of its scope for this reason. Bitcoin, +Monero, and Zcash lack general smart-contract expressiveness, so a trustless +swap protocol, which needs a counterparty online at the same time to complete +the trade, is the only construction available for them. Ethereum's +programmability makes a wrapping bridge possible instead, and wrapping is the +better choice on every count that matters here: a deposit does not need a +counterparty to be online, so the exchange is non-interactive; it needs no +additional infrastructure such as a market of counterparties or order matching; +and unlike a swap, which merely trades an external asset for one already on LEZ, +wrapping creates a genuine LEZ-native representation of the external asset +itself, which is what lets it be deposited into an AMM pool, posted as loan +collateral, or otherwise composed with LEZ DeFi programs directly. ### A transparent bridge would deanonymise the whole chain From 4eca8dd5f9c2bb1504b21b76871a50861704afd3 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:19:22 +1000 Subject: [PATCH 11/69] RFP-021: ground Why This Matters in LEZ architecture and sovereignty The opening claimed LEZ DeFi "cannot function" without external collateral and called this RFP a "missing primitive", an overstated framing led by a list of dependent RFPs rather than by why the bridge is needed. Replace with the actual motivation: LEZ's separated public/private state architecture and programmability make private DeFi possible, and bringing in assets from non-private chains like Ethereum has to preserve Logos' sovereignty principle, no custodian, signer, or federation trusted along the way. The dependent-RFP list and the wrapping-vs-swaps comparison remain as supporting detail underneath that framing. --- RFPs/RFP-021-wrapped-erc20.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 937aee12..f308fdc3 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -72,15 +72,22 @@ development. ## 🔥 Why This Matters -LEZ DeFi cannot function without external collateral. The lending protocol -([RFP-008](./RFP-008-lending-borrowing-protocol.md)), the reflexive stablecoin -([RFP-013](./RFP-013-reflexive-stablecoin-protocol.md)), and the on-chain TWAP -oracle's own design ([RFP-019](./RFP-019-twap-oracle.md)) all assume wrapped -external assets (wBTC, wETH, wXMR, wZEC) are already available as LEZ tokens. -None of those RFPs specify how a token actually gets wrapped; this RFP is that -missing primitive for the Ethereum leg. Bitcoin, Monero, and Zcash reach LEZ -liquidity through a different route: direct, trustless swaps against LEZ assets -via [RFP-003](./RFP-003-atomic-swaps.md), rather than a wrapped representation. +Thanks to LEZ's separated public/private state architecture and programmability, +private DeFi is possible with privacy guarantees at both the execution layer and +the underlying consensus layer. To let users move assets in from non-private +blockchains such as Ethereum, that move has to happen while preserving Logos' +principle of sovereignty: no custodian, signer, or federation should be trusted +with a user's assets or identity along the way. + +The lending protocol ([RFP-008](./RFP-008-lending-borrowing-protocol.md)), the +reflexive stablecoin ([RFP-013](./RFP-013-reflexive-stablecoin-protocol.md)), +and the on-chain TWAP oracle's own design ([RFP-019](./RFP-019-twap-oracle.md)) +all assume wrapped external assets (wBTC, wETH, wXMR, wZEC) are already +available as LEZ tokens. None of those RFPs specify how a token actually gets +wrapped; this RFP is that primitive for the Ethereum leg. Bitcoin, Monero, and +Zcash reach LEZ liquidity through a different route: direct, trustless swaps +against LEZ assets via [RFP-003](./RFP-003-atomic-swaps.md), rather than a +wrapped representation. RFP-003 explicitly carved Ethereum out of its scope for this reason. Bitcoin, Monero, and Zcash lack general smart-contract expressiveness, so a trustless From 680d68fba667cffa661e96fe55cd4aa51e094cbb Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:22:52 +1000 Subject: [PATCH 12/69] RFP-021: reframe DeFi paragraph as enablement, not gap-filling The paragraph was structured around what other RFPs "assume" and "don't specify", an indirect, gatekeeping way to make the point. State it directly instead: wrapped tokens are what let users bring Ethereum assets into LEZ's private DeFi, and list the RFPs that DeFi comprises (DEX, lending, stablecoin, and the price feeds that collateralise them), this RFP is the wrapping primitive that feeds all of them. --- RFPs/RFP-021-wrapped-erc20.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index f308fdc3..60999ef3 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -79,15 +79,16 @@ blockchains such as Ethereum, that move has to happen while preserving Logos' principle of sovereignty: no custodian, signer, or federation should be trusted with a user's assets or identity along the way. -The lending protocol ([RFP-008](./RFP-008-lending-borrowing-protocol.md)), the -reflexive stablecoin ([RFP-013](./RFP-013-reflexive-stablecoin-protocol.md)), -and the on-chain TWAP oracle's own design ([RFP-019](./RFP-019-twap-oracle.md)) -all assume wrapped external assets (wBTC, wETH, wXMR, wZEC) are already -available as LEZ tokens. None of those RFPs specify how a token actually gets -wrapped; this RFP is that primitive for the Ethereum leg. Bitcoin, Monero, and -Zcash reach LEZ liquidity through a different route: direct, trustless swaps -against LEZ assets via [RFP-003](./RFP-003-atomic-swaps.md), rather than a -wrapped representation. +Wrapped tokens are what let users bring assets they already hold on Ethereum +into that private DeFi: the privacy-preserving DEX +([RFP-004](./RFP-004-privacy-preserving-dex.md)), the lending protocol +([RFP-008](./RFP-008-lending-borrowing-protocol.md)), the reflexive stablecoin +([RFP-013](./RFP-013-reflexive-stablecoin-protocol.md)), and the price feeds +that collateralise them ([RFP-019](./RFP-019-twap-oracle.md), +[RFP-020](./RFP-020-redstone-oracle-adaptor.md)). This RFP delivers that +wrapping primitive for the Ethereum leg. Bitcoin, Monero, and Zcash reach LEZ +liquidity through a different route: direct, trustless swaps against LEZ assets +via [RFP-003](./RFP-003-atomic-swaps.md), rather than a wrapped representation. RFP-003 explicitly carved Ethereum out of its scope for this reason. Bitcoin, Monero, and Zcash lack general smart-contract expressiveness, so a trustless From ab59cf89392e2e7b529f0295b28fe5ba548e84e2 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:23:18 +1000 Subject: [PATCH 13/69] RFP-021: note wrapped assets carry existing value into collateral use Make explicit that wrapped tokens bring not just the asset but its already-established market value into LEZ DeFi, usable directly or posted as collateral, since that value transfer is the actual point of wrapping rather than just moving a token between chains. --- RFPs/RFP-021-wrapped-erc20.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 60999ef3..548ff219 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -79,8 +79,9 @@ blockchains such as Ethereum, that move has to happen while preserving Logos' principle of sovereignty: no custodian, signer, or federation should be trusted with a user's assets or identity along the way. -Wrapped tokens are what let users bring assets they already hold on Ethereum -into that private DeFi: the privacy-preserving DEX +Wrapped tokens are what let users bring assets they already hold, and whose +value is already established, on Ethereum into that private DeFi, spending them +there directly or posting them as collateral: the privacy-preserving DEX ([RFP-004](./RFP-004-privacy-preserving-dex.md)), the lending protocol ([RFP-008](./RFP-008-lending-borrowing-protocol.md)), the reflexive stablecoin ([RFP-013](./RFP-013-reflexive-stablecoin-protocol.md)), and the price feeds From 8920a03124585803f820ce00132c16b5cda64dee Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:35:11 +1000 Subject: [PATCH 14/69] RFP-021: privacy is maximised and documented, not an absolute guarantee Replace "A transparent bridge would deanonymise the whole chain" with a section that states the actual expectation: the applicant must consider and document a strategy for reducing linkability between Ethereum and LEZ events, and where a specific form of linkability can't be avoided, document why and what residual correlation remains. The prior framing asserted unlinkability as a hard requirement "of the same standing as solvency", which overstates what a bridge touching a public chain can actually guarantee. Soften the matching Overview paragraph to the same effect so the two sections don't contradict each other. --- RFPs/RFP-021-wrapped-erc20.md | 52 ++++++++++++++++------------------- 1 file changed, 24 insertions(+), 28 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 548ff219..f7a1ca08 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -58,13 +58,14 @@ trusted intermediary, that the deposit really happened on Ethereum. Redemption reverses the flow: burning the wrapped token on LEZ entitles the holder to release the original ERC-20 from the vault, again on cryptographic proof alone. -The bridge must achieve this **without letting a public observer connect a -specific Ethereum deposit to the LEZ mint it funded, or a specific LEZ burn to -the Ethereum release it triggered.** That privacy property is a hard requirement -of the same standing as solvency, and it shapes the whole design: the deposit -cannot name its LEZ destination, the burn cannot name its Ethereum destination, -and no component other than the user may hold the information that connects -them. +The bridge must **maximise privacy on both legs, minimising the linkability +between a specific Ethereum deposit and the LEZ mint it funded, or between a +specific LEZ burn and the Ethereum release it triggered.** This shapes the +design: the deposit should not name its LEZ destination, the burn should not +name its Ethereum destination, and information that would connect them should +stay with the user wherever the design permits it. Where a specific form of +linkability cannot be avoided, the proposal must document why and what residual +correlation results. Teams will need experience with zero-knowledge proof systems, privacy-preserving protocol design, Solidity smart-contract development, and LEZ program @@ -104,27 +105,22 @@ wrapping creates a genuine LEZ-native representation of the external asset itself, which is what lets it be deposited into an AMM pool, posted as loan collateral, or otherwise composed with LEZ DeFi programs directly. -### A transparent bridge would deanonymise the whole chain - -Privacy is not a nice-to-have here; it is the difference between this bridge -strengthening LEZ's privacy guarantees and silently destroying them. - -A conventional lock-and-mint bridge publishes a deposit event naming both the -Ethereum depositor and the LEZ recipient. That single event permanently binds a -traceable Ethereum address to a LEZ account, for anyone to read. Because -virtually all external collateral would enter LEZ through this one primitive, -such a bridge becomes the canonical deanonymisation oracle for the entire chain: -an observer needs only to scrape one Ethereum contract's logs to build an -identity map covering most of LEZ's collateral base. Every downstream privacy -feature is undermined at the point of entry, no matter how well those components -protect data internally: private accounts, the privacy-preserving DEX -([RFP-004](./RFP-004-privacy-preserving-dex.md)), shielded lending positions. -Privacy that leaks at the on-ramp is not privacy. - -The redemption leg is symmetric and, if anything, worse: a burn naming its -Ethereum destination publishes the exit address alongside the LEZ account that -funded it, closing the loop and connecting a user's entire LEZ activity to their -Ethereum identity at both ends. +### Minimising linkability between Ethereum and LEZ events + +Privacy is baked into LEZ, and this bridge should maximise privacy where it +touches a non-private chain. Ethereum is public: the deposit and the release it +eventually triggers are visible to anyone. A conventional lock-and-mint bridge +adds to that a deposit event naming both the Ethereum depositor and the LEZ +recipient, and a redemption event naming the Ethereum destination alongside the +LEZ account that funded it, each permanently binding a traceable Ethereum +identity to LEZ activity for anyone to read. + +The applicant must consider and document the bridge's strategy for reducing +linkability between an Ethereum deposit and the LEZ mint it funds, and between a +LEZ burn and the Ethereum release it triggers. Where a specific form of +linkability cannot be avoided, given what a lock-and-mint bridge to a public +chain necessarily reveals, the applicant must document why, and what residual +correlation an observer is left with as a result. ### Stablecoins are the concrete prize From ba98b4b91aea5717b37d20a7893edd1c47b4567c Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:36:19 +1000 Subject: [PATCH 15/69] RFP-021: scope P1/P2 unlinkability to exclude amount, token, timing P1 and P2 previously claimed the adversary "cannot determine" the true pairing at all, contradicted a few paragraphs later by "What cannot be hidden", which correctly states that amount and timing are visible on Ethereum and do correlate. The Privacy Preservation hard requirements inherited the same overstatement ("no correlation... better than chance"). Narrow the hard requirement to what the bridge can actually guarantee: no information other than amount, token, and timing may link an Ethereum event to its LEZ counterpart. Update the P1/P2 definitions and their test requirements to match, and cross-reference the amount mitigation already specified (fixed denominations, Soft Requirement 1). --- RFPs/RFP-021-wrapped-erc20.md | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index f7a1ca08..2a037d66 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -142,19 +142,31 @@ authority) is designed directly against that track record. ### The privacy requirement, stated precisely -Two properties must hold against an adversary who observes **all** public state -on both chains, indefinitely, and who may themselves deposit and redeem: +Amount, token, and timing are not designed away: they are visible on Ethereum by +construction (see "What cannot be hidden" below), and a design that claimed +otherwise would be wrong. The hard requirement is narrower and precise about +what it covers: **no information other than amount, token, and timing may enable +an adversary to link an Ethereum deposit to the LEZ mint it funded, or a LEZ +burn to the Ethereum release it triggered.** + +Stated against an adversary who observes **all** public state on both chains, +indefinitely, and who may themselves deposit and redeem: - **P1 (inbound).** Given an Ethereum deposit, the adversary cannot determine - which LEZ mint it funded, with probability better than uniform over the - inbound anonymity set. + which LEZ mint it funded using any signal other than amount, token, and + timing, with probability better than uniform over the set of candidate mints + those three signals leave unresolved. - **P2 (outbound).** Given a LEZ burn, the adversary cannot determine which - Ethereum release it triggered, with probability better than uniform over the - outbound anonymity set. + Ethereum release it triggered using any signal other than amount, token, and + timing, with probability better than uniform over the set of candidate + releases those three signals leave unresolved. -Both properties are stated relative to an *anonymity set*, and both degrade to -nothing when that set is small. Sizing, measuring and surfacing the anonymity -set is therefore a first-class requirement, not an implementation detail. +Both properties are stated relative to an *anonymity set*, the set of candidates +amount, token, and timing do not already narrow down, and both degrade to +nothing when that set is small. Sizing, measuring, and surfacing the anonymity +set is therefore a first-class requirement, not an implementation detail; so is +minimising how far amount and timing narrow it in the first place (see "What +cannot be hidden" below and Soft Requirement 1, Hidden amounts). ### What cannot be hidden @@ -491,8 +503,9 @@ Use FURPS framework. Each numbered item should be a testable statement. 1. **P1 must hold under test.** Provide an automated test that constructs a population of deposits and mints and asserts that no correlation derivable - from public state identifies the true pairing better than chance across the - anonymity set. + from public state, other than amount, token, and timing, identifies the true + pairing better than chance across the anonymity set those three signals leave + unresolved. 2. **P2 must hold under test.** The equivalent test for burn-to-release pairings. 3. No transaction argument, event, log, or account-state change on either chain From 615bbb07b6db7903ec8f672267055c22a871856f Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:39:24 +1000 Subject: [PATCH 16/69] RFP-021: frame wrapping as one asset strategy, not the only path The passage claimed LEZ "has no path" to bring stablecoin liquidity onto the chain without a wrapped ERC-20 primitive, and that this blocks downstream protocols. This overstates it: a healthy DeFi ecosystem draws on native LEZ assets, wrapped assets, and synthetics together, and wrapping is one strategy among those we want to see implemented, not the exclusive route. Keep the concrete stablecoin market data as the reason wrapping is a worthwhile target, without implying it's the only way collateral reaches the lending protocol and reflexive stablecoin. --- RFPs/RFP-021-wrapped-erc20.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 2a037d66..f9e1a953 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -124,12 +124,14 @@ correlation an observer is left with as a result. ### Stablecoins are the concrete prize -USDT and USDC together account for over 80% of a stablecoin market that stood -above $300B in mid-2026, and are the settlement asset most DeFi money markets -and DEXes actually run on. Without a wrapped ERC-20 primitive, LEZ has no path -to bring USDC, USDT, DAI, or WETH liquidity onto the chain, which blocks the -lending protocol and the reflexive stablecoin from having any credible -collateral base at launch. +A healthy DeFi ecosystem needs a variety of assets available as collateral and +liquidity: native LEZ assets, wrapped assets, and synthetics each have a role, +and wrapping is one strategy among those we want to see implemented, not the +only one. USDT and USDC together account for over 80% of a stablecoin market +that stood above $300B in mid-2026, and are the settlement asset most DeFi money +markets and DEXes actually run on, which makes them a concrete target for this +strategy: wrapping USDC, USDT, DAI, and WETH gives the lending protocol and the +reflexive stablecoin a credible collateral base at launch. Bridges are also the most attacked category of infrastructure in DeFi: Chainalysis has tracked more than $2.8B stolen from cross-chain bridges since From aa4c861bf4e3ae608c803ef73d14c51e2ce5c744 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:45:01 +1000 Subject: [PATCH 17/69] RFP-021: correct Chainalysis figure, broaden bridge-security rationale The stated "$2.8B stolen since 2022" is not a real Chainalysis figure. The correct, sourced number is over $2B stolen from cross-chain bridges in 2022 alone (64% of that year's DeFi losses), per Chainalysis's 2022 report. Research into the largest bridge hacks (Ronin, Harmony Horizon, Multichain, Wormhole, Nomad, BNB Bridge, Poly Network) shows key-custody compromise explains roughly half of historical losses by value, and bugs in verification logic explain a comparable share, a risk a cryptographic design does not remove on its own. Broaden the rationale accordingly: state the RFP's cryptographic design targets key-custody compromise specifically, call out verification-logic correctness as an equally important risk, and note that an upgradeable verifier contract reintroduces the same key-custody problem via its upgrade key, hence a preference for an immutable program with an explicit migration path. --- RFPs/RFP-021-wrapped-erc20.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index f9e1a953..523d8ecd 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -134,11 +134,23 @@ strategy: wrapping USDC, USDT, DAI, and WETH gives the lending protocol and the reflexive stablecoin a credible collateral base at launch. Bridges are also the most attacked category of infrastructure in DeFi: -Chainalysis has tracked more than $2.8B stolen from cross-chain bridges since -2022, the highest-value class of exploit in the industry. This RFP's security -posture (cryptographic verification eliminating the trust-in-signers vector -entirely, combined with per-token and global caps and an admin-governed freeze -authority) is designed directly against that track record. +Chainalysis tracked over $2B stolen from cross-chain bridges in 2022 alone, 64% +of all DeFi losses that year. Roughly half of that historical loss traces to +compromised custody of validator or multisig keys (Ronin, Harmony Horizon, +Multichain); this RFP's cryptographic verification design is aimed directly at +that vector, since it requires no signer, validator, or federation to be trusted +with a key at all. But key custody is not the only cause: a comparable share of +losses (Wormhole, Nomad, BNB Bridge, Poly Network) came from bugs in +verification logic itself, a risk a cryptographic design does not remove, +because it depends on that logic being correct. A verifier deployed as an +upgradeable contract reintroduces the same key-custody problem one layer down, +since whoever holds the upgrade key can substitute broken or malicious +verification logic. For that reason this RFP prefers an immutable program with +an explicit migration path over an upgradeable one, and treats verification +logic correctness (audit, formal methods, extensive adversarial testing) as a +security requirement of the same order as eliminating signer trust. Per-token +and global caps and an admin-governed freeze authority remain as operational +safety nets against both failure modes. ## 🏗 Design Rationale From 1b6b31fc618e4fd24f39c9398bcbfdc5880d197e Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:49:04 +1000 Subject: [PATCH 18/69] RFP-021: merge Suggested approach into What cannot be hidden The two sections stated the same three problems (destination-hiding, amount-correlation, fee-payer-correlation) twice: once as bare problem statements, then again a section later paired with their mitigations. Merge them so each problem and its mitigation appear together, removing the duplicated problem statements. Also add a Bridge Security hard requirement: the verifier (LEZ bridge program and Ethereum vault verification logic) must be deployed as an immutable program with an explicit migration path, not an upgradeable contract. An upgrade key that can silently replace verification logic is a key-custody attack surface of the same kind the RFP's cryptographic design otherwise eliminates. Link the (forthcoming) bridge hack taxonomy appendix from the three places that previously cited the Chainalysis figure inline, including one that still had the incorrect $2.8B number from before that figure was corrected. --- RFPs/RFP-021-wrapped-erc20.md | 84 ++++++++++++++++++----------------- 1 file changed, 44 insertions(+), 40 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 523d8ecd..1e304624 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -142,7 +142,9 @@ that vector, since it requires no signer, validator, or federation to be trusted with a key at all. But key custody is not the only cause: a comparable share of losses (Wormhole, Nomad, BNB Bridge, Poly Network) came from bugs in verification logic itself, a risk a cryptographic design does not remove, -because it depends on that logic being correct. A verifier deployed as an +because it depends on that logic being correct (see +[Appendix: Cross-Chain Bridge Hack Taxonomy](../appendix/bridge-hack-taxonomy.md) +for the sourced figures and per-hack root causes). A verifier deployed as an upgradeable contract reintroduces the same key-custody problem one layer down, since whoever holds the upgrade key can substitute broken or malicious verification logic. For that reason this RFP prefers an immutable program with @@ -193,52 +195,43 @@ must not claim otherwise: real tokens to a real address. Privacy is therefore preserved by making these public facts *uninformative about -which counterparty they pair with*, not by attempting to hide them. Three -consequences follow, and proposals must address each: +which counterparty they pair with*, not by attempting to hide them. The +following is offered as orientation on how, not prescription; proposals are free +to achieve the required properties by other means, provided they argue the case. + +The well-understood construction for the destination side is a +commitment-and-nullifier shielded pool on each leg: the deposit publishes a +commitment rather than a destination, and the claimant later proves entitlement +without revealing which deposit they are claiming, with a nullifier preventing +double-claims. The redemption leg works the same way in reverse, which requires +splitting redemption into two separately-timed stages so that the burn need not +name its Ethereum destination. Minting into **private LEZ state** is the natural +fit for the LEZ side of this, and keeps the recipient and balance off public +view without additional machinery. A proof of source-chain consensus and state +contains no user-specific data, so it can be produced by anyone and anchored +on-chain permissionlessly, leaving the user's own device to prove only its own +entitlement against it; this keeps user-specific proving cheap enough to run +locally, which matters because whoever generates the entitlement proof learns +the connection the design exists to protect. + +Three further consequences follow from what cannot be hidden, and proposals must +address each: - **Amounts correlate.** A deposit of 1,337.42 USDC followed by a mint of 1,337.42 wUSDC is matched by elimination regardless of what cryptography sits between them. The amount visible on the Ethereum side must not act as a - fingerprint. + fingerprint. Restricting transfers to a fixed set of per-token denominations + is the simpler and better-understood mitigation, and is the expected baseline + for this RFP; hiding amounts outright via value commitments is stronger but + considerably heavier, and is specified as a soft requirement below. - **Timing correlates.** A deposit followed promptly by a mint, at a quiet moment, is matched by inspection. The protocol must not force users into correlated timing. - **Fee payers correlate.** If the user pays their own gas to mint or release, the funding source of that account re-identifies them and the construction - collapses. - -### Suggested approach - -The following is offered as orientation, not prescription. Proposals are free to -achieve the required properties by other means, provided they argue the case. - -A commitment-and-nullifier shielded pool on each leg is the well-understood -construction for this problem: the deposit publishes a commitment rather than a -destination, and the claimant later proves entitlement without revealing which -deposit they are claiming, with a nullifier preventing double-claims. The -redemption leg works the same way in reverse, which requires splitting -redemption into two separately-timed stages so that the burn need not name its -Ethereum destination. - -Minting into **private LEZ state** is the natural fit for the destination side, -and keeps the recipient and balance off public view without additional -machinery. - -For the amount-correlation problem, restricting transfers to a fixed set of -per-token denominations is the simpler and better-understood option, and is the -expected baseline for this RFP; hiding amounts outright via value commitments is -stronger but considerably heavier, and is specified as a soft requirement below. - -For the fee-payer problem, permissionless relayers paid out of the bridged -amount are the conventional answer, with the destination bound into the proof so -a relayer cannot redirect funds or overcharge. - -For the trust problem, note that a proof of source-chain consensus and state -contains no user-specific data, so it can be produced by anyone and anchored -on-chain permissionlessly, leaving the user's own device to prove only their -entitlement against it. This keeps user-specific proving cheap enough to run -locally, which matters because whoever generates the entitlement proof learns -the connection the design exists to protect. + collapses. Permissionless relayers paid out of the bridged amount are the + conventional mitigation, with the destination bound into the proof so a + relayer cannot redirect funds or overcharge. ### Trust model @@ -475,8 +468,9 @@ Use FURPS framework. Each numbered item should be a testable statement. smart-contract security audit before mainnet deployment; the audit report (or a summary, if the full report is not publishable) must be linked from the README. This requirement exists because cross-chain bridges are the - single most-attacked category of DeFi infrastructure (Chainalysis has - tracked more than $2.8B stolen from bridges since 2022); it is not optional. + single most-attacked category of DeFi infrastructure (see + [Appendix: Cross-Chain Bridge Hack Taxonomy](../appendix/bridge-hack-taxonomy.md)); + it is not optional. 09. Provide a **privacy properties document** covering: a formal statement of P1 and P2 and the anonymity set each is measured against; exactly what is visible on-chain at every step on both chains; what an adversary observing @@ -512,6 +506,16 @@ Use FURPS framework. Each numbered item should be a testable statement. 7. User-facing documentation must state the trustless verification model and the liveness-only role of any off-chain participant (see Design Rationale, "Trust model"). +8. The verifier (the LEZ bridge program and the Ethereum vault's proof + verification logic) must be deployed as an immutable program with an explicit + migration path (deploy a new version, drain and redirect to it) in preference + to an upgradeable contract governed by a mutable key. An upgrade key that can + silently swap verification logic is a key-custody attack surface of the same + kind this RFP's cryptographic design otherwise eliminates (see Why This + Matters and + [Appendix: Cross-Chain Bridge Hack Taxonomy](../appendix/bridge-hack-taxonomy.md)). + Proposals must document the chosen migration mechanism and how in-flight + deposits and burns are honoured across a migration. #### + Privacy Preservation From a9f2d0c44182239d4d87564cd2f70271957a7b77 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:51:41 +1000 Subject: [PATCH 19/69] RFP-021: require a failsafe strategy for verification-logic bugs The freeze authority can halt new activity but cannot recover funds already at risk or resolve deposits and burns left in-flight if a bug is found in deployed verification logic. Add a Bridge Security hard requirement: proposals must specify a failsafe strategy for this scenario, constrained so it cannot become a backdoor. Recovery must still go through the depositor or burner proving their own entitlement (the same mechanism as an ordinary claim or redemption), not an admin authority identifying and redirecting funds on a user's behalf, must only release funds to the address or account the proof specifies, and must not reach funds beyond what a specific, proven vulnerability put at risk. If no such mechanism is achievable, the proposal must instead document why a failsafe should not be implemented and what happens to affected positions in its absence. --- RFPs/RFP-021-wrapped-erc20.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 1e304624..0b4c9456 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -516,6 +516,21 @@ Use FURPS framework. Each numbered item should be a testable statement. [Appendix: Cross-Chain Bridge Hack Taxonomy](../appendix/bridge-hack-taxonomy.md)). Proposals must document the chosen migration mechanism and how in-flight deposits and burns are honoured across a migration. +9. The freeze authority (Functionality #13) stops new activity but does not by + itself recover funds already at risk or resolve deposits and burns left + in-flight once a vulnerability in the verification logic is found. Proposals + must specify a failsafe strategy for this scenario, constrained as follows: + the failsafe must not become a backdoor, meaning any recovery must still be + claimed by the depositor or burner proving their own entitlement, the same + way an ordinary claim or redemption works (see Design Rationale, "Trust + model" and "Loss of access"), not by an admin authority or any other party + identifying who owns what and redirecting funds on their behalf; it must not + be able to mint, redirect, or release funds to any destination other than the + address or account the proof specifies; and it must not be able to act on + funds beyond what a specific, proven vulnerability put at risk. If no + mechanism satisfying these constraints is achievable, the proposal must + instead document explicitly why a failsafe should not be implemented, and + what happens to affected funds and in-flight positions in its absence. #### + Privacy Preservation From 326a5bc06503a20eb39493e98f2e28960a9c7024 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:53:19 +1000 Subject: [PATCH 20/69] RFP-021: split bridge-hack content out of the stablecoin subsection "Stablecoins are the concrete prize" contained an unrelated paragraph about bridge-hack history and this RFP's security posture against it. Give that content its own subsection so each heading matches what it actually discusses. --- RFPs/RFP-021-wrapped-erc20.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 0b4c9456..508e4b3f 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -133,7 +133,8 @@ markets and DEXes actually run on, which makes them a concrete target for this strategy: wrapping USDC, USDT, DAI, and WETH gives the lending protocol and the reflexive stablecoin a credible collateral base at launch. -Bridges are also the most attacked category of infrastructure in DeFi: +### Bridges are the most attacked category of infrastructure in DeFi + Chainalysis tracked over $2B stolen from cross-chain bridges in 2022 alone, 64% of all DeFi losses that year. Roughly half of that historical loss traces to compromised custody of validator or multisig keys (Ronin, Harmony Horizon, From 8e9be04952a5b97dbcae76f00817fc08a4bca8b5 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:54:10 +1000 Subject: [PATCH 21/69] RFP-021: rename bridge-hack subsection to a plain section title "Bridges are the most attacked category of infrastructure in DeFi" read as an assertion rather than a heading. Rename to "Bridge risks: hacking" to match the plainer, descriptive heading style used elsewhere. --- RFPs/RFP-021-wrapped-erc20.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 508e4b3f..bf8d88fc 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -133,7 +133,7 @@ markets and DEXes actually run on, which makes them a concrete target for this strategy: wrapping USDC, USDT, DAI, and WETH gives the lending protocol and the reflexive stablecoin a credible collateral base at launch. -### Bridges are the most attacked category of infrastructure in DeFi +### Bridge risks: hacking Chainalysis tracked over $2B stolen from cross-chain bridges in 2022 alone, 64% of all DeFi losses that year. Roughly half of that historical loss traces to From 103d10e52f340c573ce6ecc03ab4d68c56f31878 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:54:51 +1000 Subject: [PATCH 22/69] RFP-021: merge What cannot be hidden into the privacy requirement section Both sections opened by restating the same premise (amount and timing are public on Ethereum by construction) before diverging into distinct content: the formal P1/P2 definitions, and the concrete facts plus mitigations. Merge into one section that states the public facts first, then builds the precise P1/P2 requirement on top of them, removing the duplicated framing and the two-section back-reference. --- RFPs/RFP-021-wrapped-erc20.md | 33 +++++++++++++++------------------ 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index bf8d88fc..8652f400 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -159,12 +159,19 @@ safety nets against both failure modes. ### The privacy requirement, stated precisely -Amount, token, and timing are not designed away: they are visible on Ethereum by -construction (see "What cannot be hidden" below), and a design that claimed -otherwise would be wrong. The hard requirement is narrower and precise about -what it covers: **no information other than amount, token, and timing may enable -an adversary to link an Ethereum deposit to the LEZ mint it funded, or a LEZ -burn to the Ethereum release it triggered.** +Two facts are fixed by the environment and cannot be designed away. Proposals +must not claim otherwise: + +1. **The Ethereum deposit amount is public**, as is the depositor's address: it + is an ordinary ERC-20 transfer into the vault, sent by the depositor. +2. **The Ethereum release amount and recipient are public**: the vault must move + real tokens to a real address. + +Amount, token, and timing are therefore visible on Ethereum by construction, and +a design that claimed otherwise would be wrong. The hard requirement is narrower +and precise about what it covers: **no information other than amount, token, and +timing may enable an adversary to link an Ethereum deposit to the LEZ mint it +funded, or a LEZ burn to the Ethereum release it triggered.** Stated against an adversary who observes **all** public state on both chains, indefinitely, and who may themselves deposit and redeem: @@ -182,18 +189,8 @@ Both properties are stated relative to an *anonymity set*, the set of candidates amount, token, and timing do not already narrow down, and both degrade to nothing when that set is small. Sizing, measuring, and surfacing the anonymity set is therefore a first-class requirement, not an implementation detail; so is -minimising how far amount and timing narrow it in the first place (see "What -cannot be hidden" below and Soft Requirement 1, Hidden amounts). - -### What cannot be hidden - -Two facts are fixed by the environment and cannot be designed away. Proposals -must not claim otherwise: - -1. **The Ethereum deposit amount is public**, as is the depositor's address: it - is an ordinary ERC-20 transfer into the vault, sent by the depositor. -2. **The Ethereum release amount and recipient are public**: the vault must move - real tokens to a real address. +minimising how far amount and timing narrow it in the first place (see Soft +Requirement 1, Hidden amounts, below). Privacy is therefore preserved by making these public facts *uninformative about which counterparty they pair with*, not by attempting to hide them. The From c32f3635c83301b2b88d4439408507f3de425bd6 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:56:59 +1000 Subject: [PATCH 23/69] RFP-021: separate token redemption from deposit-claim credential recovery "Recover their full bridge position" conflated two different things. Redemption is not stateful in that sense: once minted, a wrapped token is an ordinary LEZ token, and whoever holds it, whether from their own deposit or bought later on an AMM, can burn it to claim the underlying Ethereum asset. The only genuinely stateful recovery need is narrower: a user's own unclaimed deposits and unreleased burns, recoverable from credentials they already hold. Restate Design Rationale's "Loss of access" and Functionality #10 to reflect this distinction instead of implying redemption depends on the original depositor's credentials. --- RFPs/RFP-021-wrapped-erc20.md | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 8652f400..c1892de9 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -252,12 +252,21 @@ documented as such. ### Loss of access -In any design meeting these requirements, the protocol cannot identify who owns -what, so there is no administrative recovery path when a user loses access. This -is the largest UX risk in the RFP and must be designed against rather than -disclaimed: a user must be able to recover their full bridge position from -credentials they already hold and already back up. Requiring users to separately -back up new secrets generated during a deposit is not acceptable. +A wrapped token does not carry a bridge position with it: once minted, it is an +ordinary LEZ token, and whoever holds it, however they acquired it (received +directly from their own deposit, or bought on an AMM from someone else) can burn +it and claim the underlying Ethereum asset. Redemption depends only on holding +the token, never on the original depositor's credentials. + +The credentials-recovery problem is narrower than that, and specific to the +window between depositing on Ethereum and claiming the mint on LEZ: in any +design meeting these requirements, the protocol cannot identify who owns what, +so there is no administrative recovery path if a user loses the credentials +needed to claim their own deposit before it is claimed. This is the largest UX +risk in the RFP and must be designed against rather than disclaimed: a user must +be able to recover every unclaimed deposit of their own from credentials they +already hold and already back up. Requiring users to separately back up new +secrets generated during a deposit is not acceptable. ### Token registry and decimal normalisation @@ -339,10 +348,12 @@ Use FURPS framework. Each numbered item should be a testable statement. behalf must not thereby learn, or be able to prove, which deposit or burn it corresponds to. That party must not be able to alter the destination or take more than an agreed fee. -10. A user must be able to recover their full bridge position (every claimable - deposit and every unredeemed burn) from credentials they already hold, with - no dependence on any server-side index and no separately-backed-up secret - generated during the flow. +10. A user must be able to recover every one of their own unclaimed deposits and + unreleased burns from credentials they already hold, with no dependence on + any server-side index and no separately-backed-up secret generated during + the flow. This does not extend to the wrapped token itself: once minted, it + is an ordinary LEZ token redeemable by whoever holds it, regardless of who + made the original deposit. 11. An admin authority (per RFP-001, integrated via the SPEL framework where applicable to the LEZ side) can register a supported ERC-20 (Ethereum address, LEZ wrapped mint, decimals, permitted amounts, caps) and deregister From 100f976fc835421c1c3605ba7a2458ccbdc07f81 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:57:30 +1000 Subject: [PATCH 24/69] RFP-021: drastically shorten The privacy requirement, stated precisely Compress the four-paragraph lead-in and P1/P2 definitions into a tighter statement of the same content: the two public facts folded into one sentence, the hard requirement stated once, and P1/P2 trimmed to their essential claim. No requirement dropped, just restated more directly. --- RFPs/RFP-021-wrapped-erc20.md | 60 ++++++++++++++--------------------- 1 file changed, 23 insertions(+), 37 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index c1892de9..5cb2c00e 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -159,43 +159,29 @@ safety nets against both failure modes. ### The privacy requirement, stated precisely -Two facts are fixed by the environment and cannot be designed away. Proposals -must not claim otherwise: - -1. **The Ethereum deposit amount is public**, as is the depositor's address: it - is an ordinary ERC-20 transfer into the vault, sent by the depositor. -2. **The Ethereum release amount and recipient are public**: the vault must move - real tokens to a real address. - -Amount, token, and timing are therefore visible on Ethereum by construction, and -a design that claimed otherwise would be wrong. The hard requirement is narrower -and precise about what it covers: **no information other than amount, token, and -timing may enable an adversary to link an Ethereum deposit to the LEZ mint it -funded, or a LEZ burn to the Ethereum release it triggered.** - -Stated against an adversary who observes **all** public state on both chains, -indefinitely, and who may themselves deposit and redeem: - -- **P1 (inbound).** Given an Ethereum deposit, the adversary cannot determine - which LEZ mint it funded using any signal other than amount, token, and - timing, with probability better than uniform over the set of candidate mints - those three signals leave unresolved. -- **P2 (outbound).** Given a LEZ burn, the adversary cannot determine which - Ethereum release it triggered using any signal other than amount, token, and - timing, with probability better than uniform over the set of candidate - releases those three signals leave unresolved. - -Both properties are stated relative to an *anonymity set*, the set of candidates -amount, token, and timing do not already narrow down, and both degrade to -nothing when that set is small. Sizing, measuring, and surfacing the anonymity -set is therefore a first-class requirement, not an implementation detail; so is -minimising how far amount and timing narrow it in the first place (see Soft -Requirement 1, Hidden amounts, below). - -Privacy is therefore preserved by making these public facts *uninformative about -which counterparty they pair with*, not by attempting to hide them. The -following is offered as orientation on how, not prescription; proposals are free -to achieve the required properties by other means, provided they argue the case. +Deposit amount and depositor address, and release amount and recipient, are +public on Ethereum by construction: ordinary token transfers, not designed away. +The hard requirement is precise about what it covers instead: **no information +other than amount, token, and timing may enable an adversary who observes all +public state on both chains, indefinitely, and who may themselves deposit and +redeem, to link an Ethereum deposit to the LEZ mint it funded, or a LEZ burn to +the Ethereum release it triggered.** + +- **P1 (inbound).** No signal other than amount, token, and timing may narrow + down which LEZ mint an Ethereum deposit funded, beyond uniform probability + over the remaining candidates. +- **P2 (outbound).** No signal other than amount, token, and timing may narrow + down which Ethereum release a LEZ burn triggered, beyond uniform probability + over the remaining candidates. + +Both are stated relative to this *anonymity set*, the candidates amount, token, +and timing leave unresolved, and degrade to nothing when that set is small. +Sizing and minimising it (amount and timing above all, see Soft Requirement 1, +Hidden amounts, below) is a first-class requirement. Privacy comes from making +these public facts *uninformative about which counterparty they pair with*, not +from hiding them. The following is orientation on how, not prescription; +proposals are free to achieve the required properties by other means, provided +they argue the case. The well-understood construction for the destination side is a commitment-and-nullifier shielded pool on each leg: the deposit publishes a From d554c4be7d378c902664fc35d26b56084e7b1506 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:57:52 +1000 Subject: [PATCH 25/69] appendix: add cross-chain bridge hack taxonomy and stablecoin sourcing Sources RFP-021's claims about bridge-hack history and stablecoin market size: a summary table and per-hack detail for 11 major bridge exploits with root-cause classification, a dedicated section on whether any bridge hack has involved a stolen upgrade key, a root-cause dollar breakdown, an analysis of the two distinct Chainalysis reports commonly conflated into a single "$2B / 64%" citation, and a stablecoin market-size section verifying the "over 80%" USDT+USDC share and "above $300B" total market cap figures. --- appendix/bridge-hack-taxonomy.md | 481 +++++++++++++++++++++++++++++++ 1 file changed, 481 insertions(+) create mode 100644 appendix/bridge-hack-taxonomy.md diff --git a/appendix/bridge-hack-taxonomy.md b/appendix/bridge-hack-taxonomy.md new file mode 100644 index 00000000..5c838fa1 --- /dev/null +++ b/appendix/bridge-hack-taxonomy.md @@ -0,0 +1,481 @@ +# Appendix: Cross-Chain Bridge Hack Taxonomy + +This appendix surveys major cross-chain bridge exploits, classifies their root +causes, and sources the loss figures relevant to +[RFP-021](../RFPs/RFP-021-wrapped-erc20.md), a privacy-preserving wrapped ERC-20 +bridge for LEZ. It provides the evidence base for RFP-021's claim that bridges +are the most-attacked category of DeFi infrastructure, and for its design choice +to eliminate signer/validator trust while still treating verification-logic +correctness and upgrade-key custody as first-order risks. A second, shorter +section sources RFP-021's stablecoin market-size claim, which motivates the +specific tokens (USDC, USDT, DAI, WETH) the RFP proposes wrapping first. + +## Summary Table + +Ordered by date. USD figures are as reported at or near the time of the hack; +where sources disagree, a range is given (see per-hack sections for detail). + +| Hack | Date | Amount (USD, as reported) | Root cause category | Source | +| ------------------------------ | ---------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | --------- | +| Poly Network | 10 Aug 2021 | ~$611M (range $600M-$613M) | (b) Verification/access-control bug (self-granted authority) | [7][8][9] | +| THORChain (Bifrost/ETH Router) | 15 & 22 Jul 2021 | ~$8M + ~$8M (two incidents) | (b) Smart contract / verification logic bug | [27][28] | +| Qubit Finance (QBridge) | 27-28 Jan 2022 | $80M | (b) Smart contract / verification logic bug | [23][24] | +| Wormhole | 2 Feb 2022 | ~$325M (range $320M-$326M) | (b) Smart contract / verification logic bug | [4][5] | +| Meter.io (Meter Passport) | 5 Feb 2022 | ~$4.3M-$4.4M | (b) Smart contract / verification logic bug | [25][26] | +| Ronin Network / Axie Infinity | 23 Mar 2022 | ~$625M (range $540M-$625M) | (a) Validator/multisig key custody compromise | [1][2] | +| Harmony Horizon Bridge | 23 Jun 2022 | ~$100M | (a) Validator/multisig key custody compromise | [20][21] | +| Nomad | 1 Aug 2022 | ~$190M (range $190M-$200M) | (b) Verification logic bug, introduced via a legitimate upgrade | [6][10] | +| BNB Bridge / BSC Token Hub | 7 Oct 2022 | ~$570M minted (range $566M-$586M); ~$100M-$110M actually moved off-chain | (b) Smart contract / verification logic bug | [17][18] | +| Multichain | 6-7 Jul 2023 | ~$125M-$126M | (c) Admin/custody key compromise (MPC custody, single controlling party) | [14][15] | +| Orbit Chain | 31 Dec 2023 | ~$81M-$82M (range $81M-$86M) | (a) Validator/multisig key custody compromise (disputed; operator cites insider/infrastructure compromise) | [29][30] | + +## Per-Hack Detail + +### Poly Network (10 August 2021) + +Poly Network's `EthCrossChainManager` contract accepted attacker-supplied +cross-chain transaction data and could invoke arbitrary functions via +`_executeCrossChainTx`, including privileged functions on the +`EthCrossChainData` contract that `EthCrossChainManager` owned. The attacker +crafted a call that invoked `EthCrossChainData.putCurEpochConPubKeyBytes()`, a +function intended only for legitimate keeper-rotation consensus, through this +unintended call chain, reassigning the "keeper" (the address authorized to +approve cross-chain fund releases) to an address they controlled. They then used +that self-granted authority to authorize withdrawals across Ethereum, BNB Smart +Chain, and Polygon. SlowMist's and BlockSec's independent analyses both state +explicitly that this was not a leaked private key [8][9]. Reported losses range +from $600.3M to $613M depending on the token-price snapshot used across the +three affected chains; $611M is the most frequently cited figure [7]. Nearly all +funds were returned by the attacker within about two weeks. + +This sits at the boundary between categories (b) and (c): no credentials were +compromised, so it is fundamentally an access-control/verification bug, but its +*effect* (self-appointing as the sole trusted signer) is functionally equivalent +to what a stolen keeper or governance key would achieve. + +### THORChain Bifrost/ETH Router (15 and 22 July 2021) + +Two separate incidents in the ETH Router bridging component of THORChain, a +cross-chain liquidity network rather than a pure lock-and-mint bridge. In both +cases, attacker-deployed token contracts fed fake metadata to the router, +tricking it into refunding real assets for fake or manipulated deposits. +THORChain's own post-mortem confirms both as router logic bugs, not key +compromises [27][28]. Losses were approximately $8M in each incident. Included +here as a borderline case: it is a cross-chain bridging component being +exploited via a logic bug, but THORChain's overall architecture is an +AMM/liquidity network, not a lock-and-mint bridge in the RFP-021 sense. + +### Qubit Finance / QBridge (27-28 January 2022) + +QBridge exposed a legacy `deposit()` function alongside a newer `depositETH()` +function. The attacker called the legacy function with the ETH resource ID but +supplied zero actual ETH and a malformed token address; the contract's +transfer-verification logic did not check that a real transfer had occurred, so +it emitted the same deposit event the BSC-side relayer used to mint qXETH. This +minted 77,162 qXETH against no real collateral, which the attacker then used as +loan collateral to drain approximately $80M in ETH, BTC-B, stablecoins, and +other tokens [23][24]. A pure smart contract logic bug; no key or upgrade +mechanism was involved. + +### Wormhole (2 February 2022) + +The Solana-side Wormhole program used a deprecated helper, +`load_instruction_at`, to verify that a `secp256k1_program` +signature-verification instruction preceded a mint instruction. The deprecated +function did not check that the "instructions sysvar" account passed to it was +Solana's genuine sysvar account. The attacker supplied a spoofed sysvar account +pre-populated with fabricated data mimicking a valid signature-verification +instruction, and the program accepted this forged input as proof that the +required guardian signatures had validated a Verified Action Approval (VAA). +This let the attacker mint 120,000 wETH on Solana with no real ETH backing on +Ethereum [4][5]. USD figures range from $320M to $326M depending on the ETH +price used at time of reporting; the token amount (120,000 wETH) is the more +stable figure. The bug was patched by switching to +`load_instruction_at_checked`. This is a verification-logic bug in +already-deployed program code, unrelated to any contract upgrade or key +compromise. + +### Meter.io / Meter Passport (5 February 2022) + +Meter Passport's auto-wrap/unwrap convenience feature for native gas tokens +(ETH, BNB) did not properly restrict direct interaction with the wrapped ERC-20 +contracts, nor verify that a matching real value transfer had occurred, letting +the attacker mint WETH/WBNB without depositing real collateral [25][26]. The +direct loss to Meter was approximately $4.3M-$4.4M (1,391 ETH and 2.74 BTC), +with an additional ~$3.3M cascading loss at the dependent lending protocol +Hundred Finance. Same general failure family as Qubit: an event-driven relayer +trusting an event that did not correspond to a real transferred value. + +### Ronin Network / Axie Infinity Bridge (23 March 2022) + +Ronin's bridge required 5-of-9 validator signatures to authorize withdrawals. +The attacker compromised five validator keys: four Sky Mavis-run validators via +a single senior engineer, who was compromised through a fake LinkedIn job offer +whose "offer" PDF carried spyware, giving the attackers a foothold into Sky +Mavis's infrastructure and its four validator keys; and a fifth signature from +the third-party Axie DAO validator, obtained not by directly breaching Axie DAO +but because Axie DAO had granted Sky Mavis a temporary gas-fee allowlist +delegation in November 2021 (to handle demand load) that was never revoked. The +attackers' already compromised systems used this still-active delegated +permission to sign on Axie DAO's behalf [1][2]. Reported losses are 173,600 ETH +plus 25.5M USDC, most commonly valued at $625M at the time; figures as low as +$540M appear in some contemporaneous reporting depending on the ETH price used. +The exploit occurred on 23 March 2022 and was discovered on 29 March 2022, when +a user's 5,000 ETH withdrawal failed. This is a direct compromise of validator +signing keys that custody bridge funds via multisig consensus; no contract bug +or upgrade mechanism was involved. Ronin suffered a second, unrelated incident +in August 2024 via an authorized-upgrade bug (see "Upgrade-key compromise: what +the evidence shows," below). + +### Harmony Horizon Bridge (23 June 2022) + +The Ethereum-side Horizon bridge used a multisig requiring only two signatures +(commonly cited as 2-of-5) to authorize withdrawals. Per Harmony's own incident +summary, attackers ran a multi-stage intrusion: phishing and social engineering +against developers to plant malware, which gave visibility into internal +communications and non-public bridge infrastructure code, culminating in +backdoor access to privileged servers where keys were generated or decrypted on +the fly. This gave the attackers enough plaintext private keys to meet the +two-signature threshold and authorize eleven fraudulent withdrawal transactions +[20][21]. Losses were approximately $100M across ETH, WBTC, USDC, USDT, BUSD, +and other tokens. The attack was later attributed by Elliptic and the FBI to the +Lazarus Group, with funds laundered via Tornado Cash. A direct compromise of +fund-movement signing keys; no smart contract logic was exploited. + +### Nomad (1 August 2022) + +During a routine, authorized contract upgrade on 21 April 2022, Nomad's team +initialized the `Replica` contract's trusted-root storage by calling +`initialize()` with `0x00` set as an acceptable root. In Solidity, unset mapping +entries also default to `0x00`. Because the `process()` function treated any +message whose root matched an entry in the acceptable-root mapping as valid, and +`0x00` was both the deliberately "trusted" value and the default value for an +unproven message, every unproven message hash was automatically treated as +proved. This let the first attacker submit an arbitrary spoofed message to drain +funds; because the exploit calldata was trivially copy-pasteable (swap the +recipient address), it triggered a chaotic free-for-all involving roughly 960 +transactions from hundreds of opportunistic addresses on 1 August 2022 [6][10]. +Losses are commonly cited at $190M, with some sources rounding to $200M +depending on how traced/recovered funds are accounted for. + +No upgrade key or admin key was stolen or misused by an external attacker. The +vulnerability was introduced by Nomad's own team through a legitimate, +authorized upgrade with a catastrophic initialization error — a distinct failure +mode from a compromised or misused upgrade key. See "Upgrade-key compromise: +what the evidence shows," below, for why this distinction matters. + +### BNB Bridge / BSC Token Hub (7 October 2022) + +The BSC Token Hub validated cross-chain messages using an IAVL Merkle proof +scheme. The verification code failed to enforce that a proof node had no forged +"right" child: it computed the root hash using only the "left" field and never +checked for an injected "right" attribute. The attacker took a legitimate +historical proof, injected a crafted "right" node containing a forged payload +claiming a deposit that never happened, and the verifier's root-hash comparison +passed because the malicious right-child data was never included in the hash it +validated against. This let the attacker forge two withdrawal proofs and mint +1,000,000 BNB each (2,000,000 BNB total) with no real backing deposit [17][18]. +This is a pure verification-logic bug (the BNB Chain team named it +"Dragonfruit"); no keys were stolen or misused. The minted amount is commonly +valued at $566M-$586M at the time (~$570M is the most frequently cited +midpoint); of that, only about $100M-$110M was actually moved off-chain before +validators halted the network roughly 90 minutes after the exploit began, with +about $7M frozen immediately and the remainder effectively immobilized once the +attacker's address was blacklisted. + +### Multichain (6-7 July 2023) + +Multichain used an MPC (multi-party computation) custody scheme for bridge +funds. Multichain's CEO, Zhaojun He, was reportedly detained by Chinese police +in Kunming on 21 May 2023, roughly six weeks before large, unauthorized outflows +began. Outflows occurred in waves starting 6-7 July 2023: approximately $58M in +USDC, 1,023.8 WBTC, and 7,214 wETH left the Fantom bridge contract within 30 +minutes, followed by smaller outflows from Dogechain and Moonriver bridge +contracts. Multichain's own team stated they had lost access to the MPC node +servers and could not reach Zhaojun after his arrest [14]. No smart contract +vulnerability has been identified; security-firm analysis states the pattern +does not obviously relate to any previously audited vulnerability. Total losses +are commonly cited at $125M-$126M. A Singapore High Court ruling, in a suit +brought by Fantom against Multichain, found the breach was possible because +Zhaojun held ultimate privileges and control over the custodied assets, though +the court declined to find that he or Multichain actually diverted the funds +[15]; causation remains legally unresolved even though centralized operational +control over the MPC custody scheme is established. This is best classified as +an admin/custody key compromise: the MPC key shares functioned as the +operational custody mechanism for bridge funds, and a single controlling party +(or someone with access to his systems) retained effective unilateral control, +undermining the "multi-party" security assumption the scheme depended on. + +### Orbit Chain (31 December 2023) + +Independent security researchers and Rekt.news attributed this exploit to +compromise of 7-of-10 multisig signer keys on Orbit's Ethereum vault, likely via +social engineering [29]. Orbit's developer, Ozys, published an official +statement on 25 January 2024 explicitly denying both a smart contract +vulnerability and the theft of a validator key, instead attributing the root +cause to a former CISO who "arbitrarily changed firewall policies" shortly +before departing the company (resigned 6 December, exploit occurred 31 December) +[30] — implying insider sabotage or infrastructure compromise rather than direct +key theft. The two accounts are not fully mutually exclusive: a compromised +firewall could be the vector through which signer keys were exposed. This is a +genuine, unresolved disagreement between independent researchers and the +project's own statement, noted here rather than resolved. Losses are reported in +the $81M-$86M range, with $81.5M the most commonly cited figure. No mention in +any source of an upgradeable proxy or upgrade key; the funds were held directly +in a multisig-controlled vault. + +## Upgrade-key compromise: what the evidence shows + +RFP-021 treats an upgradeable verifier contract's *upgrade key* as a key-custody +attack surface of the same kind as a validator or multisig key, one layer +removed: whoever holds the upgrade key can substitute the verification logic +itself, rather than directly signing a fraudulent withdrawal. This is a distinct +category from every hack tabulated above, none of which involved an upgrade key +being stolen or misused by an external attacker. Two related but distinct +patterns emerge from the historical record, and they should not be conflated: + +**Pattern A: a legitimate, authorized upgrade introduces a catastrophic bug.** +No key is stolen; the team that legitimately controls the upgrade key exercises +it correctly, but the new logic is broken. Nomad (above) is the clearest bridge +example: a routine upgrade set a trusted root to a value that collided with the +default "unproven" value. A second, later example from the same project family +is instructive: Ronin suffered a second, unrelated incident in August 2024, +distinct from the March 2022 validator-key compromise. During a `BridgeManager` +contract upgrade, the team skipped calling `initializeV3()`, leaving an internal +`_totalOperatorWeight` value at zero, which disabled the minimum-vote-weight +check and let a single signature pass verification where several should have +been required. An MEV bot found the bug and withdrew $12M, later returned as a +whitehat disclosure for a $500K bounty [19]. Both cases show that the +bug-introduction risk from a mutable, upgradeable verifier is real and has +caused (Nomad) or nearly caused (Ronin 2024) major losses, even absent any +attacker gaining control of the upgrade key itself. + +**Pattern B: an attacker manufactures upgrade or governance authority through a +separate bug**, rather than stealing the legitimate key outright. Audius (July +2022, a DeFi governance protocol, not a bridge) is the clearest example: a +storage-slot collision between the proxy's admin slot and OpenZeppelin's +`Initializable` flag let an attacker call `initialize()` again on an +already-initialized proxy and seize governance control, which they then used to +push a malicious governance action draining approximately $6M in AUDIO tokens +[11][12]. Wormhole had a near-miss of the same kind: an uninitialized UUPS proxy +would have let an attacker call `initialize()`, set themselves as guardian, and +push a malicious upgrade; this was caught and responsibly disclosed through +Wormhole's bug bounty program before any exploitation, with a $10M bounty paid +and no funds lost [13]. Poly Network (above) is a bridge-specific variant of +this same pattern: no key was stolen, but a verification bug let the attacker +self-grant an authority (the "keeper") that functions as the bridge's trusted +signer set, achieving an effect equivalent to a stolen governance key without +stealing one. + +**No documented case of a completed bridge hack via a genuinely stolen or +phished upgrade key was found.** The clearest examples of an upgrade key or +admin key being directly compromised and used to push malicious logic are +outside the bridge category: PAID Network (March 2021), where an attacker +compromised the single private key controlling proxy upgrade rights, upgraded to +malicious logic, and minted approximately 59.5M tokens for a loss of roughly $3M +[16]; and Wasabi Protocol (April 2026), a perpetuals protocol where an attacker +compromised the deployer EOA holding sole admin rights (no multisig or +timelock), granted itself an admin role, and executed unauthorized upgrades on +vault proxies, draining approximately $4.5M-$5.5M across three chains. Both are +DeFi protocols, not cross-chain bridges. Security-firm commentary (Trail of +Bits' 2020 review of Aave's upgradeability, and general framing from Immunefi +and OpenZeppelin) treats post-deployment upgrade mechanisms as a +disproportionate source of protocol losses as a general class, but without a +bridge-specific incident list to cite. + +The practical reading for RFP-021's argument: the *category* of risk (a mutable +verifier controlled by a key that can swap in malicious or broken logic) is +real, attested by security-firm framing, and has caused actual bridge losses +through Pattern A (a legitimate upgrade shipping a bug, Nomad and Ronin 2024) +and a bridge-specific near-miss of Pattern B (Wormhole's uninitialized proxy, +caught before exploitation). It has not, in the documented record, caused a +bridge loss through the narrower scenario of an attacker stealing an upgrade key +outright, though that exact pattern has occurred in non-bridge DeFi (PAID +Network, Wasabi Protocol). An immutable program with an explicit migration path +removes the upgrade key from the attack surface entirely, closing off both +patterns rather than only the one with a clean historical precedent. + +## Root-cause breakdown + +Excluding THORChain (a borderline case, not a lock-and-mint bridge in the +RFP-021 sense) and treating Poly Network and Multichain per their categorization +above, the ten core hacks in the summary table break down as follows by dollar +value (approximate, using the midpoint of any reported range): + +- **(a) Validator/multisig key custody compromise:** Ronin (~$625M), Harmony + Horizon (~$100M), Orbit Chain (~$81.5M, disputed). Subtotal: **~$806.5M**. +- **(b) Smart contract / verification logic bug:** Wormhole (~$323M), Nomad + (~$190M), BNB Bridge (~$576M minted, ~$105M actually exfiltrated), Qubit + Finance (~$80M), Meter.io (~$4.35M), Poly Network (~$611M, boundary case). + Subtotal using minted/at-risk BNB Bridge figure: **~$1.784B**; using the + amount actually moved off-chain for BNB Bridge instead: **~$1.313B**. +- **(c) Admin/governance key compromise:** Multichain (~$125.5M, boundary case + with (a) given MPC custody). Subtotal: **~$125.5M**. + +This does not cleanly reproduce a "half key custody, half verification bugs" +split in dollar terms across this specific set: by these figures, +verification-logic bugs account for a larger share of gross value at risk than +key-custody compromises, driven heavily by the BNB Bridge minted amount and Poly +Network's near-$611M figure, both of which are boundary cases (BNB Bridge +because most of the minted value was never actually moved off-chain; Poly +Network because the bug's effect mimicked a stolen governance key without one +being stolen). If Poly Network is instead counted toward key custody (its effect +being equivalent to a stolen keeper key) and BNB Bridge's actually-exfiltrated +figure is used rather than its minted figure, category (a) plus Poly Network's +$611M would dominate instead. The underlying point RFP-021 makes — that key +custody is a large but not exclusive source of bridge losses, and +verification-logic bugs are a comparably large source — holds directionally +across every reasonable way of drawing the boundary cases; a precise 50/50 split +should not be asserted as an exact figure, because it depends heavily on how BNB +Bridge's minted vs. exfiltrated amount and Poly Network's boundary case are each +counted. + +## Chainalysis figures: what the primary sources actually say + +RFP-021 cites Chainalysis for the claim that over $2B was stolen from +cross-chain bridges in 2022, representing 64% of that year's DeFi hacking +losses. Chainalysis in fact published two separate figures, from two separate +reports, that are often conflated: + +- **"Cross-Chain Bridge Hacks Emerge as Top Security Risk"** (2 August 2022) + \[3\]: "Chainalysis estimates that $2 billion in cryptocurrency has been + stolen across 13 separate cross-chain bridge hacks... Attacks on bridges + account for 69% of total funds stolen in 2022 so far." This is a + **partial-year** figure (through early August 2022), and the 69% is a share of + **all** cryptocurrency theft in that period, not specifically of DeFi losses. +- **"2022 Biggest Year Ever for Crypto Hacking"** (1 February 2023) \[3\]: "DeFi + protocols as victims accounted for 82.1% of all cryptocurrency stolen by + hackers — a total of $3.1 billion... And of that $3.1 billion, 64% came from + cross-chain bridge protocols specifically." This is the **full-year** figure, + and the 64% is a share of **DeFi-specific** losses ($3.1B), not of all crypto + theft. 64% of $3.1B is approximately $1.98B, close to but not identical to the + earlier $2B figure, which came from a different, partial-year, + differently-denominated report. + +Both figures are directionally consistent and both support the underlying claim +that bridges were the single largest category of DeFi hacking losses in 2022. +But the $2B dollar figure and the 64% percentage, as commonly paired in +secondary reporting (including news aggregation that RFP-021's figure likely +traces to), actually come from two different Chainalysis reports measuring +different populations over different time windows, not from a single, internally +consistent statistic. The more defensible citation is the February 2023 report's +64%-of-2022-DeFi-losses figure on its own, or the August 2022 report's +$2B/69%-of-total-crypto-theft figure on its own, rather than pairing the two +numbers as if from one source. + +### Trend since 2022 + +Chainalysis does not appear to publish a recurring, directly comparable +bridge-hack-specific percentage in its subsequent annual reports; coverage +shifted toward broader categories such as private-key compromises and +centralized-exchange hacks, and toward bridges as a money-laundering conduit +(chain-hopping) rather than as the primary attack vector. Total crypto hacking +losses (all categories, not bridge-specific) reported by Chainalysis in +subsequent years: + +- **2023:** approximately $1.7B, down roughly 54% year-over-year [31]. +- **2024:** approximately $2.2B, up roughly 21% year-over-year [32]; the largest + bridge-specific incident that year was Orbit Chain (~$81.8M), a small fraction + of the total. +- **2025 (mid-year):** more than $2.17B stolen by mid-July 2025, already + exceeding all of 2024, though dominated by the Bybit exchange hack (~$1.5B, a + private-key compromise, not a bridge exploit) rather than by bridge-specific + losses [33]. + +The overall pattern is a marked decline in bridge hacks specifically as a share +of total DeFi/crypto losses since the 2022 peak, even as total crypto theft has +fluctuated and, by mid-2025, exceeded 2022 levels again driven by other +categories (notably exchange and private-key compromises). + +## Stablecoin Market Context + +RFP-021 cites USDT and USDC together holding "over 80%" of a stablecoin market +"above $300B in mid-2026" as the rationale for prioritising those two assets +(alongside DAI and WETH) as the bridge's first wrapped tokens. DefiLlama tracks +total stablecoin market capitalisation at approximately $310B-$313B through +mid-2026, having peaked above $321B earlier in the year before shedding roughly +$10B by late July [34][35]. The "above $300B" framing is accurate as a floor, +though it understates the market by omitting the more precise $310B+ figure +available from the same tracker. + +Tether (USDT) is the largest stablecoin by a wide margin, with a market cap of +approximately $183.4B and roughly 59-64% of total stablecoin supply depending on +the exact date sampled [36][37]. Circle's USDC is second, at approximately +$72B-$75B, roughly 23-24% of supply [37][38]. Combined, USDT and USDC hold +approximately 89% of total stablecoin market capitalisation as of early August +2026 [36][37] — comfortably clearing RFP-021's "over 80%" claim rather than +merely meeting it. + +Supply share is not the same claim as settlement dominance, and the two should +not be conflated. On supply, USDT leads by a wide margin. On on-chain DEX +settlement volume specifically, the picture has shifted materially during 2026: +USDC accounted for roughly 70-80% of adjusted stablecoin transaction volume in +H1 2026, ahead of USDT's roughly 25%, a reversal from historical patterns where +USDT dominated volume [39][40]. Curve and Uniswap remain the primary venues for +USDC/USDT pairs, and stablecoin swaps make up the majority of DEX trading volume +on Ethereum [39]. On lending markets, Aave, the largest lending venue by +deposits, reportedly holds an 80%+ share of USDT and USDC deposits/borrows on +Ethereum, with stablecoin pools forming the protocol's largest liquidity base +[41]. Taken together, this supports RFP-021's framing that USDT and USDC are the +settlement asset most DeFi money markets and DEXes actually run on, though the +volume and collateral-share figures are drawn from secondary market trackers and +platform-level reporting rather than a single authoritative cross-protocol +study, and should be read as directionally strong rather than precisely +measured. + +## References + +01. [Halborn — Explained: The Ronin Hack (March 2022)](https://www.halborn.com/blog/post/explained-the-ronin-hack-march-2022) +02. [Ronin/Sky Mavis — Back to Building: Ronin Security Breach](https://roninchain.com/blog/posts/back-to-building-ronin-security-breach-6513cc78a5edc1001b03c364) +03. [Chainalysis — Cross-Chain Bridge Hacks Emerge as Top Security Risk](https://www.chainalysis.com/blog/cross-chain-bridge-hacks-2022/) + (2 Aug 2022, partial-year, $2B/69%-of-total-theft figure); see also + [Chainalysis — 2022 Biggest Year Ever for Crypto Hacking](https://www.chainalysis.com/blog/2022-biggest-year-ever-for-crypto-hacking/) + (1 Feb 2023, full-year, 64%-of-DeFi-losses figure) +04. [Halborn — Explained: The Wormhole Hack (February 2022)](https://www.halborn.com/blog/post/explained-the-wormhole-hack-february-2022) +05. [CertiK — Wormhole Bridge Exploit Incident Analysis](https://www.certik.com/blog/wormhole-bridge-exploit-incident-analysis) +06. [Immunefi — Hack Analysis: Nomad Bridge, August 2022](https://medium.com/immunefi/hack-analysis-nomad-bridge-august-2022-5aa63d53814a) +07. [Halborn — Explained: The Poly Network Hack (August 2021)](https://www.halborn.com/blog/post/explained-the-poly-network-hack-august-2021) +08. [SlowMist — The Root Cause of Poly Network Being Hacked](https://slowmist.medium.com/the-root-cause-of-poly-network-being-hacked-ec2ee1b0c68f) +09. [BlockSec — The Initial Analysis of the PolyNetwork Hack](https://blocksecteam.medium.com/the-initial-analysis-of-the-polynetwork-hack-270ac6072e2a) +10. [Halborn — The Nomad Bridge Hack: A Deeper Dive](https://www.halborn.com/blog/post/the-nomad-bridge-hack-a-deeper-dive) +11. [Audius — Audius Governance Takeover Post-Mortem](https://blog.audius.co/article/audius-governance-takeover-post-mortem-7-23-22) +12. [ChainLight — Audius Variant Scanner: Scanning Storage Collisions Between Ethereum Contracts](https://blog.chainlight.io/en-audius-variant-scanner-scanning-storage-collisions-between-ethereum-contracts-4d2d64b77566) +13. [Immunefi — Wormhole Uninitialized Proxy Bugfix Review](https://immunefi.com/blog/bug-fix-reviews/wormhole-uninitialized-proxy-bugfix-review/) +14. [Halborn — Explained: The Multichain Hack (July 2023)](https://www.halborn.com/blog/post/explained-the-multichain-hack-july-2023) +15. [DL News — Singapore Court Ruling Fuels View Multichain Hack Was Inside Job](https://www.dlnews.com/articles/defi/singapore-court-fuels-view-multichain-hack-was-inside-job/) +16. [Halborn — Explained: The PAID Network Hack (March 2021)](https://www.halborn.com/blog/post/explained-the-paid-network-hack-march-2021) +17. [Halborn — Explained: The BNB Chain Hack (October 2022)](https://www.halborn.com/blog/post/explained-the-bnb-chain-hack-october-2022) +18. [Immunefi — Hack Analysis: Binance Bridge, October 2022](https://immunefi.com/blog/bug-fix-reviews/hack-analysis-binance-bridge-october-2022/) +19. [Halborn — Explained: The Ronin Network Hack (August 2024)](https://www.halborn.com/blog/post/explained-the-ronin-network-hack-august-2024) +20. [Halborn — Explained: The Harmony Horizon Bridge Hack](https://www.halborn.com/blog/post/explained-the-harmony-horizon-bridge-hack) +21. [Harmony Community Forum — Summary of the Horizon Bridge Incident](https://talk.harmony.one/t/summary-of-the-horizon-bridge-incident/20990) +22. [Elliptic — The Harmony Horizon Bridge Hack](https://www.elliptic.co/resources/harmony-horizon-bridge-hack) +23. [Halborn — Explained: The Qubit Hack (January 2022)](https://www.halborn.com/blog/post/explained-the-qubit-hack-january-2022) +24. [SlowMist — Our Analysis of the $80M Qubit Finance Exploit](https://slowmist.medium.com/our-analysis-of-the-80m-qubit-finance-exploit-b0f272cd8c25) +25. [Halborn — Explained: The Meter.io Hack (February 2022)](https://www.halborn.com/blog/post/explained-the-meter-io-hack-february-2022) +26. [Cointelegraph — Latest DeFi Bridge Exploit Results in $4.4M Losses for Meter](https://cointelegraph.com/news/latest-defi-bridge-exploit-results-in-4-4m-losses-for-meter) +27. [Halborn — Explained: The THORChain Hack (July 2021)](https://www.halborn.com/blog/post/explained-the-thorchain-hack-july-2021) +28. [THORChain — Post-Mortem: ETH Router Exploits 1 & 2, and Premature Return to Trading](https://medium.com/thorchain/post-mortem-eth-router-exploits-1-2-and-premature-return-to-trading-incident-2908928c5fb) +29. [Rekt.news — Orbit Bridge Rekt](https://rekt.news/orbit-bridge-rekt) +30. [Orbit Chain — Official Statement Regarding Orbit Bridge Exploit](https://medium.com/orbit-chain/official-statement-regarding-orbit-bridge-exploit-551928f3dc52) +31. [Chainalysis — Stolen Crypto Falls in 2023](https://www.chainalysis.com/blog/crypto-hacking-stolen-funds-2024/) +32. [Chainalysis — $2.2 Billion Stolen in Crypto in 2024](https://www.chainalysis.com/blog/crypto-hacking-stolen-funds-2025/) +33. [Chainalysis — 2025 Crypto Crime Mid-Year Update](https://www.chainalysis.com/blog/2025-crypto-crime-mid-year-update/) +34. [DefiLlama — Stablecoins](https://defillama.com/stablecoins) — total + stablecoin market cap and per-issuer breakdown, tracked live +35. [Bitcoin Foundation — Stablecoin Market Cap Tops $321B, Extending 2026 Growth](https://bitcoinfoundation.org/news/stablecoin-news/stablecoin-market-cap-tops-321b/) +36. [CoinLaw — Tether Statistics 2026](https://coinlaw.io/tether-statistics/) — + USDT market cap and supply-share figures, early August 2026 +37. [The Motley Fool — Which Stablecoins Are the Largest and Most Popular](https://www.fool.com/research/largest-stablecoins/) + — USDT/USDC combined market-share figure +38. [USDC.org — USDC Supply Stats](https://usdc.org/stats) — USDC circulating + supply and market cap +39. [KuCoin — USDC Accounts for 70% of Adjusted Stablecoin Volume in H1 2026](https://www.kucoin.com/news/flash/usdc-accounts-for-70-of-adjusted-stablecoin-volume-in-h1-2026) +40. [CoinDesk — Circle's USDC Is Leaving Tether Behind in the Stablecoin Volume Race](https://www.coindesk.com/business/2026/07/06/circle-s-usdc-is-leaving-tether-behind-in-the-stablecoin-volume-race) +41. [Aave — Aave Is Infrastructure for Scaling Stablecoins](https://aave.com/blog/stablecoin-infrastructure) + — Aave stablecoin deposit/borrow share commentary + +______________________________________________________________________ + +*This appendix was prepared to support RFP-021. For clarification or additions, +please use the RFP repository Discussions.* From 8fdf2e500da4344aa89e29b661aac86be4e61c02 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:58:42 +1000 Subject: [PATCH 26/69] RFP-021: reconcile bridge-hack claims with the sourced appendix The appendix's research (now committed at appendix/bridge-hack-taxonomy.md) surfaced three overstatements in the RFP body: the "$2B / 64%" figure paired two different Chainalysis reports measuring different populations over different time windows; "roughly half... comparable share" implied an even key-custody vs. verification-bug split that doesn't hold cleanly in dollar terms and by some reasonable accounting favours verification bugs; and the upgrade-key paragraph implied bridge hacks from stolen upgrade keys are a documented pattern, when in fact no such case was found, the real documented bridge risk from mutable verifiers is a legitimate upgrade shipping a bug (Nomad, Ronin 2024). Correct the Why This Matters paragraph and Bridge Security requirement #8 to state what the appendix actually supports, without weakening the underlying design conclusion (prefer an immutable program with a migration path), which still holds either way. --- RFPs/RFP-021-wrapped-erc20.md | 49 +++++++++++++++++++---------------- 1 file changed, 27 insertions(+), 22 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 5cb2c00e..74e6f39c 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -135,25 +135,29 @@ reflexive stablecoin a credible collateral base at launch. ### Bridge risks: hacking -Chainalysis tracked over $2B stolen from cross-chain bridges in 2022 alone, 64% -of all DeFi losses that year. Roughly half of that historical loss traces to -compromised custody of validator or multisig keys (Ronin, Harmony Horizon, -Multichain); this RFP's cryptographic verification design is aimed directly at -that vector, since it requires no signer, validator, or federation to be trusted -with a key at all. But key custody is not the only cause: a comparable share of -losses (Wormhole, Nomad, BNB Bridge, Poly Network) came from bugs in -verification logic itself, a risk a cryptographic design does not remove, -because it depends on that logic being correct (see +Chainalysis found that cross-chain bridge protocols accounted for 64% of the +$3.1B stolen from DeFi in 2022, the single largest category that year. A large +share of that historical loss traces to compromised custody of validator or +multisig keys (Ronin, Harmony Horizon, Multichain); this RFP's cryptographic +verification design is aimed directly at that vector, since it requires no +signer, validator, or federation to be trusted with a key at all. But key +custody is not the only cause, and by some reasonable ways of counting is not +even the largest: a comparable or larger share of losses (Wormhole, Nomad, BNB +Bridge, Poly Network) came from bugs in verification logic itself, a risk a +cryptographic design does not remove, because it depends on that logic being +correct (see [Appendix: Cross-Chain Bridge Hack Taxonomy](../appendix/bridge-hack-taxonomy.md) -for the sourced figures and per-hack root causes). A verifier deployed as an -upgradeable contract reintroduces the same key-custody problem one layer down, -since whoever holds the upgrade key can substitute broken or malicious -verification logic. For that reason this RFP prefers an immutable program with -an explicit migration path over an upgradeable one, and treats verification -logic correctness (audit, formal methods, extensive adversarial testing) as a -security requirement of the same order as eliminating signer trust. Per-token -and global caps and an admin-governed freeze authority remain as operational -safety nets against both failure modes. +for the sourced figures, per-hack root causes, and the exact Chainalysis +citation). A verifier deployed as an upgradeable contract carries a related risk +one layer down: no cross-chain bridge hack has traced to a stolen upgrade key, +but legitimate, authorised upgrades have shipped catastrophic verification bugs +(Nomad; a second Ronin incident in 2024), which an immutable program with no +upgrade path forecloses by construction. For that reason this RFP prefers an +immutable program with an explicit migration path over an upgradeable one, and +treats verification logic correctness (audit, formal methods, extensive +adversarial testing) as a security requirement of the same order as eliminating +signer trust. Per-token and global caps and an admin-governed freeze authority +remain as operational safety nets against both failure modes. ## 🏗 Design Rationale @@ -504,10 +508,11 @@ Use FURPS framework. Each numbered item should be a testable statement. 8. The verifier (the LEZ bridge program and the Ethereum vault's proof verification logic) must be deployed as an immutable program with an explicit migration path (deploy a new version, drain and redirect to it) in preference - to an upgradeable contract governed by a mutable key. An upgrade key that can - silently swap verification logic is a key-custody attack surface of the same - kind this RFP's cryptographic design otherwise eliminates (see Why This - Matters and + to an upgradeable contract governed by a mutable key. An upgradeable verifier + carries two risks this eliminates by construction: a stolen or misused + upgrade key substituting malicious logic, and a legitimate, authorised + upgrade shipping a catastrophic bug, the latter being the documented cause of + real bridge losses (see Why This Matters and [Appendix: Cross-Chain Bridge Hack Taxonomy](../appendix/bridge-hack-taxonomy.md)). Proposals must document the chosen migration mechanism and how in-flight deposits and burns are honoured across a migration. From f547ce4b7150c125850d549a754e7ee1c2c29f6a Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 10:59:21 +1000 Subject: [PATCH 27/69] appendix: rename bridge-hack-taxonomy to bridges-and-wrapped-tokens The appendix now covers both the bridge-hack survey and the stablecoin market-size sourcing, so the filename and title should reflect the broader scope rather than only the (larger) bridge-hack section. Update the appendix's title and opening paragraph, and all three links to it from RFP-021's body. --- RFPs/RFP-021-wrapped-erc20.md | 6 +++--- ...onomy.md => bridges-and-wrapped-tokens.md} | 19 ++++++++++--------- 2 files changed, 13 insertions(+), 12 deletions(-) rename appendix/{bridge-hack-taxonomy.md => bridges-and-wrapped-tokens.md} (98%) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 74e6f39c..116938fc 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -146,7 +146,7 @@ even the largest: a comparable or larger share of losses (Wormhole, Nomad, BNB Bridge, Poly Network) came from bugs in verification logic itself, a risk a cryptographic design does not remove, because it depends on that logic being correct (see -[Appendix: Cross-Chain Bridge Hack Taxonomy](../appendix/bridge-hack-taxonomy.md) +[Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md) for the sourced figures, per-hack root causes, and the exact Chainalysis citation). A verifier deployed as an upgradeable contract carries a related risk one layer down: no cross-chain bridge hack has traced to a stolen upgrade key, @@ -468,7 +468,7 @@ Use FURPS framework. Each numbered item should be a testable statement. (or a summary, if the full report is not publishable) must be linked from the README. This requirement exists because cross-chain bridges are the single most-attacked category of DeFi infrastructure (see - [Appendix: Cross-Chain Bridge Hack Taxonomy](../appendix/bridge-hack-taxonomy.md)); + [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)); it is not optional. 09. Provide a **privacy properties document** covering: a formal statement of P1 and P2 and the anonymity set each is measured against; exactly what is @@ -513,7 +513,7 @@ Use FURPS framework. Each numbered item should be a testable statement. upgrade key substituting malicious logic, and a legitimate, authorised upgrade shipping a catastrophic bug, the latter being the documented cause of real bridge losses (see Why This Matters and - [Appendix: Cross-Chain Bridge Hack Taxonomy](../appendix/bridge-hack-taxonomy.md)). + [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)). Proposals must document the chosen migration mechanism and how in-flight deposits and burns are honoured across a migration. 9. The freeze authority (Functionality #13) stops new activity but does not by diff --git a/appendix/bridge-hack-taxonomy.md b/appendix/bridges-and-wrapped-tokens.md similarity index 98% rename from appendix/bridge-hack-taxonomy.md rename to appendix/bridges-and-wrapped-tokens.md index 5c838fa1..855f1cf2 100644 --- a/appendix/bridge-hack-taxonomy.md +++ b/appendix/bridges-and-wrapped-tokens.md @@ -1,14 +1,15 @@ -# Appendix: Cross-Chain Bridge Hack Taxonomy +# Appendix: Bridges and Wrapped Tokens -This appendix surveys major cross-chain bridge exploits, classifies their root -causes, and sources the loss figures relevant to +This appendix surveys the ecosystem context behind [RFP-021](../RFPs/RFP-021-wrapped-erc20.md), a privacy-preserving wrapped ERC-20 -bridge for LEZ. It provides the evidence base for RFP-021's claim that bridges -are the most-attacked category of DeFi infrastructure, and for its design choice -to eliminate signer/validator trust while still treating verification-logic -correctness and upgrade-key custody as first-order risks. A second, shorter -section sources RFP-021's stablecoin market-size claim, which motivates the -specific tokens (USDC, USDT, DAI, WETH) the RFP proposes wrapping first. +bridge for LEZ, in two parts. The first and larger part surveys major +cross-chain bridge exploits, classifies their root causes, and sources the loss +figures relevant to RFP-021's claim that bridges are the most-attacked category +of DeFi infrastructure, and to its design choice to eliminate signer/validator +trust while still treating verification-logic correctness and upgrade-key +custody as first-order risks. The second, shorter part sources RFP-021's +stablecoin market-size claim, which motivates the specific tokens (USDC, USDT, +DAI, WETH) the RFP proposes wrapping first. ## Summary Table From 682ca4eb1b6e4cd8d4089143866f3bfc386d63d2 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 11:00:59 +1000 Subject: [PATCH 28/69] RFP-021: remove prescriptive construction paragraph from Design Rationale The paragraph described a specific implementation (commitment-and- nullifier shielded pool, minting into private LEZ state, permissionless proof anchoring) despite being framed as "orientation, not prescription". This RFP specifies outcomes and required properties, not implementations; proposals choose their own construction. The underlying requirements this paragraph gestured at are already stated as hard requirements elsewhere (Functionality #4 for private-state minting, the P1/P2 properties above for destination-hiding), so nothing is lost by removing the suggested implementation. --- RFPs/RFP-021-wrapped-erc20.md | 19 +------------------ 1 file changed, 1 insertion(+), 18 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 116938fc..1245ae32 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -183,24 +183,7 @@ and timing leave unresolved, and degrade to nothing when that set is small. Sizing and minimising it (amount and timing above all, see Soft Requirement 1, Hidden amounts, below) is a first-class requirement. Privacy comes from making these public facts *uninformative about which counterparty they pair with*, not -from hiding them. The following is orientation on how, not prescription; -proposals are free to achieve the required properties by other means, provided -they argue the case. - -The well-understood construction for the destination side is a -commitment-and-nullifier shielded pool on each leg: the deposit publishes a -commitment rather than a destination, and the claimant later proves entitlement -without revealing which deposit they are claiming, with a nullifier preventing -double-claims. The redemption leg works the same way in reverse, which requires -splitting redemption into two separately-timed stages so that the burn need not -name its Ethereum destination. Minting into **private LEZ state** is the natural -fit for the LEZ side of this, and keeps the recipient and balance off public -view without additional machinery. A proof of source-chain consensus and state -contains no user-specific data, so it can be produced by anyone and anchored -on-chain permissionlessly, leaving the user's own device to prove only its own -entitlement against it; this keeps user-specific proving cheap enough to run -locally, which matters because whoever generates the entitlement proof learns -the connection the design exists to protect. +from hiding them. Three further consequences follow from what cannot be hidden, and proposals must address each: From 3f7c706c08860c6c734a9ddcadf679b54271629e Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 11:03:46 +1000 Subject: [PATCH 29/69] RFP-021: cover both claim windows and prefer regenerable recovery data "Loss of access" only described the deposit-to-mint window; state the symmetric burn-to-release window explicitly too, matching Functionality #10's existing scope (unclaimed deposits and unreleased burns). State recovery more concretely: a user must recover from their existing wallet seed alone, with no other information. Express a design preference for constructions where the needed claim/entitlement data can be regenerated from on-chain events or state via the user's own keys, over designs that generate an ad hoc secret at deposit or burn time with no on-chain trace, since the latter is unrecoverable the moment that secret is lost however it was backed up. --- RFPs/RFP-021-wrapped-erc20.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 1245ae32..0c976ad3 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -231,15 +231,24 @@ directly from their own deposit, or bought on an AMM from someone else) can burn it and claim the underlying Ethereum asset. Redemption depends only on holding the token, never on the original depositor's credentials. -The credentials-recovery problem is narrower than that, and specific to the -window between depositing on Ethereum and claiming the mint on LEZ: in any -design meeting these requirements, the protocol cannot identify who owns what, -so there is no administrative recovery path if a user loses the credentials -needed to claim their own deposit before it is claimed. This is the largest UX -risk in the RFP and must be designed against rather than disclaimed: a user must -be able to recover every unclaimed deposit of their own from credentials they -already hold and already back up. Requiring users to separately back up new -secrets generated during a deposit is not acceptable. +The credentials-recovery problem is narrower than that, and specific to the two +windows where a claim is outstanding: between depositing on Ethereum and +claiming the mint on LEZ, and between burning on LEZ and claiming the release on +Ethereum. In any design meeting these requirements, the protocol cannot identify +who owns what, so there is no administrative recovery path if a user loses +access to a deposit or burn before it is claimed. This is the largest UX risk in +the RFP and must be designed against rather than disclaimed: a user must be able +to recover every one of their own unclaimed deposits and unreleased burns from +their existing wallet seed alone, with no other information and no separately +backed-up secret. Concretely, if data loss occurs between lock and mint, or +between burn and release, the client must be able to rediscover and re-derive +everything it needs from the user's seed plus on-chain state, with no dependence +on locally-cached state that isn't recoverable that way. A construction where +the claim or entitlement data can be regenerated from on-chain events or state +(for example, re-deriving a proof from a deposit event the user's own keys can +scan for) is preferred over one that generates an ad hoc secret at deposit or +burn time with no on-chain trace, since the latter is unrecoverable the moment +that secret is lost, however it was backed up. ### Token registry and decimal normalisation From 8b3b9f25777a2b2fb9a5386445316a4943a9354b Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:18:12 +1000 Subject: [PATCH 30/69] RFP-021: no off-chain participant should be a required counterparty "Trusted for liveness only: able to decline service" implicitly accepted a design where some off-chain party's cooperation is needed at all, which conflicts with the non-interactive protocol this RFP requires (see Why This Matters: a deposit "does not need a counterparty to be online"). Restate the requirement: the protocol should not depend on any specific off-chain participant, and where one is unavoidable (relaying, proving), that role must be permissionless so a single participant declining never blocks the user, generalising the permissionless-relayer pattern already used for the fee-payer mitigation above. --- RFPs/RFP-021-wrapped-erc20.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 0c976ad3..99f0e88f 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -211,10 +211,16 @@ attestor federations, relayers, or proof-generation services. A user relies only on the correctness of the proof system, the security of the Ethereum network, and the security of the LEZ network. -Any off-chain participant in the design may be trusted for **liveness only**: -able to decline service, but never able to steal, redirect, forge, censor -selectively, or deanonymise. Proposals must identify every such participant and -justify that each is liveness-only. +The protocol should not depend on any specific off-chain participant at all: a +deposit or burn should not need a particular counterparty online to complete, +consistent with the non-interactive design this RFP requires (see Why This +Matters). Where an off-chain participant is unavoidable, for example relaying a +transaction or generating a proof, that role must be permissionless so any +single participant declining to act never blocks the user, and no participant +may be trusted with anything beyond that: never able to steal, redirect, forge, +censor selectively, or deanonymise. Proposals must identify every such +participant and justify that none of them, individually or as a class, can block +a user's deposit or burn from eventually completing. Caps and the freeze authority remain in place as operational safety mechanisms independent of the cryptographic trust model. Note that the freeze authority can From 7c5fc3f73f36275e8b8d09d58e462f3fa3716ef8 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:18:43 +1000 Subject: [PATCH 31/69] RFP-021: state Loss of access opening line directly "A wrapped token does not carry a bridge position with it" reads as a correction to a claim the reader hasn't seen, since nothing earlier in the document uses "bridge position". State the point plainly instead: once minted, the token is ordinary and redeemable by whoever holds it. --- RFPs/RFP-021-wrapped-erc20.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 99f0e88f..46b10ab5 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -231,11 +231,11 @@ documented as such. ### Loss of access -A wrapped token does not carry a bridge position with it: once minted, it is an -ordinary LEZ token, and whoever holds it, however they acquired it (received -directly from their own deposit, or bought on an AMM from someone else) can burn -it and claim the underlying Ethereum asset. Redemption depends only on holding -the token, never on the original depositor's credentials. +Once minted, a wrapped token is an ordinary LEZ token: whoever holds it, however +they acquired it (received directly from their own deposit, or bought on an AMM +from someone else), can burn it and claim the underlying Ethereum asset. +Redemption depends only on holding the token, never on the original depositor's +credentials. The credentials-recovery problem is narrower than that, and specific to the two windows where a claim is outstanding: between depositing on Ethereum and From 38650dc18283cc272c23e2527d2d356a59314099 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:23:21 +1000 Subject: [PATCH 32/69] RFP-021: justify admin-curated registry over permissionless listing Addresses review comment https://github.com/logos-co/rfp/pull/158/changes#r3754572141. The registry section specified admin curation mechanically but never argued for it over a permissionless alternative. Add the rationale: curation catches metadata/decimals errors (accidental or deliberate), blocks scam and impersonation tokens that would otherwise mint an indistinguishable wrapped version, and bounds registry growth and its on-chain read/iteration cost. Note this doesn't presuppose one canonical deployment: because the contracts are open source, multiple entities or DAOs can each run their own instance with their own registry and admin policy, competing on curation quality and the reputation of their specific wrapped tokens. --- RFPs/RFP-021-wrapped-erc20.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 46b10ab5..aa03a69e 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -258,6 +258,36 @@ that secret is lost, however it was backed up. ### Token registry and decimal normalisation +The registry is admin-curated rather than permissionless: anyone can deploy an +ERC-20 on Ethereum, and a bridge that minted a wrapped representation for any +token a depositor names would inherit every failure mode of an open listing +process. Curation defends against several distinct problems a permissionless +registry cannot: + +- **Metadata and configuration errors.** A wrong symbol, name, or decimals value + in the LEZ mint, whether an honest mistake or deliberate, corrupts every + downstream integration that reads that metadata, and is exactly the class of + error the decimals-conversion requirement below exists to catch. Curated + registration is the point at which that check happens. +- **Scam and impersonation tokens.** A permissionless registry lets anyone + deploy a token with a name or symbol crafted to be confused with an + established asset, and have the bridge mint a wrapped version + indistinguishable in a wallet UI from the real thing. Curation is what + prevents the bridge itself from becoming a vector for that. +- **Unbounded registry growth.** Every registered token adds to on-chain state + that the bridge program and its clients must read and iterate over; an + open-ended, permissionless list of approved tokens has no bound on this cost, + where a curated registry does. + +Curation by a single admin authority is not the only way to satisfy these +concerns, and this RFP does not mandate it as the only deployment model. Because +the vault contract and bridge program are open source and anyone can deploy +their own instance, curation also enables competition: multiple entities or DAOs +can each run their own deployment with their own token registry and admin +policy, competing on the quality of curation and the resulting reputation of +their specific wrapped tokens, rather than the ecosystem depending on one +canonical, centrally-curated list. + Each supported ERC-20 is registered individually by the admin authority: its Ethereum contract address, its LEZ wrapped-token mint, its decimals, its permitted transfer amounts, and its per-token caps. ERC-20 tokens do not share a From 01472b5af5d422418a54e21f26a03b01a15ddc22 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:25:24 +1000 Subject: [PATCH 33/69] RFP-021: make finality depth admin-configurable, not fixed Proposals were only required to pick and document one depth. Require a recommended default instead, configurable by the admin authority per deployment, for the same reason the token registry is admin-curated rather than fixed: different deployers may want to strike the latency-versus-reorg-risk balance differently, and a hard-coded depth forecloses that choice. Add this as Functionality #13 (a change to the depth must not invalidate an already-valid claim, consistent with the existing "a valid claim remains valid indefinitely" requirement), and renumber the freeze authority requirement and its two downstream cross-references from #13 to #14. --- RFPs/RFP-021-wrapped-erc20.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index aa03a69e..711498cf 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -307,8 +307,12 @@ Wrapped tokens must not be minted against an Ethereum deposit that a reorg could still remove, and the vault must not release against a LEZ burn that is not yet final. Both directions require a configured finality condition on the source chain. The chosen depth is a direct trade-off between user-facing latency and -reorg risk; proposals must document the depth chosen and the residual risk it -leaves. +reorg risk; proposals must recommend a specific default depth for each direction +and document the residual risk it leaves. The depth must also be configurable by +the admin authority per deployment, for the same reason the token registry is +(see "Token registry and decimal normalisation" above): different deployers may +reasonably want to strike the latency-versus-risk balance differently, and a +fixed, hard-coded depth would foreclose that choice. Once a user's claim is valid it must remain valid indefinitely, since users are expected to delay their own submissions for privacy reasons and must never be @@ -382,7 +386,12 @@ Use FURPS framework. Each numbered item should be a testable statement. authority, bound the maximum value that can be minted or released within a rolling window, as a rate limiter independent of the freeze authority. Cap enforcement must not require identifying individual users. -13. A freeze authority (per RFP-002) can pause minting and/or redemption, either +13. The finality depth required before a deposit may be claimed, and before a + burn may be released, is configurable by the admin authority per deployment, + defaulting to the depth recommended in Design Rationale, "Finality and reorg + protection." A change to the configured depth must not invalidate a claim or + release that was already valid under the previous depth. +14. A freeze authority (per RFP-002) can pause minting and/or redemption, either globally or for a single registered token, on the Ethereum vault and the LEZ bridge program independently. @@ -524,7 +533,7 @@ Use FURPS framework. Each numbered item should be a testable statement. 4. Caps (Functionality #12) bound the maximum value at risk in any rolling window; proposals must document recommended defaults and the reasoning behind them. -5. The freeze authority (Functionality #13) must be exercisable independently on +5. The freeze authority (Functionality #14) must be exercisable independently on each half, so either can be paused without the other being operational or reachable. 6. Soundness of supply: total wrapped supply on LEZ must never exceed the @@ -544,7 +553,7 @@ Use FURPS framework. Each numbered item should be a testable statement. [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)). Proposals must document the chosen migration mechanism and how in-flight deposits and burns are honoured across a migration. -9. The freeze authority (Functionality #13) stops new activity but does not by +9. The freeze authority (Functionality #14) stops new activity but does not by itself recover funds already at risk or resolve deposits and burns left in-flight once a vulnerability in the verification logic is found. Proposals must specify a failsafe strategy for this scenario, constrained as follows: From ed84d2b61a335c67b5326d15f6ddca855b9ffdec Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:28:40 +1000 Subject: [PATCH 34/69] RFP-021: mandate a configurable LEZ-side fee on mint and burn Replace the "no mandated fee" baseline with a mandatory protocol fee on both minting and burning of the wrapped token on LEZ. The rate and denomination are not mandated: proposals choose whether the fee is charged in the wrapped token, native LEZ tokens, or a configurable mix, and the rate is admin-authority configurable per deployment, the same competition rationale already used for the token registry and finality depth (different deployers can compete on sustainability and fee policy). No fee is mandated on the Ethereum side, since the focus is the Logos ecosystem and its privacy-preserving LEZ side; an Ethereum-side fee is left to the proposal if desired. The existing constraint that a fee's value must not fingerprint a transaction carries over and now applies regardless of denomination. Add Functionality #14 as the matching hard requirement, and renumber the freeze authority requirement (and its two downstream cross- references) from #14 to #15. --- RFPs/RFP-021-wrapped-erc20.md | 57 ++++++++++++++++++++++++++++------- 1 file changed, 46 insertions(+), 11 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 711498cf..e7d221ce 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -320,14 +320,43 @@ forced to act promptly to avoid expiry. ### Fee structure -This RFP does not mandate a specific protocol fee rate. Proposals must specify -who pays, when fees are collected, the exact rate, and where fees are routed. A -governance-activatable fee switch with an initial zero rate, gated by the admin -authority per RFP-001, is the recommended baseline, consistent with the pattern -used elsewhere in the Logos RFP set (see [RFP-017](./RFP-017-token-vesting.md), -"Fee structure"). Any fee paid by a user (protocol or relayer) must take a value -that does not distinguish their transaction from others, since a distinctive fee -is itself a fingerprint. +Unlike the pattern used elsewhere in the Logos RFP set (see +[RFP-017](./RFP-017-token-vesting.md), "Fee structure"), this RFP mandates a +protocol fee on both minting (deposit-side) and burning (redemption-side) of the +wrapped token on LEZ. The rate itself is not mandated: it must be configurable +by the admin authority per deployment, for the same reason the token registry +and finality depth are (see "Token registry and decimal normalisation" and +"Finality and reorg protection" above), so different deployers can compete on +sustainability and fee policy rather than being locked into one rate. This RFP +does not mandate a fee on the Ethereum side; the focus here is the Logos +ecosystem and its privacy-preserving LEZ side, and an Ethereum-side protocol fee +is left to the proposal if it chooses to specify one. + +Proposals must specify: + +1. **Denomination.** Whether the fee is charged in the wrapped token itself, in + native LEZ tokens, or a mix of both, with the design rationale for the + choice. Charging in the wrapped token keeps the fee self-contained to the + asset being bridged and requires no separate LEZ balance from the user; + charging in native LEZ tokens routes value to the LEZ token instead and + requires the user (or their relayer) to hold it. Proposals may support more + than one denomination if the admin authority can select between them per + deployment. +2. **Rate.** The initial rate and range, and the mechanism (a + governance-activatable fee switch gated by the admin authority per RFP-001 is + the expected baseline) by which the admin authority adjusts it per + deployment. +3. **Collection point.** Whether the mint-side fee is deducted at claim time, + and the burn-side fee at burn or at release, and how partial amounts (after + fee deduction) interact with the fixed-denomination requirement in "The + privacy requirement, stated precisely," above. +4. **Routing.** The destination of collected fees (protocol treasury, relayer + compensation, burn, or a combination). + +Whatever the denomination and rate, any fee paid by a user (protocol or relayer) +must take a value that does not distinguish their transaction from others, since +a distinctive fee is itself a fingerprint; this constraint applies regardless of +which token the fee is charged in. ## ✅ Scope of Work @@ -391,7 +420,13 @@ Use FURPS framework. Each numbered item should be a testable statement. defaulting to the depth recommended in Design Rationale, "Finality and reorg protection." A change to the configured depth must not invalidate a claim or release that was already valid under the previous depth. -14. A freeze authority (per RFP-002) can pause minting and/or redemption, either +14. A protocol fee is charged on both minting and burning of the wrapped token + on LEZ, in a denomination (wrapped token, native LEZ token, or a + configurable mix, per Design Rationale, "Fee structure") and at a rate + configurable by the admin authority per deployment. No fee is mandated on + the Ethereum side. The fee value must not distinguish a user's transaction + from others, consistent with Functionality #8. +15. A freeze authority (per RFP-002) can pause minting and/or redemption, either globally or for a single registered token, on the Ethereum vault and the LEZ bridge program independently. @@ -533,7 +568,7 @@ Use FURPS framework. Each numbered item should be a testable statement. 4. Caps (Functionality #12) bound the maximum value at risk in any rolling window; proposals must document recommended defaults and the reasoning behind them. -5. The freeze authority (Functionality #14) must be exercisable independently on +5. The freeze authority (Functionality #15) must be exercisable independently on each half, so either can be paused without the other being operational or reachable. 6. Soundness of supply: total wrapped supply on LEZ must never exceed the @@ -553,7 +588,7 @@ Use FURPS framework. Each numbered item should be a testable statement. [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)). Proposals must document the chosen migration mechanism and how in-flight deposits and burns are honoured across a migration. -9. The freeze authority (Functionality #14) stops new activity but does not by +9. The freeze authority (Functionality #15) stops new activity but does not by itself recover funds already at risk or resolve deposits and burns left in-flight once a vulnerability in the verification logic is found. Proposals must specify a failsafe strategy for this scenario, constrained as follows: From 15d4ec101fe68e5ec53197822c50254a61a989df Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:33:28 +1000 Subject: [PATCH 35/69] RFP-021: require chain ID scoping and independent multi-instance deployment Add two Functionality hard requirements the spec had been assuming implicitly. #16: the vault and bridge program must record and check an EVM chain ID as part of proof verification, so the design isn't Ethereum-mainnet-specific and a deposit/registration valid on one chain is never mistakenly accepted on another; this is the security property Soft Requirement 5 (multi-chain support) already presumed but never stated. #17: the same bytecode must be independently deployable by different entities, each with its own configuration (token registry, fee recipients and rates, admin authority, caps, finality depth), with no instance able to reach into another's funds or config; this is the architectural enabler the competition rationale already given for the registry, finality depth, and fee structure depends on, now stated as its own requirement and cross-referenced from where that rationale is first introduced. --- RFPs/RFP-021-wrapped-erc20.md | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index e7d221ce..e19469a6 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -281,12 +281,12 @@ registry cannot: Curation by a single admin authority is not the only way to satisfy these concerns, and this RFP does not mandate it as the only deployment model. Because -the vault contract and bridge program are open source and anyone can deploy -their own instance, curation also enables competition: multiple entities or DAOs -can each run their own deployment with their own token registry and admin -policy, competing on the quality of curation and the resulting reputation of -their specific wrapped tokens, rather than the ecosystem depending on one -canonical, centrally-curated list. +the vault contract and bridge program are open source and independently +deployable (Functionality #17), curation also enables competition: multiple +entities or DAOs can each run their own deployment with their own token registry +and admin policy, competing on the quality of curation and the resulting +reputation of their specific wrapped tokens, rather than the ecosystem depending +on one canonical, centrally-curated list. Each supported ERC-20 is registered individually by the admin authority: its Ethereum contract address, its LEZ wrapped-token mint, its decimals, its @@ -429,6 +429,20 @@ Use FURPS framework. Each numbered item should be a testable statement. 15. A freeze authority (per RFP-002) can pause minting and/or redemption, either globally or for a single registered token, on the Ethereum vault and the LEZ bridge program independently. +16. The vault contract and every token registration it holds are scoped to a + specific EVM chain ID, recorded on both the Ethereum vault and the LEZ + bridge program's registry, and checked as part of proof verification. The + design must not assume Ethereum mainnet is the only source chain: the same + vault contract and LEZ bridge program design must be deployable, unmodified, + against any EVM chain, with proofs and registrations scoped so a deposit or + registration valid for one chain ID is never accepted as valid for another. +17. The vault contract and the LEZ bridge program must be deployable as + independent instances: the same bytecode, deployed separately by different + entities, each with its own independent configuration (token registry, fee + recipients and rates, admin authority, caps, finality depth). One instance's + admin authority must have no privileged access over another instance's + configuration or funds. Document how a client identifies and switches + between deployed instances. #### Usability @@ -654,7 +668,8 @@ Use FURPS framework. Each numbered item should be a testable statement. authority to react to anomalous redemption volume before funds leave the vault. 5. Support for wrapping ERC-20 tokens from additional EVM chains (e.g. Arbitrum, - Base) behind the same LEZ bridge program, reusing the registry and caps. + Base) behind the same LEZ bridge program, reusing the registry and caps, and + building on the chain ID scoping already required by Functionality #16. Consider whether anonymity sets should be shared across source chains to enlarge them. 6. Hardware acceleration as an optional path for users with capable machines, From e29b3928965f9134d98e404874a176e7b54a47d8 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:34:40 +1000 Subject: [PATCH 36/69] RFP-021: fix contradictory bytecode phrasing in requirement #17 "The same bytecode, deployed separately" is not a coherent claim: each deployment necessarily has its own contract instance and state. Restate the actual requirement in plain terms: multiple independent deployments must be able to run concurrently, each with its own configuration, with no deployment able to reach into another's funds or settings. --- RFPs/RFP-021-wrapped-erc20.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index e19469a6..7aa2421c 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -436,13 +436,12 @@ Use FURPS framework. Each numbered item should be a testable statement. vault contract and LEZ bridge program design must be deployable, unmodified, against any EVM chain, with proofs and registrations scoped so a deposit or registration valid for one chain ID is never accepted as valid for another. -17. The vault contract and the LEZ bridge program must be deployable as - independent instances: the same bytecode, deployed separately by different - entities, each with its own independent configuration (token registry, fee - recipients and rates, admin authority, caps, finality depth). One instance's - admin authority must have no privileged access over another instance's - configuration or funds. Document how a client identifies and switches - between deployed instances. +17. The design must allow multiple independent deployments of the vault contract + and LEZ bridge program to run at the same time, each deployed and configured + by a different entity: its own token registry, fee recipients and rates, + admin authority, caps, and finality depth. One deployment's admin authority + must have no privileged access over another deployment's configuration or + funds. Document how a client identifies and switches between deployments. #### Usability From 947e2ee72031aa7f2c5967e6ee609469fa087a6e Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:35:34 +1000 Subject: [PATCH 37/69] RFP-021: fix LEZ program redeployment claim in requirement #17 A LEZ program's identity is its bytecode hash, so it cannot be "redeployed" the way an Ethereum contract can; the prior phrasing implied multiple independent LEZ program deployments, which is not possible. Restate per chain: Ethereum genuinely supports multiple independent vault contract instances, one per deploying entity. LEZ instead requires one program deployment to serve multiple entities, each operating under its own strictly separated configuration (registry, fees, admin authority, caps, finality depth), with no configuration able to reach another's funds or settings. Update the earlier cross-reference in "Token registry and decimal normalisation" to match. --- RFPs/RFP-021-wrapped-erc20.md | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 7aa2421c..ccdf143a 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -281,12 +281,12 @@ registry cannot: Curation by a single admin authority is not the only way to satisfy these concerns, and this RFP does not mandate it as the only deployment model. Because -the vault contract and bridge program are open source and independently -deployable (Functionality #17), curation also enables competition: multiple -entities or DAOs can each run their own deployment with their own token registry -and admin policy, competing on the quality of curation and the resulting -reputation of their specific wrapped tokens, rather than the ecosystem depending -on one canonical, centrally-curated list. +the design is open source, and supports multiple independently configured +entities on both chains (Functionality #17), curation also enables competition: +multiple entities or DAOs can each run their own configuration, with their own +token registry and admin policy, competing on the quality of curation and the +resulting reputation of their specific wrapped tokens, rather than the ecosystem +depending on one canonical, centrally-curated list. Each supported ERC-20 is registered individually by the admin authority: its Ethereum contract address, its LEZ wrapped-token mint, its decimals, its @@ -436,12 +436,17 @@ Use FURPS framework. Each numbered item should be a testable statement. vault contract and LEZ bridge program design must be deployable, unmodified, against any EVM chain, with proofs and registrations scoped so a deposit or registration valid for one chain ID is never accepted as valid for another. -17. The design must allow multiple independent deployments of the vault contract - and LEZ bridge program to run at the same time, each deployed and configured - by a different entity: its own token registry, fee recipients and rates, - admin authority, caps, and finality depth. One deployment's admin authority - must have no privileged access over another deployment's configuration or - funds. Document how a client identifies and switches between deployments. +17. On Ethereum, the design must allow multiple independent instances of the + vault contract to run at the same time, each deployed by a different entity. + On LEZ, where a program's identity is fixed by its bytecode and cannot be + redeployed, the bridge program must instead let multiple entities each + operate under their own independent configuration (token registry, fee + recipients and rates, admin authority, caps, finality depth) within a single + program deployment, with strict separation between them: one entity's + configuration must have no privileged access over another's configuration or + funds, as if each were a fully separate deployment. Document how a client + identifies and switches between configurations, and, on the Ethereum side, + between vault instances. #### Usability From 1bf66bce525fa11332619542f5a339e7d848fc0c Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:36:00 +1000 Subject: [PATCH 38/69] RFP-021: simplify requirement 17 to avoid per-chain deployment mechanics Splitting the requirement into an Ethereum case and a LEZ case pulled in deployment-mechanics detail the requirement doesn't need. State it once, generically: multiple entities operate under independent configuration on the same pair of blockchain programs, with strict separation between them. --- RFPs/RFP-021-wrapped-erc20.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index ccdf143a..a44c57de 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -436,17 +436,13 @@ Use FURPS framework. Each numbered item should be a testable statement. vault contract and LEZ bridge program design must be deployable, unmodified, against any EVM chain, with proofs and registrations scoped so a deposit or registration valid for one chain ID is never accepted as valid for another. -17. On Ethereum, the design must allow multiple independent instances of the - vault contract to run at the same time, each deployed by a different entity. - On LEZ, where a program's identity is fixed by its bytecode and cannot be - redeployed, the bridge program must instead let multiple entities each - operate under their own independent configuration (token registry, fee - recipients and rates, admin authority, caps, finality depth) within a single - program deployment, with strict separation between them: one entity's - configuration must have no privileged access over another's configuration or - funds, as if each were a fully separate deployment. Document how a client - identifies and switches between configurations, and, on the Ethereum side, - between vault instances. +17. The design must let multiple entities each operate under their own + independent configuration (token registry, fee recipients and rates, admin + authority, caps, finality depth) on the same pair of blockchain programs, + with strict separation between them: one entity's configuration must have no + privileged access over another's configuration or funds, as if each were a + fully separate deployment. Document how a client identifies and switches + between configurations. #### Usability From 734ed811ebabcc5c833860128a8e629b3871ac51 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:39:34 +1000 Subject: [PATCH 39/69] RFP-021: don't mandate Solidity, just an EVM smart contract Functionality #1 specified "(Solidity)" as if the language were part of the requirement, which is unnecessarily prescriptive and conflicts with Functionality #16's requirement that the design be deployable against any EVM chain. State the requirement as what it actually is: an EVM smart contract, language unspecified. --- RFPs/RFP-021-wrapped-erc20.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index a44c57de..b201660b 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -366,11 +366,11 @@ Use FURPS framework. Each numbered item should be a testable statement. #### Functionality -01. Implement an Ethereum vault contract (Solidity) that escrows deposits of any - ERC-20 in the supported-token registry, plus native ETH (auto-wrapped to - WETH, ie sends ETH to the canonical WETH contract to immediately receive - WETH). The vault must verify the actual balance delta received and reject - any deposit that does not deliver the expected amount. +01. Implement an EVM smart contract vault that escrows deposits of any ERC-20 in + the supported-token registry, plus native ETH (auto-wrapped to WETH, ie + sends ETH to the canonical WETH contract to immediately receive WETH). The + vault must verify the actual balance delta received and reject any deposit + that does not deliver the expected amount. 02. A deposit must not publish, store, or otherwise reveal its LEZ destination. No Ethereum transaction argument, event, or contract state may identify the account that will receive the wrapped tokens. From 0b7dea8bf191a2b2d463c4033cf038f3ba9b771c Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:40:21 +1000 Subject: [PATCH 40/69] RFP-021: reflect Ether in title, not just ERC-20 Functionality already covers native ETH (auto-wrapped to WETH on deposit) alongside ERC-20 tokens, but the title, H1, and README table entry only mentioned "Wrapped ERC-20". Update all three to "Wrapped ERC-20 and Ether Bridge", and lead the Overview's opening sentence with both assets instead of leaving ETH as a trailing parenthetical. --- RFPs/RFP-021-wrapped-erc20.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index b201660b..075f0ba0 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -1,6 +1,6 @@ --- id: RFP-021 -title: Privacy-Preserving Wrapped ERC-20 Bridge for LEZ +title: Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ tier: L status: open category: Developer Tooling & Infrastructure @@ -15,7 +15,7 @@ dependencies: -# RFP-021 — Privacy-Preserving Wrapped ERC-20 Bridge for LEZ +# RFP-021 — Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ > **Note.** This specification describes an outcome that may benefit the Logos > ecosystem. It is a proposal rather than an instruction. Its requirements @@ -49,8 +49,9 @@ dependencies: ## 🧭 Overview Build a trustless, privacy-preserving lock-and-mint bridge that lets ERC-20 -tokens (and native ETH, wrapped as WETH) held on Ethereum enter LEZ as canonical -wrapped assets, and exit back to Ethereum on redemption. +tokens and native ETH, held on Ethereum, enter LEZ as canonical wrapped assets +(ETH auto-wrapped to WETH on the way in), and exit back to Ethereum on +redemption. An Ethereum-side vault contract escrows deposits. A LEZ-side program mints the corresponding wrapped token once it has cryptographically verified, with no From 5abd67e20edffbc3c09f988f2627b02dbe2eb0f9 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:40:59 +1000 Subject: [PATCH 41/69] RFP-021: trim redundant WETH mechanism explanation "Auto-wrapped to WETH" already states what happens; "ie sends ETH to the canonical WETH contract to immediately receive WETH" restated the same fact mechanically. Keep the requirement and state the reason instead: it lets the vault account for ETH the same way as every other registered ERC-20, with one balance-tracking path instead of two. --- RFPs/RFP-021-wrapped-erc20.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 075f0ba0..c030c6e7 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -368,10 +368,10 @@ Use FURPS framework. Each numbered item should be a testable statement. #### Functionality 01. Implement an EVM smart contract vault that escrows deposits of any ERC-20 in - the supported-token registry, plus native ETH (auto-wrapped to WETH, ie - sends ETH to the canonical WETH contract to immediately receive WETH). The - vault must verify the actual balance delta received and reject any deposit - that does not deliver the expected amount. + the supported-token registry, plus native ETH, auto-wrapped to WETH on + deposit so the vault only ever accounts for ERC-20 balances. The vault must + verify the actual balance delta received and reject any deposit that does + not deliver the expected amount. 02. A deposit must not publish, store, or otherwise reveal its LEZ destination. No Ethereum transaction argument, event, or contract state may identify the account that will receive the wrapped tokens. From 5f7a8f4bdc581d0fc80bb3422637e2cde26dc1c3 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:42:37 +1000 Subject: [PATCH 42/69] RFP-021: stop mandating WETH as the internal ETH accounting mechanism The Overview and Functionality #1/#7 specified that the vault must auto-wrap incoming ETH to WETH and unwrap it on release, an internal implementation choice this RFP has no reason to dictate. State the outcome instead: native ETH deposits and releases are supported alongside ERC-20, and how the contract accounts for ETH internally is left to the proposal. --- RFPs/RFP-021-wrapped-erc20.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index c030c6e7..9b3b0793 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -49,9 +49,8 @@ dependencies: ## 🧭 Overview Build a trustless, privacy-preserving lock-and-mint bridge that lets ERC-20 -tokens and native ETH, held on Ethereum, enter LEZ as canonical wrapped assets -(ETH auto-wrapped to WETH on the way in), and exit back to Ethereum on -redemption. +tokens and native ETH, held on Ethereum, enter LEZ as canonical wrapped assets, +and exit back to Ethereum on redemption. An Ethereum-side vault contract escrows deposits. A LEZ-side program mints the corresponding wrapped token once it has cryptographically verified, with no @@ -368,10 +367,9 @@ Use FURPS framework. Each numbered item should be a testable statement. #### Functionality 01. Implement an EVM smart contract vault that escrows deposits of any ERC-20 in - the supported-token registry, plus native ETH, auto-wrapped to WETH on - deposit so the vault only ever accounts for ERC-20 balances. The vault must - verify the actual balance delta received and reject any deposit that does - not deliver the expected amount. + the supported-token registry, plus native ETH. The vault must verify the + actual balance delta received and reject any deposit that does not deliver + the expected amount. 02. A deposit must not publish, store, or otherwise reveal its LEZ destination. No Ethereum transaction argument, event, or contract state may identify the account that will receive the wrapped tokens. @@ -387,10 +385,10 @@ Use FURPS framework. Each numbered item should be a testable statement. 06. Implement a burn path on the LEZ bridge program that entitles the holder to release the original asset from the Ethereum vault. The burn must not publish, store, or otherwise reveal its Ethereum destination. -07. The Ethereum vault releases the original ERC-20 (or unwrapped ETH, for WETH - redemptions) on cryptographic verification of a valid LEZ burn, using a - RISC0 proof verified natively via a precompile (Groth16 verifier or - equivalent). Each burn may be redeemed at most once. +07. The Ethereum vault releases the original asset (the deposited ERC-20, or + native ETH if the original deposit was ETH) on cryptographic verification of + a valid LEZ burn, using a RISC0 proof verified natively via a precompile + (Groth16 verifier or equivalent). Each burn may be redeemed at most once. 08. The amounts visible on Ethereum must not identify which mint or burn they correspond to. Proposals must state the mechanism chosen (fixed denominations are the expected baseline) and its effect on anonymity-set From 4abd4b0e6287eec815a805f83e896c5a0208219b Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:45:05 +1000 Subject: [PATCH 43/69] RFP-021: require direct ETH deposit and private-state burning State explicitly that a user locking ETH must not be required to convert it to WETH themselves first; the vault accepts native ETH directly, whatever its internal accounting. Add Functionality #7: the wrapped token must be held in and burned from private LEZ state, matching the minting requirement (#4) that already exists. This was previously only implied in Platform Dependencies prose ("redemptions spend from it"), not stated as an enforceable, testable requirement; a design that burns from a public LEZ balance while keeping other transaction contents private did not technically violate anything before this. Renumber Functionality #7 through #17 to #8 through #18 and update all seven downstream cross-references accordingly. --- RFPs/RFP-021-wrapped-erc20.md | 47 ++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 20 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 9b3b0793..4a38b583 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -282,7 +282,7 @@ registry cannot: Curation by a single admin authority is not the only way to satisfy these concerns, and this RFP does not mandate it as the only deployment model. Because the design is open source, and supports multiple independently configured -entities on both chains (Functionality #17), curation also enables competition: +entities on both chains (Functionality #18), curation also enables competition: multiple entities or DAOs can each run their own configuration, with their own token registry and admin policy, competing on the quality of curation and the resulting reputation of their specific wrapped tokens, rather than the ecosystem @@ -367,9 +367,10 @@ Use FURPS framework. Each numbered item should be a testable statement. #### Functionality 01. Implement an EVM smart contract vault that escrows deposits of any ERC-20 in - the supported-token registry, plus native ETH. The vault must verify the - actual balance delta received and reject any deposit that does not deliver - the expected amount. + the supported-token registry, plus native ETH deposited directly: a user + locking ETH must not be required to convert it to WETH or any other ERC-20 + themselves first. The vault must verify the actual balance delta received + and reject any deposit that does not deliver the expected amount. 02. A deposit must not publish, store, or otherwise reveal its LEZ destination. No Ethereum transaction argument, event, or contract state may identify the account that will receive the wrapped tokens. @@ -385,57 +386,63 @@ Use FURPS framework. Each numbered item should be a testable statement. 06. Implement a burn path on the LEZ bridge program that entitles the holder to release the original asset from the Ethereum vault. The burn must not publish, store, or otherwise reveal its Ethereum destination. -07. The Ethereum vault releases the original asset (the deposited ERC-20, or +07. The wrapped token must be held in, and burned from, private LEZ state; a + design where the wrapped token sits in or is burned from a public LEZ + account does not satisfy this RFP, even if the burn transaction's other + contents remain private. Both legs of the token's life on LEZ, minting + (Functionality #4) and burning, are private by construction, not merely by + incidental transaction privacy. +08. The Ethereum vault releases the original asset (the deposited ERC-20, or native ETH if the original deposit was ETH) on cryptographic verification of a valid LEZ burn, using a RISC0 proof verified natively via a precompile (Groth16 verifier or equivalent). Each burn may be redeemed at most once. -08. The amounts visible on Ethereum must not identify which mint or burn they +09. The amounts visible on Ethereum must not identify which mint or burn they correspond to. Proposals must state the mechanism chosen (fixed denominations are the expected baseline) and its effect on anonymity-set size. -09. A user must be able to complete both flows without holding a funded account +10. A user must be able to complete both flows without holding a funded account on either chain, and whoever submits or pays for a transaction on the user's behalf must not thereby learn, or be able to prove, which deposit or burn it corresponds to. That party must not be able to alter the destination or take more than an agreed fee. -10. A user must be able to recover every one of their own unclaimed deposits and +11. A user must be able to recover every one of their own unclaimed deposits and unreleased burns from credentials they already hold, with no dependence on any server-side index and no separately-backed-up secret generated during the flow. This does not extend to the wrapped token itself: once minted, it is an ordinary LEZ token redeemable by whoever holds it, regardless of who made the original deposit. -11. An admin authority (per RFP-001, integrated via the SPEL framework where +12. An admin authority (per RFP-001, integrated via the SPEL framework where applicable to the LEZ side) can register a supported ERC-20 (Ethereum address, LEZ wrapped mint, decimals, permitted amounts, caps) and deregister a token. Registration changes must be mirrored consistently on both sides; document how the two stay in sync and what happens if they temporarily diverge. The registry must reject fee-on-transfer and rebasing tokens. -12. Global and per-token deposit and redemption caps, configurable by the admin +13. Global and per-token deposit and redemption caps, configurable by the admin authority, bound the maximum value that can be minted or released within a rolling window, as a rate limiter independent of the freeze authority. Cap enforcement must not require identifying individual users. -13. The finality depth required before a deposit may be claimed, and before a +14. The finality depth required before a deposit may be claimed, and before a burn may be released, is configurable by the admin authority per deployment, defaulting to the depth recommended in Design Rationale, "Finality and reorg protection." A change to the configured depth must not invalidate a claim or release that was already valid under the previous depth. -14. A protocol fee is charged on both minting and burning of the wrapped token +15. A protocol fee is charged on both minting and burning of the wrapped token on LEZ, in a denomination (wrapped token, native LEZ token, or a configurable mix, per Design Rationale, "Fee structure") and at a rate configurable by the admin authority per deployment. No fee is mandated on the Ethereum side. The fee value must not distinguish a user's transaction - from others, consistent with Functionality #8. -15. A freeze authority (per RFP-002) can pause minting and/or redemption, either + from others, consistent with Functionality #9. +16. A freeze authority (per RFP-002) can pause minting and/or redemption, either globally or for a single registered token, on the Ethereum vault and the LEZ bridge program independently. -16. The vault contract and every token registration it holds are scoped to a +17. The vault contract and every token registration it holds are scoped to a specific EVM chain ID, recorded on both the Ethereum vault and the LEZ bridge program's registry, and checked as part of proof verification. The design must not assume Ethereum mainnet is the only source chain: the same vault contract and LEZ bridge program design must be deployable, unmodified, against any EVM chain, with proofs and registrations scoped so a deposit or registration valid for one chain ID is never accepted as valid for another. -17. The design must let multiple entities each operate under their own +18. The design must let multiple entities each operate under their own independent configuration (token registry, fee recipients and rates, admin authority, caps, finality depth) on the same pair of blockchain programs, with strict separation between them: one entity's configuration must have no @@ -578,10 +585,10 @@ Use FURPS framework. Each numbered item should be a testable statement. 3. A malicious party submitting on a user's behalf must not be able to redirect funds, inflate their fee, or replay the user's submission to a different destination. Test each case explicitly. -4. Caps (Functionality #12) bound the maximum value at risk in any rolling +4. Caps (Functionality #13) bound the maximum value at risk in any rolling window; proposals must document recommended defaults and the reasoning behind them. -5. The freeze authority (Functionality #15) must be exercisable independently on +5. The freeze authority (Functionality #16) must be exercisable independently on each half, so either can be paused without the other being operational or reachable. 6. Soundness of supply: total wrapped supply on LEZ must never exceed the @@ -601,7 +608,7 @@ Use FURPS framework. Each numbered item should be a testable statement. [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)). Proposals must document the chosen migration mechanism and how in-flight deposits and burns are honoured across a migration. -9. The freeze authority (Functionality #15) stops new activity but does not by +9. The freeze authority (Functionality #16) stops new activity but does not by itself recover funds already at risk or resolve deposits and burns left in-flight once a vulnerability in the verification logic is found. Proposals must specify a failsafe strategy for this scenario, constrained as follows: @@ -668,7 +675,7 @@ Use FURPS framework. Each numbered item should be a testable statement. vault. 5. Support for wrapping ERC-20 tokens from additional EVM chains (e.g. Arbitrum, Base) behind the same LEZ bridge program, reusing the registry and caps, and - building on the chain ID scoping already required by Functionality #16. + building on the chain ID scoping already required by Functionality #17. Consider whether anonymity sets should be shared across source chains to enlarge them. 6. Hardware acceleration as an optional path for users with capable machines, From 6e139a60763791bccc144beea436f7c206ffcc67 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:46:18 +1000 Subject: [PATCH 44/69] RFP-021: explain "balance delta" instead of using the term unexplained Functionality #1 used "balance delta" with no explanation before the term's meaning is ever established. State the check plainly: the vault measures how much its own balance actually increased, rather than trusting the amount the depositor claims to send. Update the later fee-on-transfer paragraph to reference this same requirement instead of repeating the jargon term on its own. --- RFPs/RFP-021-wrapped-erc20.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 4a38b583..83233871 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -298,8 +298,8 @@ whose values cannot be represented exactly in the chosen LEZ mint precision. Fee-on-transfer and rebasing ERC-20s break the invariant that the amount deposited equals the amount mintable. The registry must reject them, and the -vault must verify the actual balance delta on deposit rather than trusting the -requested amount. +vault must measure the deposit by how much its own balance actually increased, +rather than trusting the requested amount, per Functionality #1. ### Finality and reorg protection @@ -369,8 +369,10 @@ Use FURPS framework. Each numbered item should be a testable statement. 01. Implement an EVM smart contract vault that escrows deposits of any ERC-20 in the supported-token registry, plus native ETH deposited directly: a user locking ETH must not be required to convert it to WETH or any other ERC-20 - themselves first. The vault must verify the actual balance delta received - and reject any deposit that does not deliver the expected amount. + themselves first. The vault must measure how much its own balance actually + increased by (before versus after the transfer), not trust the amount the + depositor claims to send, and reject any deposit that does not deliver the + expected amount. 02. A deposit must not publish, store, or otherwise reveal its LEZ destination. No Ethereum transaction argument, event, or contract state may identify the account that will receive the wrapped tokens. From 9b21b2ffc3302e9d87228919c0cc51dfcbf58575 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:46:52 +1000 Subject: [PATCH 45/69] RFP-021: remove obvious balance-check statement from Functionality #1 Stating that the vault must measure its own balance increase rather than trust the claimed deposit amount is basic smart-contract hygiene, not something this RFP needs to spell out as a requirement; it only made the sentence longer without adding information. The specific, non-obvious case that does need stating, fee-on-transfer and rebasing tokens breaking this assumption, remains in "Token registry and decimal normalisation". --- RFPs/RFP-021-wrapped-erc20.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 83233871..83c4a7d4 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -299,7 +299,7 @@ whose values cannot be represented exactly in the chosen LEZ mint precision. Fee-on-transfer and rebasing ERC-20s break the invariant that the amount deposited equals the amount mintable. The registry must reject them, and the vault must measure the deposit by how much its own balance actually increased, -rather than trusting the requested amount, per Functionality #1. +rather than trusting the requested amount. ### Finality and reorg protection @@ -369,10 +369,7 @@ Use FURPS framework. Each numbered item should be a testable statement. 01. Implement an EVM smart contract vault that escrows deposits of any ERC-20 in the supported-token registry, plus native ETH deposited directly: a user locking ETH must not be required to convert it to WETH or any other ERC-20 - themselves first. The vault must measure how much its own balance actually - increased by (before versus after the transfer), not trust the amount the - depositor claims to send, and reject any deposit that does not deliver the - expected amount. + themselves first. 02. A deposit must not publish, store, or otherwise reveal its LEZ destination. No Ethereum transaction argument, event, or contract state may identify the account that will receive the wrapped tokens. From 01e7d9d2917a8029127b6be2db2607df3cfe6005 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 14:53:11 +1000 Subject: [PATCH 46/69] RFP-021: stop mandating RISC0 for Ethereum-side verification RISC0 is a genuine, unavoidable dependency on the LEZ side, since LEZ itself runs on RISC0, so LEZ-side proving requirements correctly keep mentioning it. But several places also mandated RISC0-specific constructions (a Groth16 precompile, "this RFP specifies RISC0... not a candidate for alternative proof systems") for the Ethereum-side verification, which is a design choice this RFP has no reason to dictate. Generalize Functionality #3 and #8, Usability #4, the Out of Scope RISC0 bullets, and Platform Dependencies' "RISC0 zkVM" section to state the LEZ-side dependency as fact while leaving the Ethereum-side proof system to the proposal. RFP-021: support public and private LEZ accounts for both mint and burn Functionality #4 and #7 previously mandated private-state-only minting and burning. Change this to a choice: both flows must support a private or a public LEZ account as the destination/source, at the user's choice, rather than forcing private accounts exclusively. Add a new Usability requirement that the mini-app and CLI default to inviting the user toward the private path (pre-selected, public path needs an explicit action), consistent with the existing Privacy Preservation "default configuration must be private" requirement. Update the Platform Dependencies "Private LEZ account state" section to match. RFP-021: require deposits and burns to secretly commit to their destination Add a new Bridge Security hard requirement: a deposit and a burn must each secretly commit to the destination on the other chain, so a claim can only be completed by whoever holds the originating seed, and no information beyond that seed, however it leaks, from the transaction itself, public state, or any party in the flow, can let someone else construct a valid claim. This closes a gap the earlier destination- hiding requirements (Functionality #2, #6) didn't fully cover: hiding a destination from observers is not the same as cryptographically binding the claim to it. --- RFPs/RFP-021-wrapped-erc20.md | 173 +++++++++++++++++++--------------- 1 file changed, 95 insertions(+), 78 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 83c4a7d4..e0500a2a 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -374,27 +374,26 @@ Use FURPS framework. Each numbered item should be a testable statement. No Ethereum transaction argument, event, or contract state may identify the account that will receive the wrapped tokens. 03. Implement a LEZ bridge program that mints the corresponding wrapped token on - cryptographic verification of a valid Ethereum deposit, using RISC0 proofs - of Ethereum consensus and state verified in-program. Verification must + cryptographic verification of a valid Ethereum deposit. Verification must require no trusted party. -04. Wrapped tokens are minted into private LEZ state by default, so that neither - the recipient nor the balance is publicly visible. +04. Minting must support both a private LEZ account and a public LEZ account as + the destination, at the depositor's choice; the design must not restrict + minting to private accounts only. 05. Each deposit may be claimed at most once. A repeat claim must be rejected deterministically, without minting, and without revealing which deposit it referred to. 06. Implement a burn path on the LEZ bridge program that entitles the holder to release the original asset from the Ethereum vault. The burn must not publish, store, or otherwise reveal its Ethereum destination. -07. The wrapped token must be held in, and burned from, private LEZ state; a - design where the wrapped token sits in or is burned from a public LEZ - account does not satisfy this RFP, even if the burn transaction's other - contents remain private. Both legs of the token's life on LEZ, minting - (Functionality #4) and burning, are private by construction, not merely by - incidental transaction privacy. +07. Burning must support the wrapped token being held in, and burned from, + either a private or a public LEZ account, at the holder's choice; the design + must not restrict burning to private accounts only. Where a burn involves a + private account, the burn must not thereby reveal its Ethereum destination + (Functionality #6). 08. The Ethereum vault releases the original asset (the deposited ERC-20, or native ETH if the original deposit was ETH) on cryptographic verification of - a valid LEZ burn, using a RISC0 proof verified natively via a precompile - (Groth16 verifier or equivalent). Each burn may be redeemed at most once. + a valid LEZ burn, verified natively on Ethereum. Each burn may be redeemed + at most once. 09. The amounts visible on Ethereum must not identify which mint or burn they correspond to. Proposals must state the mechanism chosen (fixed denominations are the expected baseline) and its effect on anonymity-set @@ -467,9 +466,9 @@ Use FURPS framework. Each numbered item should be a testable statement. a **Logos module accompanied by a Logos Core headless CLI/daemon**, runnable standalone, supporting configurable RPC endpoints for both chains, configurable finality depth, structured logging, and a clean shutdown path. - Proposals must integrate mature RISC0 implementations (e.g. Zisk) rather than - reimplementing zero-knowledge primitives. Document the operator journey - end-to-end: install, configure, run, monitor. + Proposals must integrate mature, audited proof-system implementations rather + than reimplementing zero-knowledge primitives from scratch. Document the + operator journey end-to-end: install, configure, run, monitor. 5. Provide an IDL for the LEZ bridge program using the [SPEL framework](https://github.com/logos-co/spel). 6. Before any privacy-sensitive submission, the mini-app and CLI must show the @@ -477,11 +476,16 @@ Use FURPS framework. Each numbered item should be a testable statement. falls below a configurable threshold. Where delaying a submission improves privacy, the client must default to doing so rather than submitting immediately, with the user able to inspect and override. -7. Documentation and UI must clearly explain what is public and what is private +7. Although minting and burning both support public LEZ accounts (Functionality + #4, #7), the mini-app and CLI must default to inviting the user to mint into, + and burn from, a private account: the private path is the pre-selected option + in the flow, and choosing the public path instead requires an explicit + action, consistent with Privacy Preservation #8. +8. Documentation and UI must clearly explain what is public and what is private at each step on both chains, in the manner of [RFP-004](./RFP-004-privacy-preserving-dex.md), so users can judge their own exposure. -8. Return clear, actionable error messages for all failure modes: unsupported +9. Return clear, actionable error messages for all failure modes: unsupported token, invalid amount, cap exceeded, verification failure, insufficient finality, already claimed, and program or per-token frozen. Error messages must not reveal which deposit or burn a failed attempt referred to. @@ -574,54 +578,63 @@ Use FURPS framework. Each numbered item should be a testable statement. #### + Bridge Security -1. Proof verification must be deterministic and independently verifiable. Both - the LEZ program and the Ethereum vault must reject invalid proofs, tested - with incorrect public inputs, proofs for incorrect chain state, tampered - headers, and replayed proofs. -2. Any off-chain component must independently derive chain state from the source - chain rather than accepting data supplied by a third party without - verification. -3. A malicious party submitting on a user's behalf must not be able to redirect - funds, inflate their fee, or replay the user's submission to a different - destination. Test each case explicitly. -4. Caps (Functionality #13) bound the maximum value at risk in any rolling - window; proposals must document recommended defaults and the reasoning behind - them. -5. The freeze authority (Functionality #16) must be exercisable independently on - each half, so either can be paused without the other being operational or - reachable. -6. Soundness of supply: total wrapped supply on LEZ must never exceed the - vault's holdings. Provide tests attempting to mint without a valid deposit, - mint twice from one deposit, and release without a valid burn. -7. User-facing documentation must state the trustless verification model and the - liveness-only role of any off-chain participant (see Design Rationale, "Trust - model"). -8. The verifier (the LEZ bridge program and the Ethereum vault's proof - verification logic) must be deployed as an immutable program with an explicit - migration path (deploy a new version, drain and redirect to it) in preference - to an upgradeable contract governed by a mutable key. An upgradeable verifier - carries two risks this eliminates by construction: a stolen or misused - upgrade key substituting malicious logic, and a legitimate, authorised - upgrade shipping a catastrophic bug, the latter being the documented cause of - real bridge losses (see Why This Matters and - [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)). - Proposals must document the chosen migration mechanism and how in-flight - deposits and burns are honoured across a migration. -9. The freeze authority (Functionality #16) stops new activity but does not by - itself recover funds already at risk or resolve deposits and burns left - in-flight once a vulnerability in the verification logic is found. Proposals - must specify a failsafe strategy for this scenario, constrained as follows: - the failsafe must not become a backdoor, meaning any recovery must still be - claimed by the depositor or burner proving their own entitlement, the same - way an ordinary claim or redemption works (see Design Rationale, "Trust - model" and "Loss of access"), not by an admin authority or any other party - identifying who owns what and redirecting funds on their behalf; it must not - be able to mint, redirect, or release funds to any destination other than the - address or account the proof specifies; and it must not be able to act on - funds beyond what a specific, proven vulnerability put at risk. If no - mechanism satisfying these constraints is achievable, the proposal must - instead document explicitly why a failsafe should not be implemented, and - what happens to affected funds and in-flight positions in its absence. +01. Proof verification must be deterministic and independently verifiable. Both + the LEZ program and the Ethereum vault must reject invalid proofs, tested + with incorrect public inputs, proofs for incorrect chain state, tampered + headers, and replayed proofs. +02. Any off-chain component must independently derive chain state from the + source chain rather than accepting data supplied by a third party without + verification. +03. A malicious party submitting on a user's behalf must not be able to redirect + funds, inflate their fee, or replay the user's submission to a different + destination. Test each case explicitly. +04. A deposit and a burn must each secretly commit to the destination on the + other chain, so that the claim can only be completed by whoever holds the + seed or credentials that produced the commitment. It must not be possible to + steal a claim from any information that leaks beyond that seed: not the + deposit or burn transaction itself, not any public or observable state, and + not any party the flow depends on (see Functionality #2, #6). Test that an + adversary who observes everything public about a deposit or burn, but does + not hold the originating seed, cannot construct a valid claim for a + different destination. +05. Caps (Functionality #13) bound the maximum value at risk in any rolling + window; proposals must document recommended defaults and the reasoning + behind them. +06. The freeze authority (Functionality #16) must be exercisable independently + on each half, so either can be paused without the other being operational or + reachable. +07. Soundness of supply: total wrapped supply on LEZ must never exceed the + vault's holdings. Provide tests attempting to mint without a valid deposit, + mint twice from one deposit, and release without a valid burn. +08. User-facing documentation must state the trustless verification model and + the liveness-only role of any off-chain participant (see Design Rationale, + "Trust model"). +09. The verifier (the LEZ bridge program and the Ethereum vault's proof + verification logic) must be deployed as an immutable program with an + explicit migration path (deploy a new version, drain and redirect to it) in + preference to an upgradeable contract governed by a mutable key. An + upgradeable verifier carries two risks this eliminates by construction: a + stolen or misused upgrade key substituting malicious logic, and a + legitimate, authorised upgrade shipping a catastrophic bug, the latter being + the documented cause of real bridge losses (see Why This Matters and + [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)). + Proposals must document the chosen migration mechanism and how in-flight + deposits and burns are honoured across a migration. +10. The freeze authority (Functionality #16) stops new activity but does not by + itself recover funds already at risk or resolve deposits and burns left + in-flight once a vulnerability in the verification logic is found. Proposals + must specify a failsafe strategy for this scenario, constrained as follows: + the failsafe must not become a backdoor, meaning any recovery must still be + claimed by the depositor or burner proving their own entitlement, the same + way an ordinary claim or redemption works (see Design Rationale, "Trust + model" and "Loss of access"), not by an admin authority or any other party + identifying who owns what and redirecting funds on their behalf; it must not + be able to mint, redirect, or release funds to any destination other than + the address or account the proof specifies; and it must not be able to act + on funds beyond what a specific, proven vulnerability put at risk. If no + mechanism satisfying these constraints is achievable, the proposal must + instead document explicitly why a failsafe should not be implemented, and + what happens to affected funds and in-flight positions in its absence. #### + Privacy Preservation @@ -703,12 +716,12 @@ The following are explicitly excluded from this RFP: mechanisms. Voluntary user-held viewing keys are Soft Requirement #3; any capability allowing a third party to deanonymise a user without their consent is contrary to the design and out of scope. -- Circuit optimization or custom RISC0 accelerators: proposals should leverage - mature existing RISC0 implementations (e.g. Zisk) rather than implementing - novel circuits or optimization techniques. -- Alternative proof systems (e.g. other zkVMs): this RFP specifies RISC0. If - future RISC0 versions or alternative systems become preferable, that is a - candidate for a future update or new RFP. +- Circuit optimisation or custom zkVM accelerators for the LEZ side: LEZ itself + runs on RISC0, so proposals should leverage mature existing implementations + (e.g. Zisk) for LEZ-side proving rather than implementing novel circuits or + optimisation techniques. This RFP does not mandate a specific proof system for + verifying LEZ state and events on Ethereum; that choice is left to the + proposal. - Price feeds for wrapped assets. Once a token is wrapped, pricing it is the responsibility of the oracle stack ([RFP-019](./RFP-019-twap-oracle.md), [RFP-020](./RFP-020-redstone-oracle-adaptor.md)), not this bridge. @@ -742,17 +755,21 @@ provides; proposals pursuing that path must state what extension is needed. #### Private LEZ account state -Wrapped tokens are minted into private LEZ state, and redemptions spend from it. -The privacy guarantees depend on this: minting into a public account exposes the -recipient immediately. Proposals must state which LEZ private-state primitives -they rely on and their maturity. +Minting and burning must both support private LEZ accounts (Functionality #4, +#7), and the privacy guarantees (P1, P2) apply when a user chooses that path: +minting into a public account instead exposes the recipient immediately, which +is the user's choice to make, not a gap in the design. Proposals must state +which LEZ private-state primitives they rely on and their maturity. #### RISC0 zkVM -The bridge verifies proofs of consensus and state in-program on LEZ and natively -on Ethereum. This requires RISC0, a production-ready zkVM. Proposals must +The bridge verifies proofs of consensus and state in-program on LEZ. Because LEZ +itself runs on RISC0, a production-ready zkVM, this leg of the design is a +LEZ-runtime dependency rather than a choice the proposal makes; proposals must leverage mature RISC0 implementations (e.g. -[Zisk](https://github.com/risc0/zisk)) rather than building custom circuits. +[Zisk](https://github.com/risc0/zisk)) for LEZ-side proving rather than building +custom circuits. This RFP does not mandate a specific proof system for the +corresponding native verification on Ethereum. ### Soft dependencies From 241f2bed0a358a96be981739e5a1e87850ff2b13 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 15:23:54 +1000 Subject: [PATCH 47/69] RFP-021: remove diff-referencing clauses and one requirement Three cleanups to Functionality: - Removed "the design must not restrict minting/burning to private accounts only" from #4 and #6 (old #4/#7). These clauses only made sense as a diff against the previous private-only wording; stated on their own they're confusing, since nothing established a private-only restriction to argue against. - Removed the old #5 (repeat-claim rejection) entirely, per direction. - Removed "where a burn involves a private account, the burn must not thereby reveal its Ethereum destination" from burn support (old #7): redundant with the destination-hiding requirement on the burn path itself (now #5), and wrongly implied that requirement only applies when burning from a private account, when it applies to every burn. Renumbered Functionality #5 through #18 down to #4 through #17 accordingly, and fixed all eight downstream cross-references across Bridge Security, Soft Requirements, and Platform Dependencies. --- RFPs/RFP-021-wrapped-erc20.md | 53 +++++++++++++++-------------------- 1 file changed, 23 insertions(+), 30 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index e0500a2a..cdbc5969 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -282,7 +282,7 @@ registry cannot: Curation by a single admin authority is not the only way to satisfy these concerns, and this RFP does not mandate it as the only deployment model. Because the design is open source, and supports multiple independently configured -entities on both chains (Functionality #18), curation also enables competition: +entities on both chains (Functionality #17), curation also enables competition: multiple entities or DAOs can each run their own configuration, with their own token registry and admin policy, competing on the quality of curation and the resulting reputation of their specific wrapped tokens, rather than the ecosystem @@ -377,70 +377,63 @@ Use FURPS framework. Each numbered item should be a testable statement. cryptographic verification of a valid Ethereum deposit. Verification must require no trusted party. 04. Minting must support both a private LEZ account and a public LEZ account as - the destination, at the depositor's choice; the design must not restrict - minting to private accounts only. -05. Each deposit may be claimed at most once. A repeat claim must be rejected - deterministically, without minting, and without revealing which deposit it - referred to. -06. Implement a burn path on the LEZ bridge program that entitles the holder to + the destination, at the depositor's choice. +05. Implement a burn path on the LEZ bridge program that entitles the holder to release the original asset from the Ethereum vault. The burn must not publish, store, or otherwise reveal its Ethereum destination. -07. Burning must support the wrapped token being held in, and burned from, - either a private or a public LEZ account, at the holder's choice; the design - must not restrict burning to private accounts only. Where a burn involves a - private account, the burn must not thereby reveal its Ethereum destination - (Functionality #6). -08. The Ethereum vault releases the original asset (the deposited ERC-20, or +06. Burning must support the wrapped token being held in, and burned from, + either a private or a public LEZ account, at the holder's choice. +07. The Ethereum vault releases the original asset (the deposited ERC-20, or native ETH if the original deposit was ETH) on cryptographic verification of a valid LEZ burn, verified natively on Ethereum. Each burn may be redeemed at most once. -09. The amounts visible on Ethereum must not identify which mint or burn they +08. The amounts visible on Ethereum must not identify which mint or burn they correspond to. Proposals must state the mechanism chosen (fixed denominations are the expected baseline) and its effect on anonymity-set size. -10. A user must be able to complete both flows without holding a funded account +09. A user must be able to complete both flows without holding a funded account on either chain, and whoever submits or pays for a transaction on the user's behalf must not thereby learn, or be able to prove, which deposit or burn it corresponds to. That party must not be able to alter the destination or take more than an agreed fee. -11. A user must be able to recover every one of their own unclaimed deposits and +10. A user must be able to recover every one of their own unclaimed deposits and unreleased burns from credentials they already hold, with no dependence on any server-side index and no separately-backed-up secret generated during the flow. This does not extend to the wrapped token itself: once minted, it is an ordinary LEZ token redeemable by whoever holds it, regardless of who made the original deposit. -12. An admin authority (per RFP-001, integrated via the SPEL framework where +11. An admin authority (per RFP-001, integrated via the SPEL framework where applicable to the LEZ side) can register a supported ERC-20 (Ethereum address, LEZ wrapped mint, decimals, permitted amounts, caps) and deregister a token. Registration changes must be mirrored consistently on both sides; document how the two stay in sync and what happens if they temporarily diverge. The registry must reject fee-on-transfer and rebasing tokens. -13. Global and per-token deposit and redemption caps, configurable by the admin +12. Global and per-token deposit and redemption caps, configurable by the admin authority, bound the maximum value that can be minted or released within a rolling window, as a rate limiter independent of the freeze authority. Cap enforcement must not require identifying individual users. -14. The finality depth required before a deposit may be claimed, and before a +13. The finality depth required before a deposit may be claimed, and before a burn may be released, is configurable by the admin authority per deployment, defaulting to the depth recommended in Design Rationale, "Finality and reorg protection." A change to the configured depth must not invalidate a claim or release that was already valid under the previous depth. -15. A protocol fee is charged on both minting and burning of the wrapped token +14. A protocol fee is charged on both minting and burning of the wrapped token on LEZ, in a denomination (wrapped token, native LEZ token, or a configurable mix, per Design Rationale, "Fee structure") and at a rate configurable by the admin authority per deployment. No fee is mandated on the Ethereum side. The fee value must not distinguish a user's transaction - from others, consistent with Functionality #9. -16. A freeze authority (per RFP-002) can pause minting and/or redemption, either + from others, consistent with Functionality #8. +15. A freeze authority (per RFP-002) can pause minting and/or redemption, either globally or for a single registered token, on the Ethereum vault and the LEZ bridge program independently. -17. The vault contract and every token registration it holds are scoped to a +16. The vault contract and every token registration it holds are scoped to a specific EVM chain ID, recorded on both the Ethereum vault and the LEZ bridge program's registry, and checked as part of proof verification. The design must not assume Ethereum mainnet is the only source chain: the same vault contract and LEZ bridge program design must be deployable, unmodified, against any EVM chain, with proofs and registrations scoped so a deposit or registration valid for one chain ID is never accepted as valid for another. -18. The design must let multiple entities each operate under their own +17. The design must let multiple entities each operate under their own independent configuration (token registry, fee recipients and rates, admin authority, caps, finality depth) on the same pair of blockchain programs, with strict separation between them: one entity's configuration must have no @@ -593,14 +586,14 @@ Use FURPS framework. Each numbered item should be a testable statement. seed or credentials that produced the commitment. It must not be possible to steal a claim from any information that leaks beyond that seed: not the deposit or burn transaction itself, not any public or observable state, and - not any party the flow depends on (see Functionality #2, #6). Test that an + not any party the flow depends on (see Functionality #2, #5). Test that an adversary who observes everything public about a deposit or burn, but does not hold the originating seed, cannot construct a valid claim for a different destination. -05. Caps (Functionality #13) bound the maximum value at risk in any rolling +05. Caps (Functionality #12) bound the maximum value at risk in any rolling window; proposals must document recommended defaults and the reasoning behind them. -06. The freeze authority (Functionality #16) must be exercisable independently +06. The freeze authority (Functionality #15) must be exercisable independently on each half, so either can be paused without the other being operational or reachable. 07. Soundness of supply: total wrapped supply on LEZ must never exceed the @@ -620,7 +613,7 @@ Use FURPS framework. Each numbered item should be a testable statement. [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)). Proposals must document the chosen migration mechanism and how in-flight deposits and burns are honoured across a migration. -10. The freeze authority (Functionality #16) stops new activity but does not by +10. The freeze authority (Functionality #15) stops new activity but does not by itself recover funds already at risk or resolve deposits and burns left in-flight once a vulnerability in the verification logic is found. Proposals must specify a failsafe strategy for this scenario, constrained as follows: @@ -687,7 +680,7 @@ Use FURPS framework. Each numbered item should be a testable statement. vault. 5. Support for wrapping ERC-20 tokens from additional EVM chains (e.g. Arbitrum, Base) behind the same LEZ bridge program, reusing the registry and caps, and - building on the chain ID scoping already required by Functionality #17. + building on the chain ID scoping already required by Functionality #16. Consider whether anonymity sets should be shared across source chains to enlarge them. 6. Hardware acceleration as an optional path for users with capable machines, @@ -756,7 +749,7 @@ provides; proposals pursuing that path must state what extension is needed. #### Private LEZ account state Minting and burning must both support private LEZ accounts (Functionality #4, -#7), and the privacy guarantees (P1, P2) apply when a user chooses that path: +#6), and the privacy guarantees (P1, P2) apply when a user chooses that path: minting into a public account instead exposes the recipient immediately, which is the user's choice to make, not a gap in the design. Proposals must state which LEZ private-state primitives they rely on and their maturity. From f5de940c3330c0e05c37a1e9f07407b7449eb1e6 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 15:51:51 +1000 Subject: [PATCH 48/69] RFP-021: add gas-token bootstrapping as a soft requirement Add Soft Requirement 8: an ERC-20 on Ethereum representing a Logos zone's native gas token, where minting it is actually a release of gas token already escrowed on the LEZ side, the inverse of this RFP's primary deposit/mint flow. The goal is letting a user with no existing holdings on the zone acquire gas via the bridge, so they are never blocked from their first transaction. Since this direction has no external market minting new supply on Ethereum (unlike a wrapped external asset), require proposals to either treat it symmetrically to the primary flow and document how the Ethereum-side escrow is funded and replenished, or document why it isn't achievable and what alternative bootstrapping mechanism would be needed instead. --- RFPs/RFP-021-wrapped-erc20.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index cdbc5969..5bb8fe2e 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -688,6 +688,21 @@ Use FURPS framework. Each numbered item should be a testable statement. 7. Design the proof-system components as pluggable, so that future zkVM improvements, proof compression, or hardware acceleration can be adopted without restructuring the vault or the bridge program. +8. **Gas-token bootstrapping.** An ERC-20 on Ethereum representing the native + gas token of a given Logos zone, where "minting" that ERC-20 is actually a + release of native gas token already escrowed on the LEZ side, and burning it + on Ethereum mints it back on LEZ, the inverse of this RFP's primary flow. The + goal is to let a user with no existing holdings on the zone acquire its gas + token via the bridge from Ethereum, so they are never blocked from their + first transaction by not already holding gas. If achievable, proposals should + treat this as symmetric to the primary flow (same privacy, caps, freeze + authority, and finality requirements apply to the gas-token leg) and document + how the Ethereum-side escrow of native gas token is funded and replenished, + since unlike a wrapped external asset, there is no independent market minting + new supply of it on Ethereum. If not achievable within this RFP's design, or + only achievable with materially different trust or custody assumptions than + the primary flow, document why, and what alternative bootstrapping mechanism + (a faucet, gas sponsorship, meta-transactions) would need to exist instead. ### Out of Scope From 9e341134d03787dc49198a504254c82a26f5f03b Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 11 Aug 2026 17:39:13 +1000 Subject: [PATCH 49/69] RFP-021: address full batch of PR review comments Functionality: - Simplify #7 (Ethereum release): drop the redundant "if the original deposit was ETH" clause and "each burn may be redeemed at most once" restatement. - Delete the old #9 (funded-account / relayer-learns-nothing item); its substance is now folded into Bridge Security. - #11 (registry): replace the sync/divergence language with a plain documentation requirement covering registration changes and delisting. - #14 (fee): "can be charged" instead of "is charged", drop the redundant "no fee mandated on Ethereum" sentence, note the admin can set either fee to zero. - #15/#16 (chain ID, multi-config): rewrite around a precise program-refers-to-contract-refers-to-zone model instead of vague "vault contract... Ethereum mainnet" language that didn't fit the LEZ side and ignored testnets. #16 now allows "same or different pairs" of blockchain programs. Usability: - #1 rewritten around a Logos core module used by multiple Logos ui modules, rather than an SDK. - #2 (mini-app) trimmed to drop build/deployment detail that belongs in Supportability. - CLI item removed from Usability (moved conceptually to Supportability doc-packet requirements). - New #5: the three privacy correlation mitigations (amount, timing, fee payer) must be enabled by default, with a leak indicator and recommended parameters, replacing the narrower anonymity-set-warning item. Supportability: - Testnet wording corrected (LEZ testnet, not devnet/testnet). - Doc packet items reference "the core module" instead of "the SDK". - New deployer doc-packet item, matching the pattern of the SDK and CLI doc-packet items, covering how an entity stands up its own configured deployment. - Figma-designs item removed. - Audit item simplified to "the audit report must be published", dropping the Chainalysis justification aside. - New item requiring the Logos Ethereum core module (with verified proxy features), RPC/target switching in the UI, the Lambda Prize wallet SDK, RFP-001/002 outputs for admin and freeze authorities, compatibility with the existing LEZ token program and ATA derivation, catalog publication, and standard Logos GitHub Actions. Bridge Security: - Removed the standalone "off-chain component must independently derive chain state" item. - Merged the claim-theft-resistance requirement into the malicious- relayer item, since they covered overlapping ground. Platform Dependencies: - Trimmed the LP-0013, "Private LEZ account state", and "RISC0 zkVM" subsections to their core dependency statements. - Moved "Event emission (LP-0012)" from Soft to Hard dependencies, removing the now-empty "Soft dependencies" heading. Out of Scope: removed the BTC/XMR/ZEC, mobile/in-browser proving, and price-feed bullets (now covered elsewhere or no longer needed as exclusions). Renumbered Functionality, Bridge Security, and their downstream cross-references throughout to stay sequential and accurate. --- RFPs/RFP-021-wrapped-erc20.md | 283 ++++++++++++++++------------------ 1 file changed, 133 insertions(+), 150 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 5bb8fe2e..dcc4a485 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -282,7 +282,7 @@ registry cannot: Curation by a single admin authority is not the only way to satisfy these concerns, and this RFP does not mandate it as the only deployment model. Because the design is open source, and supports multiple independently configured -entities on both chains (Functionality #17), curation also enables competition: +entities on both chains (Functionality #16), curation also enables competition: multiple entities or DAOs can each run their own configuration, with their own token registry and admin policy, competing on the quality of curation and the resulting reputation of their specific wrapped tokens, rather than the ecosystem @@ -384,101 +384,95 @@ Use FURPS framework. Each numbered item should be a testable statement. 06. Burning must support the wrapped token being held in, and burned from, either a private or a public LEZ account, at the holder's choice. 07. The Ethereum vault releases the original asset (the deposited ERC-20, or - native ETH if the original deposit was ETH) on cryptographic verification of - a valid LEZ burn, verified natively on Ethereum. Each burn may be redeemed - at most once. + native ETH) on cryptographic verification of a valid LEZ burn, verified + natively on Ethereum. 08. The amounts visible on Ethereum must not identify which mint or burn they correspond to. Proposals must state the mechanism chosen (fixed denominations are the expected baseline) and its effect on anonymity-set size. -09. A user must be able to complete both flows without holding a funded account - on either chain, and whoever submits or pays for a transaction on the user's - behalf must not thereby learn, or be able to prove, which deposit or burn it - corresponds to. That party must not be able to alter the destination or take - more than an agreed fee. -10. A user must be able to recover every one of their own unclaimed deposits and +09. A user must be able to recover every one of their own unclaimed deposits and unreleased burns from credentials they already hold, with no dependence on any server-side index and no separately-backed-up secret generated during the flow. This does not extend to the wrapped token itself: once minted, it is an ordinary LEZ token redeemable by whoever holds it, regardless of who made the original deposit. -11. An admin authority (per RFP-001, integrated via the SPEL framework where +10. An admin authority (per RFP-001, integrated via the SPEL framework where applicable to the LEZ side) can register a supported ERC-20 (Ethereum address, LEZ wrapped mint, decimals, permitted amounts, caps) and deregister - a token. Registration changes must be mirrored consistently on both sides; - document how the two stay in sync and what happens if they temporarily - diverge. The registry must reject fee-on-transfer and rebasing tokens. -12. Global and per-token deposit and redemption caps, configurable by the admin + a token. Documentation needs to be provided to handle registration changes + with minimum impact for users, including delisting of a token. The registry + must reject fee-on-transfer and rebasing tokens. +11. Global and per-token deposit and redemption caps, configurable by the admin authority, bound the maximum value that can be minted or released within a rolling window, as a rate limiter independent of the freeze authority. Cap enforcement must not require identifying individual users. -13. The finality depth required before a deposit may be claimed, and before a +12. The finality depth required before a deposit may be claimed, and before a burn may be released, is configurable by the admin authority per deployment, defaulting to the depth recommended in Design Rationale, "Finality and reorg protection." A change to the configured depth must not invalidate a claim or release that was already valid under the previous depth. -14. A protocol fee is charged on both minting and burning of the wrapped token - on LEZ, in a denomination (wrapped token, native LEZ token, or a +13. A protocol fee can be charged on both minting and burning of the wrapped + token on LEZ, in a denomination (wrapped token, native LEZ token, or a configurable mix, per Design Rationale, "Fee structure") and at a rate - configurable by the admin authority per deployment. No fee is mandated on - the Ethereum side. The fee value must not distinguish a user's transaction - from others, consistent with Functionality #8. -15. A freeze authority (per RFP-002) can pause minting and/or redemption, either + configurable by the admin authority per deployment. The fee value must not + distinguish a user's transaction from others, consistent with Functionality + #8. The admin can also set either fee to zero. +14. A freeze authority (per RFP-002) can pause minting and/or redemption, either globally or for a single registered token, on the Ethereum vault and the LEZ bridge program independently. -16. The vault contract and every token registration it holds are scoped to a - specific EVM chain ID, recorded on both the Ethereum vault and the LEZ - bridge program's registry, and checked as part of proof verification. The - design must not assume Ethereum mainnet is the only source chain: the same - vault contract and LEZ bridge program design must be deployable, unmodified, - against any EVM chain, with proofs and registrations scoped so a deposit or - registration valid for one chain ID is never accepted as valid for another. -17. The design must let multiple entities each operate under their own +15. Each LEZ bridge program deployment refers to a specific EVM smart contract + deployment on a specific chain (contract address plus chain ID as the + identifier), and reciprocally, each EVM smart contract deployment refers to + a specific zone instance (LEZ blockchain ID, zone ID, and program ID). The + design must not assume Ethereum mainnet is the only chain a deployment can + target: the same program and contract design must be deployable, unmodified, + against any EVM chain, mainnet or testnet, with each pairing checked as part + of proof verification so a deposit or registration valid for one pairing is + never accepted as valid for another. +16. The design must let multiple entities each operate under their own independent configuration (token registry, fee recipients and rates, admin - authority, caps, finality depth) on the same pair of blockchain programs, - with strict separation between them: one entity's configuration must have no - privileged access over another's configuration or funds, as if each were a - fully separate deployment. Document how a client identifies and switches - between configurations. + authority, caps, finality depth) on the same or different pairs of + blockchain programs, with strict separation between them: one entity's + configuration must have no privileged access over another's configuration or + funds, as if each were a fully separate deployment. Document how a client + identifies and switches between configurations. #### Usability -1. Provide an SDK that can be used to build Logos modules for: depositing, - claiming a deposit on LEZ, redeeming, releasing on Ethereum, recovering a - position from user credentials, and reading the supported-token registry and - its permitted amounts. -2. Provide a Logos mini-app GUI with local build instructions, downloadable - assets, and loadable in Logos app (Basecamp) via git repo. It must cover the - deposit and redemption flows end to end, position recovery, and a registry - view showing supported tokens, permitted amounts, caps and current - utilisation. -3. Provide a CLI that covers core functionality: deposit, claim, redeem, - release, recover, and query the registry. The CLI may have fewer features - than the mini-app but must support all essential operations. -4. Any long-running off-chain component the design requires must be provided as +1. Build core functionalities for both users and admin in a Logos core module, + enabling the delivery of different Logos ui modules to use these programs: + depositing, claiming a deposit on LEZ, redeeming, releasing on Ethereum, + recovering a position from user credentials, and reading and administering + the supported-token registry and its permitted amounts. +2. Provide a Logos mini-app, aka Logos ui module, covering the deposit and + redemption flows end to end, position recovery, and a registry view showing + supported tokens, permitted amounts, caps and current utilisation. +3. Any long-running off-chain component the design requires must be provided as a **Logos module accompanied by a Logos Core headless CLI/daemon**, runnable standalone, supporting configurable RPC endpoints for both chains, configurable finality depth, structured logging, and a clean shutdown path. Proposals must integrate mature, audited proof-system implementations rather than reimplementing zero-knowledge primitives from scratch. Document the operator journey end-to-end: install, configure, run, monitor. -5. Provide an IDL for the LEZ bridge program using the +4. Provide an IDL for the LEZ bridge program using the [SPEL framework](https://github.com/logos-co/spel). -6. Before any privacy-sensitive submission, the mini-app and CLI must show the - user the current anonymity set their transaction would join, and warn when it - falls below a configurable threshold. Where delaying a submission improves - privacy, the client must default to doing so rather than submitting - immediately, with the user able to inspect and override. -7. Although minting and burning both support public LEZ accounts (Functionality - #4, #7), the mini-app and CLI must default to inviting the user to mint into, +5. The mitigations to the three correlation points in Design Rationale, "The + privacy requirement, stated precisely" (amount, timing, fee payer) must be + enabled by default for users, not opt-in. The mini-app and CLI must show a + clear indicator of what data would be leaked by the user's current choices, + and default to the recommended parameters (fixed denomination, delayed + submission, permissionless relayer) rather than requiring the user to select + them. +6. Although minting and burning both support public LEZ accounts (Functionality + #4, #6), the mini-app and CLI must default to inviting the user to mint into, and burn from, a private account: the private path is the pre-selected option in the flow, and choosing the public path instead requires an explicit action, consistent with Privacy Preservation #8. -8. Documentation and UI must clearly explain what is public and what is private +7. Documentation and UI must clearly explain what is public and what is private at each step on both chains, in the manner of [RFP-004](./RFP-004-privacy-preserving-dex.md), so users can judge their own exposure. -9. Return clear, actionable error messages for all failure modes: unsupported +8. Return clear, actionable error messages for all failure modes: unsupported token, invalid amount, cap exceeded, verification failure, insufficient finality, already claimed, and program or per-token frozen. Error messages must not reveal which deposit or burn a failed attempt referred to. @@ -531,7 +525,7 @@ Use FURPS framework. Each numbered item should be a testable statement. #### Supportability 01. The Ethereum vault contract and the LEZ bridge program are deployed and - tested on a public Ethereum testnet and LEZ devnet/testnet respectively. + tested on a public Ethereum testnet and LEZ testnet respectively. 02. End-to-end integration tests exercise the full deposit and redemption round trip against a LEZ sequencer (standalone mode) and an Ethereum test network or local fork, and are included in CI. CI must be green on the default @@ -543,21 +537,21 @@ Use FURPS framework. Each numbered item should be a testable statement. depositing and redeeming via CLI and mini-app. 05. Submit a [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for the SDK, covering the developer integration journey for both flows - including position recovery. + for the core module, covering the developer integration journey for both + flows including position recovery. 06. Submit a [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) for the CLI and any operator-facing components, covering the core user and operator journeys respectively. -07. Provide Figma designs or equivalent for all mini-app GUI artefacts, - including the anonymity-set disclosure and the recovery flow. +07. Submit a + [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) + for the deployer journey, covering how an entity stands up its own + independently configured deployment (Functionality #16): registering tokens, + setting fees, configuring the admin and freeze authorities, and the finality + depth. 08. The Ethereum vault contract undergoes an independent third-party smart-contract security audit before mainnet deployment; the audit report - (or a summary, if the full report is not publishable) must be linked from - the README. This requirement exists because cross-chain bridges are the - single most-attacked category of DeFi infrastructure (see - [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)); - it is not optional. + must be published. 09. Provide a **privacy properties document** covering: a formal statement of P1 and P2 and the anonymity set each is measured against; exactly what is visible on-chain at every step on both chains; what an adversary observing @@ -568,66 +562,74 @@ Use FURPS framework. Each numbered item should be a testable statement. 10. Document the anonymity-set growth model: expected set size over time at projected volumes, the minimum below which the guarantees are considered not to hold, and guidance for users bridging before the pool has matured. +11. The Ethereum side must use the Logos Ethereum core module, including its + verified proxy features. The UI must let users change the targeted Ethereum + RPC address and the targeted LEZ sequencer or zone. The UI must use the + wallet SDK from the Lambda Prize wallet-SDK work. The design must use the + outputs of [RFP-001](./RFP-001-admin-authority-lib.md) and + [RFP-002](./RFP-002-freeze-authority-lib.md) for the admin and freeze + authorities respectively, and must work with the existing LEZ token program. + Wrapped-token accounts must be compatible with ATA (Associated Token + Account) derivation, consistent with + [RFP-004](./RFP-004-privacy-preserving-dex.md). The deliverable must be + published on the module catalog and must use the standard Logos GitHub + Actions. #### + Bridge Security -01. Proof verification must be deterministic and independently verifiable. Both - the LEZ program and the Ethereum vault must reject invalid proofs, tested - with incorrect public inputs, proofs for incorrect chain state, tampered - headers, and replayed proofs. -02. Any off-chain component must independently derive chain state from the - source chain rather than accepting data supplied by a third party without - verification. -03. A malicious party submitting on a user's behalf must not be able to redirect - funds, inflate their fee, or replay the user's submission to a different - destination. Test each case explicitly. -04. A deposit and a burn must each secretly commit to the destination on the - other chain, so that the claim can only be completed by whoever holds the - seed or credentials that produced the commitment. It must not be possible to - steal a claim from any information that leaks beyond that seed: not the - deposit or burn transaction itself, not any public or observable state, and - not any party the flow depends on (see Functionality #2, #5). Test that an - adversary who observes everything public about a deposit or burn, but does - not hold the originating seed, cannot construct a valid claim for a - different destination. -05. Caps (Functionality #12) bound the maximum value at risk in any rolling - window; proposals must document recommended defaults and the reasoning - behind them. -06. The freeze authority (Functionality #15) must be exercisable independently - on each half, so either can be paused without the other being operational or - reachable. -07. Soundness of supply: total wrapped supply on LEZ must never exceed the - vault's holdings. Provide tests attempting to mint without a valid deposit, - mint twice from one deposit, and release without a valid burn. -08. User-facing documentation must state the trustless verification model and - the liveness-only role of any off-chain participant (see Design Rationale, - "Trust model"). -09. The verifier (the LEZ bridge program and the Ethereum vault's proof - verification logic) must be deployed as an immutable program with an - explicit migration path (deploy a new version, drain and redirect to it) in - preference to an upgradeable contract governed by a mutable key. An - upgradeable verifier carries two risks this eliminates by construction: a - stolen or misused upgrade key substituting malicious logic, and a - legitimate, authorised upgrade shipping a catastrophic bug, the latter being - the documented cause of real bridge losses (see Why This Matters and - [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)). - Proposals must document the chosen migration mechanism and how in-flight - deposits and burns are honoured across a migration. -10. The freeze authority (Functionality #15) stops new activity but does not by - itself recover funds already at risk or resolve deposits and burns left - in-flight once a vulnerability in the verification logic is found. Proposals - must specify a failsafe strategy for this scenario, constrained as follows: - the failsafe must not become a backdoor, meaning any recovery must still be - claimed by the depositor or burner proving their own entitlement, the same - way an ordinary claim or redemption works (see Design Rationale, "Trust - model" and "Loss of access"), not by an admin authority or any other party - identifying who owns what and redirecting funds on their behalf; it must not - be able to mint, redirect, or release funds to any destination other than - the address or account the proof specifies; and it must not be able to act - on funds beyond what a specific, proven vulnerability put at risk. If no - mechanism satisfying these constraints is achievable, the proposal must - instead document explicitly why a failsafe should not be implemented, and - what happens to affected funds and in-flight positions in its absence. +1. Proof verification must be deterministic and independently verifiable. Both + the LEZ program and the Ethereum vault must reject invalid proofs, tested + with incorrect public inputs, proofs for incorrect chain state, tampered + headers, and replayed proofs. +2. A malicious party submitting on a user's behalf must not be able to redirect + funds, inflate their fee, or replay the user's submission to a different + destination: a deposit and a burn must each secretly commit to the + destination on the other chain, so that the claim can only be completed by + whoever holds the seed or credentials that produced the commitment, and no + information that leaks beyond that seed, whether from the deposit or burn + transaction itself, public or observable state, or any party the flow depends + on, can be used to steal it (see Functionality #2, #5). Test that an + adversary who observes everything public about a deposit or burn, but does + not hold the originating seed, cannot construct a valid claim for a different + destination. +3. Caps (Functionality #11) bound the maximum value at risk in any rolling + window; proposals must document recommended defaults and the reasoning behind + them. +4. The freeze authority (Functionality #14) must be exercisable independently on + each half, so either can be paused without the other being operational or + reachable. +5. Soundness of supply: total wrapped supply on LEZ must never exceed the + vault's holdings. Provide tests attempting to mint without a valid deposit, + mint twice from one deposit, and release without a valid burn. +6. User-facing documentation must state the trustless verification model and the + liveness-only role of any off-chain participant (see Design Rationale, "Trust + model"). +7. The verifier (the LEZ bridge program and the Ethereum vault's proof + verification logic) must be deployed as an immutable program with an explicit + migration path (deploy a new version, drain and redirect to it) in preference + to an upgradeable contract governed by a mutable key. An upgradeable verifier + carries two risks this eliminates by construction: a stolen or misused + upgrade key substituting malicious logic, and a legitimate, authorised + upgrade shipping a catastrophic bug, the latter being the documented cause of + real bridge losses (see Why This Matters and + [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)). + Proposals must document the chosen migration mechanism and how in-flight + deposits and burns are honoured across a migration. +8. The freeze authority (Functionality #14) stops new activity but does not by + itself recover funds already at risk or resolve deposits and burns left + in-flight once a vulnerability in the verification logic is found. Proposals + must specify a failsafe strategy for this scenario, constrained as follows: + the failsafe must not become a backdoor, meaning any recovery must still be + claimed by the depositor or burner proving their own entitlement, the same + way an ordinary claim or redemption works (see Design Rationale, "Trust + model" and "Loss of access"), not by an admin authority or any other party + identifying who owns what and redirecting funds on their behalf; it must not + be able to mint, redirect, or release funds to any destination other than the + address or account the proof specifies; and it must not be able to act on + funds beyond what a specific, proven vulnerability put at risk. If no + mechanism satisfying these constraints is achievable, the proposal must + instead document explicitly why a failsafe should not be implemented, and + what happens to affected funds and in-flight positions in its absence. #### + Privacy Preservation @@ -679,10 +681,10 @@ Use FURPS framework. Each numbered item should be a testable statement. authority to react to anomalous redemption volume before funds leave the vault. 5. Support for wrapping ERC-20 tokens from additional EVM chains (e.g. Arbitrum, - Base) behind the same LEZ bridge program, reusing the registry and caps, and - building on the chain ID scoping already required by Functionality #16. - Consider whether anonymity sets should be shared across source chains to - enlarge them. + Base), each served by its own LEZ bridge program deployment per Functionality + #15 (one program per chain ID, not one program juggling several chains + internally). Consider whether anonymity sets should be shared across these + per-chain deployments to enlarge them. 6. Hardware acceleration as an optional path for users with capable machines, without making it a requirement. 7. Design the proof-system components as pluggable, so that future zkVM @@ -709,13 +711,6 @@ Use FURPS framework. Each numbered item should be a testable statement. The following are explicitly excluded from this RFP: - Wrapping non-fungible assets (ERC-721, ERC-1155). -- Bitcoin, Monero, and Zcash liquidity: these reach LEZ via direct, trustless - swaps against LEZ assets, delivered in [RFP-003](./RFP-003-atomic-swaps.md), - not via a wrapped representation. -- Mobile and in-browser proving. Basecamp is a desktop application and is the - delivery surface for the mini-app, so any user-side proving targets desktop - only. Proposals must not constrain their design to fit mobile-class resource - budgets. - Network-level anonymity. The guarantees here are properties of on-chain state. IP-level correlation between a user's Ethereum deposit and their later LEZ activity is out of scope as an implementation concern, but must be disclosed @@ -730,9 +725,6 @@ The following are explicitly excluded from this RFP: optimisation techniques. This RFP does not mandate a specific proof system for verifying LEZ state and events on Ethereum; that choice is left to the proposal. -- Price feeds for wrapped assets. Once a token is wrapped, pricing it is the - responsibility of the oracle stack ([RFP-019](./RFP-019-twap-oracle.md), - [RFP-020](./RFP-020-redstone-oracle-adaptor.md)), not this bridge. ## ⚠ Platform Dependencies @@ -757,17 +749,11 @@ from [RFP-002](./RFP-002-freeze-authority-lib.md). The LEZ bridge program mints wrapped tokens on verified deposits and burns them on redemption. This requires the token mint/burn authority primitives in [LP-0013](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md). -Note that Soft Requirement #1 (hidden amounts) would require supply accounting -over concealed values, which is likely an extension beyond what LP-0013 -provides; proposals pursuing that path must state what extension is needed. #### Private LEZ account state Minting and burning must both support private LEZ accounts (Functionality #4, -#6), and the privacy guarantees (P1, P2) apply when a user chooses that path: -minting into a public account instead exposes the recipient immediately, which -is the user's choice to make, not a gap in the design. Proposals must state -which LEZ private-state primitives they rely on and their maturity. +#6), and the privacy guarantees (P1, P2) apply when a user chooses that path. #### RISC0 zkVM @@ -776,10 +762,7 @@ itself runs on RISC0, a production-ready zkVM, this leg of the design is a LEZ-runtime dependency rather than a choice the proposal makes; proposals must leverage mature RISC0 implementations (e.g. [Zisk](https://github.com/risc0/zisk)) for LEZ-side proving rather than building -custom circuits. This RFP does not mandate a specific proof system for the -corresponding native verification on Ethereum. - -### Soft dependencies +custom circuits. #### Event emission (LP-0012) From ee4c3a5de593a560d32b22ba762503515d4c639f Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Wed, 12 Aug 2026 14:45:36 +1000 Subject: [PATCH 50/69] RFP-021: rename privacy property labels P1/P2 to PP1/PP2 Avoids collision with the numbered items (1., 2., ...) in the FURPS Privacy Preservation requirements list, where "1. P1 must hold under test" read as if P1 meant that item's own number. Co-Authored-By: Claude Sonnet 5 --- RFPs/RFP-021-wrapped-erc20.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index dcc4a485..d5f20c8c 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -171,10 +171,10 @@ public state on both chains, indefinitely, and who may themselves deposit and redeem, to link an Ethereum deposit to the LEZ mint it funded, or a LEZ burn to the Ethereum release it triggered.** -- **P1 (inbound).** No signal other than amount, token, and timing may narrow +- **PP1 (inbound).** No signal other than amount, token, and timing may narrow down which LEZ mint an Ethereum deposit funded, beyond uniform probability over the remaining candidates. -- **P2 (outbound).** No signal other than amount, token, and timing may narrow +- **PP2 (outbound).** No signal other than amount, token, and timing may narrow down which Ethereum release a LEZ burn triggered, beyond uniform probability over the remaining candidates. @@ -552,8 +552,8 @@ Use FURPS framework. Each numbered item should be a testable statement. 08. The Ethereum vault contract undergoes an independent third-party smart-contract security audit before mainnet deployment; the audit report must be published. -09. Provide a **privacy properties document** covering: a formal statement of P1 - and P2 and the anonymity set each is measured against; exactly what is +09. Provide a **privacy properties document** covering: a formal statement of + PP1 and PP2 and the anonymity set each is measured against; exactly what is visible on-chain at every step on both chains; what an adversary observing all public state can and cannot infer; what every off-chain participant in the design can observe; residual leakage from timing, amount selection, fee @@ -633,12 +633,12 @@ Use FURPS framework. Each numbered item should be a testable statement. #### + Privacy Preservation -1. **P1 must hold under test.** Provide an automated test that constructs a +1. **PP1 must hold under test.** Provide an automated test that constructs a population of deposits and mints and asserts that no correlation derivable from public state, other than amount, token, and timing, identifies the true pairing better than chance across the anonymity set those three signals leave unresolved. -2. **P2 must hold under test.** The equivalent test for burn-to-release +2. **PP2 must hold under test.** The equivalent test for burn-to-release pairings. 3. No transaction argument, event, log, or account-state change on either chain may reveal a deposit's LEZ destination or a burn's Ethereum destination. @@ -753,7 +753,7 @@ on redemption. This requires the token mint/burn authority primitives in #### Private LEZ account state Minting and burning must both support private LEZ accounts (Functionality #4, -#6), and the privacy guarantees (P1, P2) apply when a user chooses that path. +#6), and the privacy guarantees (PP1, PP2) apply when a user chooses that path. #### RISC0 zkVM From a70b494468d571e7f2afb806ff1b05df6ad47c5b Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Wed, 12 Aug 2026 14:49:02 +1000 Subject: [PATCH 51/69] RFP-021: drop invented PP1/PP2 labels, cite FURPS items directly PP1/PP2 read as "Privacy Preservation 1/2", colliding with the section name itself, on top of already colliding with that section's own item numbering. Instead of any invented label, the inbound/outbound unlinkability properties are now defined directly as Privacy Preservation items #1 and #2, and every other reference cites them the same way the doc already cites other FURPS items elsewhere (Functionality #2, #5, Supportability #9, etc). Co-Authored-By: Claude Sonnet 5 --- RFPs/RFP-021-wrapped-erc20.md | 47 ++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 20 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index d5f20c8c..37e78ee4 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -171,12 +171,14 @@ public state on both chains, indefinitely, and who may themselves deposit and redeem, to link an Ethereum deposit to the LEZ mint it funded, or a LEZ burn to the Ethereum release it triggered.** -- **PP1 (inbound).** No signal other than amount, token, and timing may narrow - down which LEZ mint an Ethereum deposit funded, beyond uniform probability - over the remaining candidates. -- **PP2 (outbound).** No signal other than amount, token, and timing may narrow - down which Ethereum release a LEZ burn triggered, beyond uniform probability - over the remaining candidates. +- **Inbound.** No signal other than amount, token, and timing may narrow down + which LEZ mint an Ethereum deposit funded, beyond uniform probability over the + remaining candidates. Formalised as a testable requirement in Privacy + Preservation #1, below. +- **Outbound.** No signal other than amount, token, and timing may narrow down + which Ethereum release a LEZ burn triggered, beyond uniform probability over + the remaining candidates. Formalised as a testable requirement in Privacy + Preservation #2, below. Both are stated relative to this *anonymity set*, the candidates amount, token, and timing leave unresolved, and degrade to nothing when that set is small. @@ -553,12 +555,12 @@ Use FURPS framework. Each numbered item should be a testable statement. smart-contract security audit before mainnet deployment; the audit report must be published. 09. Provide a **privacy properties document** covering: a formal statement of - PP1 and PP2 and the anonymity set each is measured against; exactly what is - visible on-chain at every step on both chains; what an adversary observing - all public state can and cannot infer; what every off-chain participant in - the design can observe; residual leakage from timing, amount selection, fee - payment, network metadata and usage patterns; and the conditions under which - the guarantees degrade or fail. + Privacy Preservation #1 and #2 and the anonymity set each is measured + against; exactly what is visible on-chain at every step on both chains; what + an adversary observing all public state can and cannot infer; what every + off-chain participant in the design can observe; residual leakage from + timing, amount selection, fee payment, network metadata and usage patterns; + and the conditions under which the guarantees degrade or fail. 10. Document the anonymity-set growth model: expected set size over time at projected volumes, the minimum below which the guarantees are considered not to hold, and guidance for users bridging before the pool has matured. @@ -633,13 +635,17 @@ Use FURPS framework. Each numbered item should be a testable statement. #### + Privacy Preservation -1. **PP1 must hold under test.** Provide an automated test that constructs a - population of deposits and mints and asserts that no correlation derivable - from public state, other than amount, token, and timing, identifies the true - pairing better than chance across the anonymity set those three signals leave - unresolved. -2. **PP2 must hold under test.** The equivalent test for burn-to-release - pairings. +1. **Inbound unlinkability must hold under test.** No signal other than amount, + token, and timing may narrow down which LEZ mint an Ethereum deposit funded, + beyond uniform probability over the remaining candidates. Provide an + automated test that constructs a population of deposits and mints and asserts + that no correlation derivable from public state, other than amount, token, + and timing, identifies the true pairing better than chance across the + anonymity set those three signals leave unresolved. +2. **Outbound unlinkability must hold under test.** No signal other than amount, + token, and timing may narrow down which Ethereum release a LEZ burn + triggered, beyond uniform probability over the remaining candidates. The + equivalent test for burn-to-release pairings. 3. No transaction argument, event, log, or account-state change on either chain may reveal a deposit's LEZ destination or a burn's Ethereum destination. Provide a test asserting this over full event and state diffs for a complete @@ -753,7 +759,8 @@ on redemption. This requires the token mint/burn authority primitives in #### Private LEZ account state Minting and burning must both support private LEZ accounts (Functionality #4, -#6), and the privacy guarantees (PP1, PP2) apply when a user chooses that path. +#6), and the privacy guarantees (Privacy Preservation #1, #2) apply when a user +chooses that path. #### RISC0 zkVM From 8b1083b37533e81c1cb057c73c90ee7600fb5cce Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Wed, 12 Aug 2026 15:47:47 +1000 Subject: [PATCH 52/69] RFP-021: address second batch of PR review comments - Credit Cryptarchia and Blend alongside LEZ architecture - Note wrapped Bitcoin and synthetics as other strategies under consideration - Require the UI to encourage a submission delay - Drop the "not the only deployment model" hedge; the RFP does mandate admin curation - Remove fee-on-transfer/rebasing rejection as an implementation choice - Drop the RFP-017 comparison and "in the manner of RFP-004" cross-reads - Add Design Rationale: One program pair = one chain pair - Add admin UI to Usability #2 - Move proof-system maturity and CI-green to Reliability - Split Supportability #11 into separate criteria; move dependencies to Platform Dependencies (Logos Ethereum core module, wallet SDK, ATA/token program) - Correct LP-0013 title and mark it closed; drop the redundant private-account dependency section - Soften Soft Requirement #1 phrasing; drop the batching privacy claim and the shared-anonymity-set question; freeze -> admin authority on the release delay - Rewrite gas-token bootstrapping for clarity Co-Authored-By: Claude Sonnet 5 --- RFPs/RFP-021-wrapped-erc20.md | 198 ++++++++++++++++++---------------- 1 file changed, 106 insertions(+), 92 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 37e78ee4..379eff98 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -10,7 +10,7 @@ dependencies: - id: RFP-002 reason: Freeze authority provides the circuit breaker to halt minting and/or redemption, globally or per token, if a proof-system or vault vulnerability is suspected. - id: LP-0013 - reason: Mint/burn token authority primitives are required for the LEZ program to mint wrapped tokens on verified deposit, and burn them on redemption. + reason: Token authority primitives are required for the LEZ program to mint wrapped tokens on verified deposit, and burn them on redemption. --- @@ -74,11 +74,12 @@ development. ## 🔥 Why This Matters Thanks to LEZ's separated public/private state architecture and programmability, -private DeFi is possible with privacy guarantees at both the execution layer and -the underlying consensus layer. To let users move assets in from non-private -blockchains such as Ethereum, that move has to happen while preserving Logos' -principle of sovereignty: no custodian, signer, or federation should be trusted -with a user's assets or identity along the way. +and Logos Blockchain's Cryptarchia and Blend protocols, private DeFi is possible +with privacy guarantees at both the execution layer and the underlying consensus +layer. To let users move assets in from non-private blockchains such as +Ethereum, that move has to happen while preserving Logos' principle of +sovereignty: no custodian, signer, or federation should be trusted with a user's +assets or identity along the way. Wrapped tokens are what let users bring assets they already hold, and whose value is already established, on Ethereum into that private DeFi, spending them @@ -90,7 +91,9 @@ that collateralise them ([RFP-019](./RFP-019-twap-oracle.md), [RFP-020](./RFP-020-redstone-oracle-adaptor.md)). This RFP delivers that wrapping primitive for the Ethereum leg. Bitcoin, Monero, and Zcash reach LEZ liquidity through a different route: direct, trustless swaps against LEZ assets -via [RFP-003](./RFP-003-atomic-swaps.md), rather than a wrapped representation. +via [RFP-003](./RFP-003-atomic-swaps.md), rather than a wrapped representation, +noting that other strategies such as wrapped Bitcoin and synthetics are also +being considered. RFP-003 explicitly carved Ethereum out of its scope for this reason. Bitcoin, Monero, and Zcash lack general smart-contract expressiveness, so a trustless @@ -199,7 +202,7 @@ address each: considerably heavier, and is specified as a soft requirement below. - **Timing correlates.** A deposit followed promptly by a mint, at a quiet moment, is matched by inspection. The protocol must not force users into - correlated timing. + correlated timing, and the UI must encourage some delay. - **Fee payers correlate.** If the user pays their own gas to mint or release, the funding source of that account re-identifies them and the construction collapses. Permissionless relayers paid out of the bridged amount are the @@ -281,14 +284,12 @@ registry cannot: open-ended, permissionless list of approved tokens has no bound on this cost, where a curated registry does. -Curation by a single admin authority is not the only way to satisfy these -concerns, and this RFP does not mandate it as the only deployment model. Because -the design is open source, and supports multiple independently configured -entities on both chains (Functionality #16), curation also enables competition: -multiple entities or DAOs can each run their own configuration, with their own -token registry and admin policy, competing on the quality of curation and the -resulting reputation of their specific wrapped tokens, rather than the ecosystem -depending on one canonical, centrally-curated list. +Because the design is open source, and supports multiple independently +configured entities on both chains (Functionality #16), curation also enables +competition: multiple entities or DAOs can each run their own configuration, +with their own token registry and admin policy, competing on the quality of +curation and the resulting reputation of their specific wrapped tokens, rather +than the ecosystem depending on one canonical, centrally-curated list. Each supported ERC-20 is registered individually by the admin authority: its Ethereum contract address, its LEZ wrapped-token mint, its decimals, its @@ -298,11 +299,6 @@ wrapped LEZ mint for each token must document its own decimals and the exact conversion applied on mint and burn, and registration must reject any token whose values cannot be represented exactly in the chosen LEZ mint precision. -Fee-on-transfer and rebasing ERC-20s break the invariant that the amount -deposited equals the amount mintable. The registry must reject them, and the -vault must measure the deposit by how much its own balance actually increased, -rather than trusting the requested amount. - ### Finality and reorg protection Wrapped tokens must not be minted against an Ethereum deposit that a reorg could @@ -322,19 +318,17 @@ forced to act promptly to avoid expiry. ### Fee structure -Unlike the pattern used elsewhere in the Logos RFP set (see -[RFP-017](./RFP-017-token-vesting.md), "Fee structure"), this RFP mandates a -protocol fee on both minting (deposit-side) and burning (redemption-side) of the -wrapped token on LEZ. The rate itself is not mandated: it must be configurable -by the admin authority per deployment, for the same reason the token registry -and finality depth are (see "Token registry and decimal normalisation" and -"Finality and reorg protection" above), so different deployers can compete on -sustainability and fee policy rather than being locked into one rate. This RFP -does not mandate a fee on the Ethereum side; the focus here is the Logos -ecosystem and its privacy-preserving LEZ side, and an Ethereum-side protocol fee -is left to the proposal if it chooses to specify one. +This RFP mandates a protocol fee on both minting (deposit-side) and burning +(redemption-side) of the wrapped token on LEZ. The rate itself is not mandated: +it must be configurable by the admin authority per deployment, for the same +reason the token registry and finality depth are (see "Token registry and +decimal normalisation" and "Finality and reorg protection" above), so different +deployers can compete on sustainability and fee policy rather than being locked +into one rate. This RFP does not mandate a fee on the Ethereum side; the focus +here is the Logos ecosystem and its privacy-preserving LEZ side, and an +Ethereum-side protocol fee is left to the proposal if it chooses to specify one. -Proposals must specify: +Configuration proposals must specify: 1. **Denomination.** Whether the fee is charged in the wrapped token itself, in native LEZ tokens, or a mix of both, with the design rationale for the @@ -360,6 +354,24 @@ must take a value that does not distinguish their transaction from others, since a distinctive fee is itself a fingerprint; this constraint applies regardless of which token the fee is charged in. +### One program pair = one chain pair + +A given instance of the LEZ program, under a given configuration, supports a +single EVM chain ID. The reason is blast-radius containment: an incident on one +EVM chain, whether a reorg, a consensus bug, or a compromised token contract, +should not contaminate the wrapped supply backed by another chain. + +This raises the question of whether USDC deposited from EVM chain A should be +represented by the same LEZ token as USDC deposited from EVM chain B. Separation +reduces risk, since a failure on one chain leaves the other chain's wrapped +supply untouched. Unification increases liquidity, and increases privacy, since +a mint of USDC on LEZ could then have originated from any of several chains, +enlarging the anonymity set. + +This RFP is written assuming separation, and Functionality #15 and Soft +Requirement #5 reflect that. Applicants are welcome to argue for either +direction, with the reasoning made explicit. + ## ✅ Scope of Work ### Hard Requirements @@ -402,8 +414,7 @@ Use FURPS framework. Each numbered item should be a testable statement. applicable to the LEZ side) can register a supported ERC-20 (Ethereum address, LEZ wrapped mint, decimals, permitted amounts, caps) and deregister a token. Documentation needs to be provided to handle registration changes - with minimum impact for users, including delisting of a token. The registry - must reject fee-on-transfer and rebasing tokens. + with minimum impact for users, including delisting of a token. 11. Global and per-token deposit and redemption caps, configurable by the admin authority, bound the maximum value that can be minted or released within a rolling window, as a rate limiter independent of the freeze authority. Cap @@ -448,21 +459,21 @@ Use FURPS framework. Each numbered item should be a testable statement. the supported-token registry and its permitted amounts. 2. Provide a Logos mini-app, aka Logos ui module, covering the deposit and redemption flows end to end, position recovery, and a registry view showing - supported tokens, permitted amounts, caps and current utilisation. + supported tokens, permitted amounts, caps and current utilisation. Also + provide a UI for the admin functionality; whether this is combined into one + UI or delivered as two separate ones is left to the applicant's choice. 3. Any long-running off-chain component the design requires must be provided as a **Logos module accompanied by a Logos Core headless CLI/daemon**, runnable standalone, supporting configurable RPC endpoints for both chains, configurable finality depth, structured logging, and a clean shutdown path. - Proposals must integrate mature, audited proof-system implementations rather - than reimplementing zero-knowledge primitives from scratch. Document the - operator journey end-to-end: install, configure, run, monitor. + Document the operator journey end-to-end: install, configure, run, monitor. 4. Provide an IDL for the LEZ bridge program using the [SPEL framework](https://github.com/logos-co/spel). 5. The mitigations to the three correlation points in Design Rationale, "The privacy requirement, stated precisely" (amount, timing, fee payer) must be - enabled by default for users, not opt-in. The mini-app and CLI must show a - clear indicator of what data would be leaked by the user's current choices, - and default to the recommended parameters (fixed denomination, delayed + enabled by default for users. The mini-app and CLI must show a clear + indicator of what data would be leaked by the user's current choices, and + default to the recommended parameters (fixed denomination, delayed submission, permissionless relayer) rather than requiring the user to select them. 6. Although minting and burning both support public LEZ accounts (Functionality @@ -471,9 +482,7 @@ Use FURPS framework. Each numbered item should be a testable statement. in the flow, and choosing the public path instead requires an explicit action, consistent with Privacy Preservation #8. 7. Documentation and UI must clearly explain what is public and what is private - at each step on both chains, in the manner of - [RFP-004](./RFP-004-privacy-preserving-dex.md), so users can judge their own - exposure. + at each step on both chains, so users can judge their own exposure. 8. Return clear, actionable error messages for all failure modes: unsupported token, invalid amount, cap exceeded, verification failure, insufficient finality, already claimed, and program or per-token frozen. Error messages @@ -498,6 +507,9 @@ Use FURPS framework. Each numbered item should be a testable statement. already done. 7. An interrupted user-side operation does not consume, corrupt, or expose the user's entitlement. +8. Proposals must integrate mature, audited proof-system implementations rather + than reimplementing zero-knowledge primitives from scratch. +9. CI must be green on the default branch. #### Performance @@ -530,8 +542,7 @@ Use FURPS framework. Each numbered item should be a testable statement. tested on a public Ethereum testnet and LEZ testnet respectively. 02. End-to-end integration tests exercise the full deposit and redemption round trip against a LEZ sequencer (standalone mode) and an Ethereum test network - or local fork, and are included in CI. CI must be green on the default - branch. + or local fork, and are included in CI. 03. Every hard requirement in Functionality, Usability, Reliability, Performance, and Privacy Preservation has at least one corresponding test. 04. A README documents end-to-end usage: contract and program addresses, @@ -564,25 +575,17 @@ Use FURPS framework. Each numbered item should be a testable statement. 10. Document the anonymity-set growth model: expected set size over time at projected volumes, the minimum below which the guarantees are considered not to hold, and guidance for users bridging before the pool has matured. -11. The Ethereum side must use the Logos Ethereum core module, including its - verified proxy features. The UI must let users change the targeted Ethereum - RPC address and the targeted LEZ sequencer or zone. The UI must use the - wallet SDK from the Lambda Prize wallet-SDK work. The design must use the - outputs of [RFP-001](./RFP-001-admin-authority-lib.md) and - [RFP-002](./RFP-002-freeze-authority-lib.md) for the admin and freeze - authorities respectively, and must work with the existing LEZ token program. - Wrapped-token accounts must be compatible with ATA (Associated Token - Account) derivation, consistent with - [RFP-004](./RFP-004-privacy-preserving-dex.md). The deliverable must be - published on the module catalog and must use the standard Logos GitHub - Actions. +11. The UI must let users change the targeted Ethereum RPC address and the + targeted LEZ sequencer or zone. +12. The deliverable must be published on the module catalog. +13. The repository must use the standard Logos GitHub Actions. #### + Bridge Security -1. Proof verification must be deterministic and independently verifiable. Both - the LEZ program and the Ethereum vault must reject invalid proofs, tested - with incorrect public inputs, proofs for incorrect chain state, tampered - headers, and replayed proofs. +1. Proof verification must be independently verifiable. Both the LEZ program and + the Ethereum vault must reject invalid proofs, tested with incorrect public + inputs, proofs for incorrect chain state, tampered headers, and replayed + proofs. 2. A malicious party submitting on a user's behalf must not be able to redirect funds, inflate their fee, or replay the user's submission to a different destination: a deposit and a burn must each secretly commit to the @@ -671,46 +674,50 @@ Use FURPS framework. Each numbered item should be a testable statement. 1. **Hidden amounts.** Remove the amount-visibility constraint entirely by concealing transferred values on the LEZ side, rather than relying on a fixed set of permitted amounts. This merges all per-amount anonymity sets into one - and removes the need for users to split transfers. Whatever is delivered + and reduces the need for users to split transfers. Whatever is delivered under the hard requirements should be designed so this can be adopted later without redeploying the vault or resetting accumulated anonymity; document the intended migration path even if it is not implemented. + 2. Batching: amortise verification cost across multiple operations in a single transaction, analogous to the multi-feed batching soft requirement in - RFP-020. Batching also improves privacy by making individual operations - harder to isolate. + RFP-020. + 3. Optional viewing keys allowing a user to *voluntarily* disclose their own bridge activity to a chosen third party, without weakening privacy for anyone else and without any protocol-level disclosure capability. + 4. A configurable per-token release delay, in addition to finality and any - user-chosen delay, as an extra circuit-breaker window allowing the freeze + user-chosen delay, as an extra circuit-breaker window allowing the admin authority to react to anomalous redemption volume before funds leave the vault. + 5. Support for wrapping ERC-20 tokens from additional EVM chains (e.g. Arbitrum, Base), each served by its own LEZ bridge program deployment per Functionality #15 (one program per chain ID, not one program juggling several chains - internally). Consider whether anonymity sets should be shared across these - per-chain deployments to enlarge them. + internally). + 6. Hardware acceleration as an optional path for users with capable machines, without making it a requirement. + 7. Design the proof-system components as pluggable, so that future zkVM improvements, proof compression, or hardware acceleration can be adopted without restructuring the vault or the bridge program. -8. **Gas-token bootstrapping.** An ERC-20 on Ethereum representing the native - gas token of a given Logos zone, where "minting" that ERC-20 is actually a - release of native gas token already escrowed on the LEZ side, and burning it - on Ethereum mints it back on LEZ, the inverse of this RFP's primary flow. The - goal is to let a user with no existing holdings on the zone acquire its gas - token via the bridge from Ethereum, so they are never blocked from their - first transaction by not already holding gas. If achievable, proposals should - treat this as symmetric to the primary flow (same privacy, caps, freeze - authority, and finality requirements apply to the gas-token leg) and document - how the Ethereum-side escrow of native gas token is funded and replenished, - since unlike a wrapped external asset, there is no independent market minting - new supply of it on Ethereum. If not achievable within this RFP's design, or - only achievable with materially different trust or custody assumptions than - the primary flow, document why, and what alternative bootstrapping mechanism - (a faucet, gas sponsorship, meta-transactions) would need to exist instead. + +8. **Gas-token bootstrapping.** Run the bridge in reverse for a zone's native + gas token: an ERC-20 on Ethereum represents it, locking that ERC-20 on + Ethereum releases native gas token on LEZ, and locking gas token on LEZ + releases the ERC-20 on Ethereum. This lets a user who holds nothing on the + zone acquire gas from Ethereum, rather than being unable to make a first + transaction for want of gas. + + The same privacy, caps, freeze authority, and finality requirements apply to + this leg. Proposals taking it on must document how the Ethereum-side supply + of the ERC-20 is initially issued and replenished, since no external market + mints it the way it does a wrapped external asset. Proposals that judge it + out of reach here, or reachable only under different trust or custody + assumptions, should say why, and name the bootstrapping mechanism (faucet, + gas sponsorship, meta-transactions) that would be needed instead. ### Out of Scope @@ -750,17 +757,24 @@ minting and/or redemption, globally or per token, as a circuit breaker independent of the caps. This requires the standardised freeze authority library from [RFP-002](./RFP-002-freeze-authority-lib.md). -#### Token mint/burn authorities (LP-0013) +#### Token authorities (LP-0013) The LEZ bridge program mints wrapped tokens on verified deposits and burns them -on redemption. This requires the token mint/burn authority primitives in -[LP-0013](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md). +on redemption. This requires the token authority primitives in +[LP-0013](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md), +which is **closed** (delivered). The design must work with the existing LEZ +token program, and wrapped-token accounts must be compatible with ATA +(Associated Token Account) derivation, consistent with +[RFP-004](./RFP-004-privacy-preserving-dex.md). + +#### Logos Ethereum core module + +The Ethereum side must use the Logos Ethereum core module, including its +verified proxy features. -#### Private LEZ account state +#### Wallet SDK -Minting and burning must both support private LEZ accounts (Functionality #4, -#6), and the privacy guarantees (Privacy Preservation #1, #2) apply when a user -chooses that path. +The UI must use the wallet SDK from the Lambda Prize wallet-SDK work. #### RISC0 zkVM @@ -827,7 +841,7 @@ All code must be released under the **MIT+Apache2.0 dual License**. - [RFP-020 — RedStone Off-Chain Oracle Adaptor for LEZ](./RFP-020-redstone-oracle-adaptor.md) (reference for in-program proof verification cost measurement) - [LP-0012: Event/Log mechanism for LEZ](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) -- [LP-0013: Token program improvements: mint authorities](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md) +- [LP-0013: Token program improvements: authorities](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md) - [RISC0 — Zero-Knowledge VM](https://github.com/risc0/risc0) - [Zisk — RISC0 Proof Generation](https://github.com/risc0/zisk) (reference implementation for proof generation) From 051d6eb99ea008799cf51cb88da7b3b093a540ff Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Wed, 12 Aug 2026 15:49:27 +1000 Subject: [PATCH 53/69] RFP-021: gas-token bootstrapping can be researched, not solved A proposal may commit to researching the gas-token leg and reporting findings rather than implementing it. Co-Authored-By: Claude Sonnet 5 --- RFPs/RFP-021-wrapped-erc20.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 379eff98..6e49a2c8 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -711,13 +711,16 @@ Use FURPS framework. Each numbered item should be a testable statement. zone acquire gas from Ethereum, rather than being unable to make a first transaction for want of gas. - The same privacy, caps, freeze authority, and finality requirements apply to - this leg. Proposals taking it on must document how the Ethereum-side supply - of the ERC-20 is initially issued and replenished, since no external market - mints it the way it does a wrapped external asset. Proposals that judge it - out of reach here, or reachable only under different trust or custody - assumptions, should say why, and name the bootstrapping mechanism (faucet, - gas sponsorship, meta-transactions) that would be needed instead. + A proposal does not need to solve this. Committing to research it and to + report the findings is enough, and a proposal may also implement it. Either + way, the open question to address is how the Ethereum-side supply of the + ERC-20 is initially issued and replenished, since no external market mints it + the way one does for a wrapped external asset. If the conclusion is that this + cannot be done here, or only under different trust or custody assumptions + than the primary flow, the research should say why and name the bootstrapping + mechanism (faucet, gas sponsorship, meta-transactions) that would be needed + instead. Any implementation is held to the same privacy, caps, freeze + authority, and finality requirements as the primary flow. ### Out of Scope From 9f3de3e0331b8ea143bbf099faedb487327b2590 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Fri, 14 Aug 2026 13:43:34 +1000 Subject: [PATCH 54/69] RFP-022: add trustless Ethereum state attestation primitive Extract the Ethereum consensus and state verification that RFP-021's mint path needs into its own RFP, so the primitive is built and audited once and shared with the other LEZ programs that need to read Ethereum state. The attestation establishes finality (sync-committee signatures over a light-client finality update), inclusion (Merkle-Patricia proof under the finalised header), and a predicate over the verified state, then emits a verified statement with no application action attached. Uniqueness stays with the consumer, keyed on a statement identifier the primitive supplies. RFP-021 now depends on RFP-022 for the inbound leg; the outbound leg (verifying a LEZ burn natively on Ethereum) stays in RFP-021. Co-Authored-By: Claude Opus 5 --- .github/ISSUE_TEMPLATE/proposal.yml | 1 + README.md | 1 + RFPs/RFP-021-wrapped-erc20.md | 43 +- RFPs/RFP-022-ethereum-state-attestation.md | 630 +++++++++++++++++++++ 4 files changed, 667 insertions(+), 8 deletions(-) create mode 100644 RFPs/RFP-022-ethereum-state-attestation.md diff --git a/.github/ISSUE_TEMPLATE/proposal.yml b/.github/ISSUE_TEMPLATE/proposal.yml index 11113c3a..d3eea9ab 100644 --- a/.github/ISSUE_TEMPLATE/proposal.yml +++ b/.github/ISSUE_TEMPLATE/proposal.yml @@ -15,6 +15,7 @@ body: - "RFP-016 — Token Launchpad: LBP" - "RFP-017 — Privacy-Preserving Token Vesting" - "RFP-021 — Wrapped ERC-20 Bridge for LEZ" + - "RFP-022 — Trustless Ethereum State Attestation for LEZ" validations: required: true diff --git a/README.md b/README.md index 646c5bf5..3fa023ab 100644 --- a/README.md +++ b/README.md @@ -90,6 +90,7 @@ Click an RFP to view details. Use the Submit Proposal button to apply. | RFP-019 | [On-Chain TWAP Oracle](RFPs/RFP-019-twap-oracle.md) | L | closed | - | Developer Tooling & Infrastructure | Closed | | RFP-020 | [RedStone Off-Chain Oracle Adaptor for LEZ](RFPs/RFP-020-redstone-oracle-adaptor.md) | M | closed | - | Developer Tooling & Infrastructure | Closed | | RFP-021 | [Wrapped ERC-20 Bridge for LEZ](RFPs/RFP-021-wrapped-erc20.md) | L | open | - | Developer Tooling & Infrastructure | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | +| RFP-022 | [Trustless Ethereum State Attestation for LEZ](RFPs/RFP-022-ethereum-state-attestation.md) | M | open | - | Developer Tooling & Infrastructure | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 6e49a2c8..81227fa4 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -5,6 +5,8 @@ tier: L status: open category: Developer Tooling & Infrastructure dependencies: + - id: RFP-022 + reason: The trustless Ethereum state attestation primitive is what the LEZ bridge program uses to verify a deposit really happened on Ethereum, as specified in Functionality. - id: RFP-001 reason: Admin authority governs the supported-token registry and the deposit/redemption caps, as specified in Functionality. - id: RFP-002 @@ -54,9 +56,12 @@ and exit back to Ethereum on redemption. An Ethereum-side vault contract escrows deposits. A LEZ-side program mints the corresponding wrapped token once it has cryptographically verified, with no -trusted intermediary, that the deposit really happened on Ethereum. Redemption -reverses the flow: burning the wrapped token on LEZ entitles the holder to -release the original ERC-20 from the vault, again on cryptographic proof alone. +trusted intermediary, that the deposit really happened on Ethereum; that +verification is the attestation primitive specified in +[RFP-022](./RFP-022-ethereum-state-attestation.md), which this RFP consumes +rather than rebuilds. Redemption reverses the flow: burning the wrapped token on +LEZ entitles the holder to release the original ERC-20 from the vault, again on +cryptographic proof alone. The bridge must **maximise privacy on both legs, minimising the linkability between a specific Ethereum deposit and the LEZ mint it funded, or between a @@ -389,7 +394,12 @@ Use FURPS framework. Each numbered item should be a testable statement. account that will receive the wrapped tokens. 03. Implement a LEZ bridge program that mints the corresponding wrapped token on cryptographic verification of a valid Ethereum deposit. Verification must - require no trusted party. + require no trusted party, and must consume the attestation primitive from + [RFP-022](./RFP-022-ethereum-state-attestation.md) rather than implementing + its own Ethereum consensus and inclusion verification. Uniqueness (that one + deposit cannot be minted against twice, per Reliability #3) is this + program's responsibility, keyed on the statement identifier the attestation + carries. 04. Minting must support both a private LEZ account and a public LEZ account as the destination, at the depositor's choice. 05. Implement a burn path on the LEZ bridge program that entitles the holder to @@ -746,6 +756,19 @@ The following are explicitly excluded from this RFP: ### Hard dependencies +#### Ethereum state attestation (RFP-022) + +The inbound leg mints only against a deposit proven to have been finalised on +Ethereum, with no signer or federation trusted to attest to it (Functionality +#3). That verification, establishing Ethereum finality, proving inclusion of the +deposit under a finalised header, and emitting a verified statement, is +delivered as a shared primitive by +[RFP-022](./RFP-022-ethereum-state-attestation.md). This RFP consumes it and +does not rebuild it, so that the consensus verification path is audited once and +shared with the other LEZ programs that need to read Ethereum state. The +outbound leg, verifying a LEZ burn natively on Ethereum, is specific to this +bridge and remains in scope here. + #### Admin authority (RFP-001) The Functionality requirements specify that an admin authority registers and @@ -781,10 +804,11 @@ The UI must use the wallet SDK from the Lambda Prize wallet-SDK work. #### RISC0 zkVM -The bridge verifies proofs of consensus and state in-program on LEZ. Because LEZ -itself runs on RISC0, a production-ready zkVM, this leg of the design is a -LEZ-runtime dependency rather than a choice the proposal makes; proposals must -leverage mature RISC0 implementations (e.g. +The bridge verifies proofs in-program on LEZ (the deposit attestation from +RFP-022 on the inbound leg, and the bridge's own claim and burn logic +throughout). Because LEZ itself runs on RISC0, a production-ready zkVM, this leg +of the design is a LEZ-runtime dependency rather than a choice the proposal +makes; proposals must leverage mature RISC0 implementations (e.g. [Zisk](https://github.com/risc0/zisk)) for LEZ-side proving rather than building custom circuits. @@ -843,6 +867,9 @@ All code must be released under the **MIT+Apache2.0 dual License**. external assets as priced collateral) - [RFP-020 — RedStone Off-Chain Oracle Adaptor for LEZ](./RFP-020-redstone-oracle-adaptor.md) (reference for in-program proof verification cost measurement) +- [RFP-022 — Trustless Ethereum State Attestation for LEZ](./RFP-022-ethereum-state-attestation.md) + (delivers the verification of finalised Ethereum state that the inbound mint + path consumes) - [LP-0012: Event/Log mechanism for LEZ](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) - [LP-0013: Token program improvements: authorities](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md) - [RISC0 — Zero-Knowledge VM](https://github.com/risc0/risc0) diff --git a/RFPs/RFP-022-ethereum-state-attestation.md b/RFPs/RFP-022-ethereum-state-attestation.md new file mode 100644 index 00000000..f4b0d3a8 --- /dev/null +++ b/RFPs/RFP-022-ethereum-state-attestation.md @@ -0,0 +1,630 @@ +--- +id: RFP-022 +title: Trustless Ethereum State Attestation for LEZ +tier: M +status: open +category: Developer Tooling & Infrastructure +dependencies: + - id: RFP-001 + reason: Admin authority governs the weak-subjectivity checkpoint, the chain registry, and the finality parameters, as specified in Functionality. + - id: LP-0012 + reason: Structured on-chain events let clients and off-chain components follow committee handoffs and attestation submissions without polling every account. +--- + + + +# RFP-022 — Trustless Ethereum State Attestation for LEZ + +> **Note.** This specification describes an outcome that may benefit the Logos +> ecosystem. It is a proposal rather than an instruction. Its requirements +> reflect the technical compatibility with the Logos technology stack and are +> the criteria against which proposals and milestones are evaluated. Logos makes +> no representation as to the legal or regulatory treatment of this +> specification or any implementation of it in any jurisdiction. +> +> Teams implementing it are solely responsible for (i) assessing the risks and +> implications of what they build; (ii) obtaining their own professional advice; +> and (iii) for complying with any legal and regulatory requirements that apply +> to them. Software developed under the Program is published and maintained by +> its developers, not by Logos. +> +> Anyone who chooses to deploy, host, operate or use software developed under +> the Program, whether or not they were awarded a grant under the Program, does +> so at their own risk and is solely responsible for complying with any legal or +> regulatory requirements that apply to them. See the +> [Terms & Conditions](../TERMS_AND_CONDITIONS.md). +> +> Deploying the software described in this RFP, operating any service based on +> it, or carrying on business through it may amount to regulated activity in +> some jurisdictions, including where it involves holding or managing users' +> assets or providing services to others. Whoever conducts any such activity +> does so as principal, in their own name, and is solely responsible for +> assessing its regulatory treatment, including any licensing, registration, +> sanctions or anti-money laundering obligations that may apply to them. Logos +> does not make any representation, provides any advice or assumes any +> responsibility in respect of any such determination or compliance. + +## 🧭 Overview + +Build a reusable LEZ primitive that lets any LEZ program act on a fact about +Ethereum state and know that fact is true, with no trusted intermediary. + +A LEZ execution is self-contained: a program reads inputs from LEZ accounts and +instruction data, runs in the zkVM, and produces a proof that the execution was +correct **given those inputs**. Whether an input is a true statement about the +outside world is not something that proof covers. A program that mints against +"a deposit of amount X occurred on Ethereum" proves only that it minted given +the claim; the claim itself is uncertified, and whoever controls the input can +assert a deposit that never happened. + +This RFP delivers the missing piece: a LEZ module that verifies Ethereum +consensus and finality, verifies inclusion of a referenced piece of state under +a finalised Ethereum header, evaluates a predicate over that state, and emits a +**verified statement** with no application action attached. It takes an Ethereum +header, the consensus material needed to prove that header is finalised, an +inclusion proof, and a predicate to check. It returns a proven assertion that +any LEZ program can consume. + +The deliverable is deliberately application-free. Minting, escrow release, +settlement, and every other action belong to the consuming program. This RFP +delivers only the attestation, plus the tooling and documentation a consumer +needs to integrate it. + +Teams will need experience with Ethereum consensus and the light-client +protocol, Merkle-Patricia proof verification, and LEZ program development inside +the RISC0 zkVM. + +## 🔥 Why This Matters + +Every LEZ program that wants to react to something that happened on Ethereum +faces the same problem, and today each would have to solve it independently. Two +workstreams already need it, and they need the same thing: + +- **The wrapped-token bridge** ([RFP-021](./RFP-021-wrapped-erc20.md)). An + Ethereum vault escrows an ERC-20 or native ETH and a LEZ program mints a + canonical wrapped representation. Minting must happen only against a real, + finalised deposit, with no signer or federation trusted to attest to it. That + is a verified deposit statement feeding a mint. RFP-021 already requires + trustless verification of Ethereum consensus and state rather than an + inclusion check alone; this RFP is where that verification is specified and + built. +- **Private cross-chain swaps.** A cross-chain swap that settles on the users' + home chains, with no liquidity resting on LEZ, needs LEZ to confirm that both + legs deposited before it authorises release. Confirming the Ethereum leg is a + verified escrow statement, with no mint and no wrapped asset created. This is + the read-only consumer, using the same attestation with no minting action + attached. + +The two consumers do different things with the statement and carry different +trust and compliance surfaces, but they rely on the same attestation. That is +the case for building it once, as a shared primitive with a single audited +verification path, rather than twice inside two applications. It also means the +hardest and most security-critical part of a cross-chain design (consensus +verification) gets one audit, one test suite, and one set of documented trust +assumptions, instead of one per consumer. + +Building it once has a second consequence worth stating: it lowers the barrier +for any future LEZ program that wants to read Ethereum. Cross-chain lending +collateral checks, governance actions mirrored from an Ethereum DAO, proof of +holding an Ethereum-side asset, and airdrop eligibility derived from historic +Ethereum state all reduce to "evaluate a predicate over finalised Ethereum +state", which is exactly what this primitive returns. + +## 🏗 Design Rationale + +### Why an inclusion proof alone is not enough + +The tempting shortcut is to verify an inclusion proof: supply a state root or +block header along with a Merkle path showing the state is included under that +root, and check the path inside the zkVM. That step is necessary and it is not +sufficient. + +Given a chosen state, anyone can construct a header and a set of Merkle paths +that are internally consistent with it. An inclusion proof verifies that a leaf +is included under a **supplied** root. Whether that supplied root is the root of +the real Ethereum chain stays unchecked. A party free to choose the root can +fabricate a self-consistent state in which any deposit they like appears to +exist, generate a valid inclusion proof against it, and pass verification. The +zkVM proof will be sound. It will be proving a statement about a fabricated +Ethereum. + +The missing ingredient is an anchor to canonical Ethereum. Verification has to +establish that the header it reasons about is a header the Ethereum network +agreed on, before any inclusion check against it carries meaning. + +### The anchor: Ethereum finality via the sync committee + +The anchor comes from Ethereum finality. Under proof of stake, Ethereum +finalises checkpoints: once a checkpoint is justified and then finalised, +roughly two epochs after a block, reverting it requires a consensus failure +severe enough to slash at least a third of all staked ETH. The light-client +protocol exposes this through finality updates, and a sync committee of 512 +validators, rotating every sync-committee period, signs headers so a light +client can follow the finalised chain by checking committee signatures. The +beacon state holds `current_sync_committee` and `next_sync_committee`, so the +next committee is known a period ahead and handoffs can be followed forward. A +party tracking the sync committee can confirm that a given header is a finalised +header of the canonical chain without running a full node. + +An attestation therefore establishes three things, in this order: + +1. **Finality.** The supplied Ethereum header belongs to the finalised set, + verified against sync-committee signatures over the light-client finality + update. This is the basis the inclusion step depends on. +2. **Inclusion.** The referenced state or event (a deposit, a contract storage + slot, a log) is included under that finalised header's state or receipts + root, verified by Merkle proof. +3. **Predicate.** A statement over that verified state holds, for example + "contract C holds an escrow of amount X in token T". + +The output is a compact, proven assertion that the predicate holds of finalised +Ethereum state, carrying no trust in whoever generated the proof. A dishonest +prover cannot forge it, since forging it would require forging sync-committee +signatures over a finalised header. A dishonest prover can only decline to +produce a proof, which is why proof generation must be a liveness role rather +than a trust role: no single party may be able to turn a refusal into a block on +an honest user. + +### Trust assumptions the design carries + +The anchor is not free of assumptions, and both must be documented for consumers +rather than buried: + +- **Honest sync-committee supermajority.** Following the chain through committee + signatures trusts that at least two thirds of the current 512-validator sync + committee are honest. This is weaker than Ethereum's full economic finality: a + committee that colludes or is compromised could sign a header off the + canonical chain, an expensive but real attack surface that verifying the full + validator set would avoid. It is the standard light-client trade-off, and the + proposal must state it plainly and quantify the cost of the attack it admits. +- **Weak-subjectivity checkpoint.** Sync-committee tracking only works starting + from a trusted checkpoint, a known-good committee, following handoffs forward + from there. That initial checkpoint is a trust anchor. The design is trustless + after bootstrap, given a correct starting committee, so the specification must + say who supplies the checkpoint, how a verifier confirms it independently, and + how it is refreshed if a deployment falls outside the weak-subjectivity + period. + +Applicants may propose a stronger anchor than sync-committee tracking (full +validator-set verification, or a hybrid) and are encouraged to state the cost +trade-off explicitly if they do. The sync-committee path is the expected +baseline because it is what the light-client protocol supports today at +tractable in-zkVM cost. + +### Chain binding + +The attestation carries which chain and which chain ID it refers to, so a +statement valid for one network is never accepted as valid for another. This is +not incidental: the same contract address exists on mainnet and on every +testnet, and a design that omits the binding would let a testnet deposit satisfy +a mainnet predicate. + +### Uniqueness is the consumer's job, not the primitive's + +Two sub-problems sit inside "act on an Ethereum fact": + +1. **Existence.** Did the referenced Ethereum state actually occur on the + canonical Ethereum chain? +2. **Uniqueness.** Has this particular piece of Ethereum state already been + consumed on LEZ, so that it cannot be acted on twice? + +This RFP delivers existence. Uniqueness is solvable with mechanisms LEZ already +has: a consuming program records a nullifier or a program-owned account marking +a given Ethereum event as spent and rejects any second attempt. That is standard +double-spend protection, and it belongs to the consumer because only the +consumer knows what "the same action" means for its own application: a bridge +mint must be once-per-deposit, whereas a read-only escrow check may legitimately +be evaluated many times. + +The primitive must nonetheless make uniqueness enforceable. Every verified +statement carries a deterministic, collision-resistant identifier derived from +the attested state itself, so a consumer can key a nullifier on it without +inventing its own derivation and without two consumers deriving incompatible +identifiers from the same event. Guidance on doing this correctly is a +documentation deliverable (Supportability #6). + +### What the attestation does not do + +**It does not hide the underlying Ethereum activity.** Ethereum state is public +by construction. Amounts and timing of deposits and releases are visible on the +public chain, and linking them to LEZ activity is a separate privacy problem, +handled by the consuming application through fixed denominations, delayed +submission, and anonymity-set growth (see [RFP-021](./RFP-021-wrapped-erc20.md), +Design Rationale, "The privacy requirement, stated precisely"). What this RFP +must guarantee is narrower and still essential: verifying and consuming an +attestation must not itself add a new correlation signal beyond what Ethereum +already exposes. A consumer that does its own privacy work correctly must not +have that work undone by the attestation path, which is why the verified +statement's public inputs are constrained in Functionality #8. + +**It does not verify LEZ state on Ethereum.** The reverse direction, proving a +LEZ event natively on Ethereum, is specific to the bridge and stays in +[RFP-021](./RFP-021-wrapped-erc20.md). + +### Consumption model + +The primitive is delivered as a library callable from a consuming LEZ program, +not only as a standalone program with an account interface. A consumer must be +able to verify an attestation inline within its own transaction, so that +verification and the action it authorises are atomic and the consumer never has +to trust an intermediate account written by someone else. + +A standalone program that verifies and records attestations to a public account +is a legitimate additional deployment shape, since it lets cost be amortised +when many consumers care about the same Ethereum state, and it is specified as a +soft requirement rather than a hard one. Where both shapes exist they must share +a single verification core, so the audit surface and the cost profile stay +common, following the pattern established in +[RFP-020](./RFP-020-redstone-oracle-adaptor.md). + +### Cost is a primary deliverable + +Whether sync-committee signature verification and Merkle-Patricia proof +verification fit inside a LEZ transaction budget, and at what cost, is the +central open question of this RFP. Signature verification inside RISC0 is known +to be expensive: prototype work on in-program secp256k1 ECDSA verification +([`fryorcraken/lez-signature-bench`](https://github.com/fryorcraken/lez-signature-bench)) +showed costs high enough to foreclose some designs on LEZ, and the sync +committee signs with BLS12-381 aggregate signatures, a different and heavier +primitive. Measuring and documenting the real cost, with a breakdown by +component, is therefore a first-class deliverable and not a side report, exactly +as it was for RFP-020. Consumers cannot size their own designs without those +numbers, and if the cost turns out to be unacceptable the measurement is the +input to a follow-on RFP proposing a BLS12-381 precompile for LEZ. + +## ✅ Scope of Work + +### Hard Requirements + +Use FURPS framework. Each numbered item should be a testable statement. + +#### Functionality + +01. Implement sync-committee tracking: given a trusted starting checkpoint, + verify light-client updates and committee handoffs so the module can follow + the canonical finalised chain forward across sync-committee periods without + running a full node. +02. Verify that a supplied Ethereum block header is finalised, by checking + sync-committee signatures over the light-client finality update, and reject + any header that is not. +03. Verify Merkle-Patricia inclusion of a referenced piece of state under a + verified finalised header: at minimum an account, a contract storage slot, + and a receipt or log. Reject any inclusion proof that does not verify + against the header's state or receipts root. +04. Evaluate a predicate over the verified state and emit a verified statement + asserting that the predicate holds of finalised Ethereum state. The + predicate interface must support at least equality and inequality + comparisons over attested values, and must be expressible by a consuming + program without modifying the module. +05. The verified statement binds the chain identity (network and chain ID) it + refers to. A statement produced against one chain must be rejected by a + verifier configured for another, tested across mainnet and at least one + testnet with the same contract address on both. +06. The verified statement carries a deterministic, collision-resistant + identifier derived from the attested Ethereum state, suitable for a consumer + to key a nullifier on. Identical Ethereum state yields an identical + identifier; distinct state yields a distinct one. +07. The module is callable as a library from a consuming LEZ program, so that + verification and the action it authorises occur in a single transaction. A + consumer must be able to integrate without depending on any account written + by a third party. +08. Verifying and consuming an attestation must not introduce any correlation + signal beyond what is already public on Ethereum. The public inputs of the + verified statement must be limited to what the consumer explicitly chooses + to expose, and must not reveal the identity of the consuming LEZ account or + the consuming transaction. Provide a test asserting this over full event and + state diffs. +09. An admin authority (per [RFP-001](./RFP-001-admin-authority-lib.md), + integrated via the [SPEL framework](https://github.com/logos-co/spel) where + applicable) can configure the weak-subjectivity checkpoint, the supported + chain and chain ID, and the finality parameters, per deployment. Document a + procedure by which anyone can independently verify a configured checkpoint + against public Ethereum sources before relying on the deployment. +10. Provide a checkpoint-refresh path for a deployment that has fallen outside + the weak-subjectivity period, and document when a deployment is required to + use it. +11. Proof generation must be a permissionless liveness role: no specific party + may be required to produce an attestation, and any party declining to act + must not block a user. Proposals must identify every off-chain participant + the design requires and justify that none of them, individually or as a + class, can block an attestation from eventually being produced. +12. The design must not assume Ethereum mainnet is the only target. The same + module must be deployable, unmodified, against any Ethereum-consensus chain, + mainnet or testnet, with the chain binding in Functionality #5 keeping + deployments separate. + +#### Usability + +1. Build the attestation functionality for both consumers and admins in a Logos + core module, so that different Logos ui modules can be built on it: producing + an attestation, verifying one, and reading and administering the checkpoint + and chain configuration. +2. Provide a CLI that covers producing an attestation for a given + `(chain, contract, storage slot or log, predicate)` tuple, verifying one + off-chain as a dry run, and reading and administering the configuration. The + dry run must report the same typed error codes the on-chain path returns. +3. Any long-running off-chain component the design requires (for example a + process that follows sync-committee handoffs and keeps update material + available) must be provided as a **Logos module accompanied by a Logos Core + headless CLI/daemon**, runnable standalone, supporting configurable Ethereum + consensus and execution RPC endpoints, structured logging, and a clean + shutdown path. Document the operator journey end-to-end: install, configure, + run, monitor. +4. Provide an IDL for the LEZ-side module using the + [SPEL framework](https://github.com/logos-co/spel). +5. Return clear, actionable error messages for all failure modes: header not + finalised, sync-committee signature invalid, committee handoff not verified, + checkpoint stale or outside the weak-subjectivity period, inclusion proof + invalid, predicate not satisfied, chain-ID mismatch, and malformed input. + +#### Reliability + +1. Verification is deterministic: the same inputs always yield the same verdict, + independently reproducible from the test suite. +2. Verification is read-only with respect to consumer state: a rejected + attestation consumes nothing and leaves the consumer able to retry. +3. A verified statement over a finalised header remains valid indefinitely. + Later Ethereum activity, including subsequent sync-committee rotations, must + never invalidate an attestation that was valid when produced. +4. Committee handoff tracking survives interruption: a component restarted after + an outage resumes from its last verified state without re-verifying from the + original checkpoint, and without accepting a handoff it has not verified. +5. Temporary RPC or connectivity failure on the Ethereum side leaves any + off-chain component in a recoverable state, able to resume without + duplicating work already done. +6. Proposals must integrate mature, audited implementations of BLS12-381 + signature verification, Merkle-Patricia proof verification, and the + light-client protocol rather than reimplementing cryptographic primitives + from scratch. +7. CI must be green on the default branch. + +#### Performance + +1. Verifying an attestation and evaluating its predicate must complete within a + single LEZ transaction at the per-transaction compute budget in force at + delivery time, in the library consumption path of Functionality #7. If this + proves infeasible at delivery time, the measurement in Performance #2 stands + as the deliverable and the shortfall must be documented with the specific + component responsible. +2. Cost measurement is a primary deliverable, not a side report. Measure and + document, with a breakdown by component: BLS12-381 aggregate signature + verification over a sync-committee update, committee handoff verification, + Merkle-Patricia inclusion proof verification for an account, a storage slot + and a log, and predicate evaluation. Report compute units, proof time, and + proof size for each, extending the measurement methodology from + [RFP-020](./RFP-020-redstone-oracle-adaptor.md). Numbers must be reproducible + from the test suite. +3. Document the amortised per-attestation cost of sync-committee tracking at the + recommended operating cadence, separately from the per-attestation + verification cost, since the two amortise differently across consumers. +4. Any proving the user's own device must perform has to be practical on the + desktop hardware Basecamp runs on. Measure and document wall-clock time and + peak memory on a mid-range laptop and on the lowest specification the team + declares as supported, and state that minimum explicitly. +5. Document end-to-end attestation latency, from the Ethereum event to a + verified statement usable on LEZ, broken down by finality wait, update + availability, proof generation, and on-chain verification. +6. Document the compute resources (CPU, RAM, time) required to run any off-chain + component the design requires. +7. Document the growth rate and on-chain storage cost of any module state that + accumulates with usage, in particular committee-tracking state, with + projections over one and five years of continuous operation. +8. Document the cost delta between the in-program BLS12-381 path and a + hypothetical native precompile, so the measurement can inform whether a + follow-on precompile RFP is warranted. + +#### Supportability + +01. The module is deployed and tested on LEZ testnet, attesting to state on a + public Ethereum testnet. +02. End-to-end integration tests exercise attestation production and consumption + against a LEZ sequencer (standalone mode) and an Ethereum test network or + local fork, and are included in CI. +03. Every hard requirement in Functionality, Usability, Reliability, and + Performance has at least one corresponding test. +04. A README documents end-to-end usage: module addresses, deployment steps, + configuration of the checkpoint and chain, and step-by-step instructions for + producing and consuming an attestation via the CLI. +05. Submit a + [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) + for the core module, covering the developer integration journey for a + consuming LEZ program. +06. The consumer documentation must include a **"Recommended Consumer Pattern"** + section covering: enforcing uniqueness with a nullifier keyed on the + statement identifier from Functionality #6, verifying the chain binding + matches the consumer's expectation, handling each typed error code, and the + recommended behaviour when an attestation cannot be produced (refuse the + action, never fall back to an unverified input). +07. Submit a + [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) + for the CLI and any operator-facing components, covering the core user and + operator journeys respectively. +08. Provide a **trust assumptions document** covering: the honest sync-committee + supermajority assumption and the cost of the attack it admits; the + weak-subjectivity checkpoint, who supplies it and how a verifier confirms it + independently; what an attestation does and does not prove; what every + off-chain participant in the design can observe; and the conditions under + which the guarantees degrade or fail. +09. The module undergoes an independent third-party security audit of the + consensus and inclusion verification logic before any mainnet-facing + deployment; the audit report must be published. +10. The deliverable must be published on the module catalog. +11. The repository must use the standard Logos GitHub Actions. + +#### + Verification Security + +1. Verification must reject a fabricated chain: given a self-consistent header + and inclusion proof over state that was never finalised on the canonical + chain, verification must fail. This is the central adversarial test of the + RFP and must be exercised explicitly, not implied by other tests. +2. Verification must reject: a header signed by a committee that was never + validly handed off from the configured checkpoint; a sync-committee signature + below the required participation threshold; a valid inclusion proof against a + header that is not finalised; a valid finalised header with a tampered state + or receipts root; a proof replayed against a different chain ID; and a + predicate asserted over state the inclusion proof does not cover. +3. The verifier must be deployed as an immutable program with an explicit + migration path (deploy a new version, redirect consumers to it) in preference + to an upgradeable one governed by a mutable key. Legitimate, authorised + upgrades have shipped catastrophic verification bugs in production bridges + (see + [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)), + which an immutable program forecloses by construction. Document the migration + mechanism and how consumers are expected to move across a migration. +4. Document the failure modes that follow from a compromised or colluding sync + committee, and what a consuming application can do to bound its exposure (for + example, caps and freeze authorities on the consumer side, as + [RFP-021](./RFP-021-wrapped-erc20.md) specifies). +5. User-facing and developer-facing documentation must state the trustless + verification model and the liveness-only role of any off-chain participant + (see Design Rationale, "The anchor: Ethereum finality via the sync + committee"). + +### Soft Requirements + +1. **Standalone attestation program.** In addition to the library path + (Functionality #7), provide a LEZ program that verifies attestations and + records verified statements to a public account, so cost can be amortised + when many consumers care about the same Ethereum state. It must share a + single verification core with the library path, following the pattern in + [RFP-020](./RFP-020-redstone-oracle-adaptor.md), so that the audit surface + and the cost profile stay common. + +2. **Batching.** Amortise verification cost across multiple attestations over + the same finalised header in a single transaction, analogous to the + multi-feed batching soft requirement in RFP-020. + +3. **Historical state.** Attest to state under a header older than the + currently-tracked finalised head, for example via historical summaries in the + beacon state, so a consumer can prove a fact about Ethereum's past rather + than only its recent finalised present. + +4. **Richer predicates.** Support predicates over multiple attested values in a + single statement (for example, an account balance and a storage slot under + the same header), so a consumer can express a compound condition without + producing and correlating several attestations. + +5. **Pluggable proof components.** Design the proof-system components so that + future zkVM improvements, proof compression, or hardware acceleration can be + adopted without restructuring the module or its consumer interface. + +6. **Additional chains.** Extend the attestation to other chains with a + light-client-verifiable consensus, each served by its own configuration per + Functionality #12. + +### Out of Scope + +The following are explicitly excluded from this RFP: + +- **Verifying LEZ state or events on Ethereum.** The reverse direction is + specific to the bridge and stays in [RFP-021](./RFP-021-wrapped-erc20.md). +- **Any application action.** Minting, escrow release, settlement, and every + other action belong to the consuming program. This RFP emits a verified + statement and stops there. +- **Uniqueness enforcement.** The primitive supplies the statement identifier + (Functionality #6) and the guidance (Supportability #6); the nullifier or + spent-marker itself belongs to the consumer (see Design Rationale, "Uniqueness + is the consumer's job, not the primitive's"). +- **Hiding Ethereum-side activity.** Ethereum state is public by construction. + Unlinkability between Ethereum activity and LEZ activity is the consuming + application's problem; this RFP's obligation is only to avoid adding a new + correlation signal (Functionality #8). +- **Adding a BLS12-381 precompile to LEZ.** The in-program path is the + deliverable here. A precompile becomes a candidate for a follow-on RFP if and + only if the cost measurement in Performance #2 shows the in-program path is + too expensive for production use. +- **Circuit optimisation or custom zkVM accelerators.** LEZ runs on RISC0, so + proposals should leverage mature existing implementations rather than + implementing novel circuits or optimisation techniques. + +## ⚠ Platform Dependencies + +### Hard dependencies + +#### Admin authority (RFP-001) + +The Functionality requirements specify that an admin authority configures the +weak-subjectivity checkpoint, the supported chain and chain ID, and the finality +parameters. These admin-gated functions require the standardised admin authority +library from [RFP-001](./RFP-001-admin-authority-lib.md). + +#### Event emission (LP-0012) + +Structured on-chain events let clients and off-chain components follow committee +handoffs and attestation submissions without polling every account. +[LP-0012](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) +is **closed** (delivered). + +#### RISC0 zkVM + +The module verifies Ethereum consensus and state in-program on LEZ. Because LEZ +itself runs on RISC0, a production-ready zkVM, this is a LEZ-runtime dependency +rather than a choice the proposal makes; proposals must leverage mature RISC0 +implementations (e.g. [Zisk](https://github.com/risc0/zisk)) for LEZ-side +proving rather than building custom circuits. + +#### Logos Ethereum core module + +Any Ethereum-side interaction, including fetching headers, update material, and +inclusion proofs, must use the Logos Ethereum core module, including its +verified proxy features. + +## 👤 Recommended Team Profile + +Team experienced with: + +- Ethereum consensus and the light-client protocol (sync committees, finality + updates, committee handoffs, weak subjectivity) +- BLS12-381 signature verification and aggregate signature schemes +- Merkle-Patricia trie proof verification against Ethereum state and receipts + roots +- Zero-knowledge proof systems and the RISC0 zkVM (guest program development, + proof generation and verification, public/private input handling, and cost + characterisation, since cost measurement is a primary deliverable) +- LEZ program development and on-chain proof verification +- Security auditing of consensus verification logic (fabricated-chain attacks, + replay, committee-handoff attacks, checkpoint staleness) +- Designing libraries consumed by other protocol teams, including interface + stability and integration documentation + +## ⏱ Timeline Expectations + +Estimated software delivery duration: **8–12 weeks**. The scope is a single +primitive with no application logic, but sync-committee tracking, in-zkVM +BLS12-381 verification, and the cost measurement deliverable are each +substantial. This excludes the third-party audit lead time required before any +mainnet-facing deployment (Supportability #9), which is typically procured and +scheduled separately. + +## 🌍 Open Source Requirement + +All code must be released under the **MIT+Apache2.0 dual License**. + +## Resources + +- [RFP-001 — Admin Authority Library](./RFP-001-admin-authority-lib.md) +- [RFP-003 — Atomic Swaps](./RFP-003-atomic-swaps.md) (trustless swap path for + chains without general smart-contract expressiveness) +- [RFP-020 — RedStone Off-Chain Oracle Adaptor for LEZ](./RFP-020-redstone-oracle-adaptor.md) + (reference for in-program verification cost measurement, and for the shared + verification core between a library and a program deployment shape) +- [RFP-021 — Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ](./RFP-021-wrapped-erc20.md) + (primary consumer; the mint side depends on this attestation) +- [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md) + (bridge failure taxonomy, including verification-logic bugs) +- [LP-0012: Event/Log mechanism for LEZ](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) +- [Ethereum Altair light-client specification](https://github.com/ethereum/consensus-specs/tree/dev/specs/altair/light-client) +- [Ethereum weak subjectivity specification](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/weak-subjectivity.md) +- [RISC0 — Zero-Knowledge VM](https://github.com/risc0/risc0) +- [Zisk — RISC0 Proof Generation](https://github.com/risc0/zisk) +- [`fryorcraken/lez-signature-bench`](https://github.com/fryorcraken/lez-signature-bench) + (prototype measurements of in-program signature verification cost on RISC0) + +## ✏️ How to Apply + +👉 Submit a proposal using the Issue form: + +**[Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml)** + +We typically respond within **14 days**. For clarification questions, please use +**Discussions**. From 8c0e01215034fa42a07ea0a66faa39523de7778f Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Fri, 14 Aug 2026 14:22:23 +1000 Subject: [PATCH 55/69] RFP-023: add native gas token bridge, inverting RFP-021's roles RFP-021 carried gas-token bootstrapping as a soft requirement asking only for research. Deliver it properly as its own RFP: the LEZ program is the vault holding native gas token, the Ethereum contract is the minter, and the two directions mirror RFP-021 with the chains swapped. This closes a gap in the corpus. RFP-004, 008, 012 through 017 all fund gas by atomic deshield from the user's own shielded balance, precisely so no external funding source links the ephemeral account to an identity. That pattern presupposes the user already has funds on LEZ and says nothing about how they got there. RFP-023 is the trustless entry path for a user holding nothing. Supply is demand-driven: the ERC-20 is minted against proof of a lock in the LEZ vault and burned to release from it, so there is no float to seed and no incentive mechanism to design. The invariant that makes this sound is that the ERC-20 has no privileged minter and no pre-issued supply, which is exactly the Meter Passport failure mode already documented in the appendix. Privacy mirrors RFP-021 in full: each leg of each bridge has one public endpoint and it is the Ethereum one in every case. The one genuinely new problem is releasing native gas to a recipient who has none. Hard requirement that this must work for a zero-balance account with no required off-chain counterparty; mechanism left to the proposal. RFP-021 Soft Requirement #8 becomes a pointer to RFP-023. RFP-022 gains it as a third consumer of the attestation primitive. Co-Authored-By: Claude Opus 5 --- .github/ISSUE_TEMPLATE/proposal.yml | 1 + README.md | 1 + RFPs/RFP-021-wrapped-erc20.md | 26 +- RFPs/RFP-022-ethereum-state-attestation.md | 28 +- RFPs/RFP-023-gas-token-bridge.md | 741 +++++++++++++++++++++ 5 files changed, 770 insertions(+), 27 deletions(-) create mode 100644 RFPs/RFP-023-gas-token-bridge.md diff --git a/.github/ISSUE_TEMPLATE/proposal.yml b/.github/ISSUE_TEMPLATE/proposal.yml index d3eea9ab..6ae0ea2a 100644 --- a/.github/ISSUE_TEMPLATE/proposal.yml +++ b/.github/ISSUE_TEMPLATE/proposal.yml @@ -16,6 +16,7 @@ body: - "RFP-017 — Privacy-Preserving Token Vesting" - "RFP-021 — Wrapped ERC-20 Bridge for LEZ" - "RFP-022 — Trustless Ethereum State Attestation for LEZ" + - "RFP-023 — Native Gas Token Bridge for LEZ" validations: required: true diff --git a/README.md b/README.md index 3fa023ab..c2798408 100644 --- a/README.md +++ b/README.md @@ -91,6 +91,7 @@ Click an RFP to view details. Use the Submit Proposal button to apply. | RFP-020 | [RedStone Off-Chain Oracle Adaptor for LEZ](RFPs/RFP-020-redstone-oracle-adaptor.md) | M | closed | - | Developer Tooling & Infrastructure | Closed | | RFP-021 | [Wrapped ERC-20 Bridge for LEZ](RFPs/RFP-021-wrapped-erc20.md) | L | open | - | Developer Tooling & Infrastructure | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | | RFP-022 | [Trustless Ethereum State Attestation for LEZ](RFPs/RFP-022-ethereum-state-attestation.md) | M | open | - | Developer Tooling & Infrastructure | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | +| RFP-023 | [Native Gas Token Bridge for LEZ](RFPs/RFP-023-gas-token-bridge.md) | M | open | - | Developer Tooling & Infrastructure | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 81227fa4..53be0f2c 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -714,23 +714,13 @@ Use FURPS framework. Each numbered item should be a testable statement. improvements, proof compression, or hardware acceleration can be adopted without restructuring the vault or the bridge program. -8. **Gas-token bootstrapping.** Run the bridge in reverse for a zone's native - gas token: an ERC-20 on Ethereum represents it, locking that ERC-20 on - Ethereum releases native gas token on LEZ, and locking gas token on LEZ - releases the ERC-20 on Ethereum. This lets a user who holds nothing on the - zone acquire gas from Ethereum, rather than being unable to make a first - transaction for want of gas. - - A proposal does not need to solve this. Committing to research it and to - report the findings is enough, and a proposal may also implement it. Either - way, the open question to address is how the Ethereum-side supply of the - ERC-20 is initially issued and replenished, since no external market mints it - the way one does for a wrapped external asset. If the conclusion is that this - cannot be done here, or only under different trust or custody assumptions - than the primary flow, the research should say why and name the bootstrapping - mechanism (faucet, gas sponsorship, meta-transactions) that would be needed - instead. Any implementation is held to the same privacy, caps, freeze - authority, and finality requirements as the primary flow. +8. **Reverse direction for a zone's native gas token**, letting a user who holds + nothing on the zone acquire gas from Ethereum, is delivered separately by + [RFP-023](./RFP-023-gas-token-bridge.md), which inverts the roles so that the + LEZ program is the vault and the Ethereum contract is the minter. It builds + on the vault, mint, and privacy construction specified here. Proposals for + this RFP are not asked to address it, but should avoid design choices that + would make the reverse direction harder to build on the same patterns. ### Out of Scope @@ -870,6 +860,8 @@ All code must be released under the **MIT+Apache2.0 dual License**. - [RFP-022 — Trustless Ethereum State Attestation for LEZ](./RFP-022-ethereum-state-attestation.md) (delivers the verification of finalised Ethereum state that the inbound mint path consumes) +- [RFP-023 — Native Gas Token Bridge for LEZ](./RFP-023-gas-token-bridge.md) + (the reverse direction, with LEZ as the vault, built on this RFP's patterns) - [LP-0012: Event/Log mechanism for LEZ](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) - [LP-0013: Token program improvements: authorities](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md) - [RISC0 — Zero-Knowledge VM](https://github.com/risc0/risc0) diff --git a/RFPs/RFP-022-ethereum-state-attestation.md b/RFPs/RFP-022-ethereum-state-attestation.md index f4b0d3a8..f02bfe02 100644 --- a/RFPs/RFP-022-ethereum-state-attestation.md +++ b/RFPs/RFP-022-ethereum-state-attestation.md @@ -77,8 +77,8 @@ the RISC0 zkVM. ## 🔥 Why This Matters Every LEZ program that wants to react to something that happened on Ethereum -faces the same problem, and today each would have to solve it independently. Two -workstreams already need it, and they need the same thing: +faces the same problem, and today each would have to solve it independently. +Three workstreams already need it, and they need the same thing: - **The wrapped-token bridge** ([RFP-021](./RFP-021-wrapped-erc20.md)). An Ethereum vault escrows an ERC-20 or native ETH and a LEZ program mints a @@ -94,14 +94,20 @@ workstreams already need it, and they need the same thing: verified escrow statement, with no mint and no wrapped asset created. This is the read-only consumer, using the same attestation with no minting action attached. - -The two consumers do different things with the statement and carry different -trust and compliance surfaces, but they rely on the same attestation. That is -the case for building it once, as a shared primitive with a single audited -verification path, rather than twice inside two applications. It also means the -hardest and most security-critical part of a cross-chain design (consensus -verification) gets one audit, one test suite, and one set of documented trust -assumptions, instead of one per consumer. +- **The native gas token bridge** ([RFP-023](./RFP-023-gas-token-bridge.md)). + The reverse-direction counterpart to RFP-021, in which LEZ is the vault and + Ethereum the minter. Releasing native gas token from the LEZ vault requires + proof that the corresponding ERC-20 was really burned on Ethereum, which is + another verified statement over finalised Ethereum state, consumed by a + program doing something different again with it. + +These consumers do different things with the statement and carry different trust +and compliance surfaces, but they rely on the same attestation. That is the case +for building it once, as a shared primitive with a single audited verification +path, rather than separately inside each application. It also means the hardest +and most security-critical part of a cross-chain design (consensus verification) +gets one audit, one test suite, and one set of documented trust assumptions, +instead of one per consumer. Building it once has a second consequence worth stating: it lowers the barrier for any future LEZ program that wants to read Ethereum. Cross-chain lending @@ -610,6 +616,8 @@ All code must be released under the **MIT+Apache2.0 dual License**. verification core between a library and a program deployment shape) - [RFP-021 — Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ](./RFP-021-wrapped-erc20.md) (primary consumer; the mint side depends on this attestation) +- [RFP-023 — Native Gas Token Bridge for LEZ](./RFP-023-gas-token-bridge.md) + (consumer; the gas-token release path depends on this attestation) - [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md) (bridge failure taxonomy, including verification-logic bugs) - [LP-0012: Event/Log mechanism for LEZ](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) diff --git a/RFPs/RFP-023-gas-token-bridge.md b/RFPs/RFP-023-gas-token-bridge.md new file mode 100644 index 00000000..16bb5c42 --- /dev/null +++ b/RFPs/RFP-023-gas-token-bridge.md @@ -0,0 +1,741 @@ +--- +id: RFP-023 +title: Native Gas Token Bridge for LEZ +tier: M +status: open +category: Developer Tooling & Infrastructure +dependencies: + - id: RFP-021 + reason: Delivers the vault, mint, registry, caps and privacy construction this RFP inverts; the two bridges share their patterns and their proof-verification approach. + - id: RFP-022 + reason: The trustless Ethereum state attestation primitive is what the LEZ vault program uses to verify an ERC-20 burn really happened on Ethereum, as specified in Functionality. + - id: RFP-001 + reason: Admin authority governs the caps, the finality depth, and the chain and zone pairing, as specified in Functionality. + - id: RFP-002 + reason: Freeze authority provides the circuit breaker to halt minting and/or release if a proof-system or vault vulnerability is suspected. + - id: LP-0013 + reason: Token authority primitives are required for the LEZ vault program to escrow and release native gas token under program control. +--- + + + +# RFP-023 — Native Gas Token Bridge for LEZ + +> **Note.** This specification describes an outcome that may benefit the Logos +> ecosystem. It is a proposal rather than an instruction. Its requirements +> reflect the technical compatibility with the Logos technology stack and are +> the criteria against which proposals and milestones are evaluated. Logos makes +> no representation as to the legal or regulatory treatment of this +> specification or any implementation of it in any jurisdiction. +> +> Teams implementing it are solely responsible for (i) assessing the risks and +> implications of what they build; (ii) obtaining their own professional advice; +> and (iii) for complying with any legal and regulatory requirements that apply +> to them. Software developed under the Program is published and maintained by +> its developers, not by Logos. +> +> Anyone who chooses to deploy, host, operate or use software developed under +> the Program, whether or not they were awarded a grant under the Program, does +> so at their own risk and is solely responsible for complying with any legal or +> regulatory requirements that apply to them. See the +> [Terms & Conditions](../TERMS_AND_CONDITIONS.md). +> +> Deploying the software described in this RFP, operating any service based on +> it, or carrying on business through it may amount to regulated activity in +> some jurisdictions, including where it involves holding or managing users' +> assets or providing services to others. Whoever conducts any such activity +> does so as principal, in their own name, and is solely responsible for +> assessing its regulatory treatment, including any licensing, registration, +> sanctions or anti-money laundering obligations that may apply to them. Logos +> does not make any representation, provides any advice or assumes any +> responsibility in respect of any such determination or compliance. + +## 🧭 Overview + +Build the reverse-direction counterpart to +[RFP-021](./RFP-021-wrapped-erc20.md): a trustless, privacy-preserving bridge in +which **LEZ is the vault** and Ethereum is the minter, so a zone's native gas +token can be represented as an ERC-20 on Ethereum and acquired by someone who +holds nothing on the zone yet. + +A LEZ-side vault program escrows native gas token. Locking gas token in that +vault entitles the holder to mint the corresponding ERC-20 on Ethereum, on +cryptographic proof of the lock. Burning that ERC-20 on Ethereum entitles the +holder to release native gas token from the LEZ vault, on cryptographic proof of +the burn, verified in-program on LEZ via the attestation primitive from +[RFP-022](./RFP-022-ethereum-state-attestation.md). + +This is RFP-021's construction with the chains swapped, and it inherits that +RFP's requirements accordingly: the same trustless verification model, the same +unlinkability guarantees, the same caps and freeze authority, the same immutable +verifier preference. It is a separate deliverable because the roles invert. The +vault logic and the mint logic move to opposite chains, which makes the LEZ +program the thing holding value and the Ethereum contract the thing issuing a +representation, with a correspondingly different audit target. + +One problem is genuinely new and has no analogue in RFP-021: releasing native +gas token to a recipient who, by construction, has no gas with which to pay for +the release. + +Teams will need experience with zero-knowledge proof systems, privacy-preserving +protocol design, Solidity smart-contract development, and LEZ program +development. + +## 🔥 Why This Matters + +Every other LEZ application RFP assumes the user already holds gas. The +privacy-preserving DEX ([RFP-004](./RFP-004-privacy-preserving-dex.md)), the +lending protocol ([RFP-008](./RFP-008-lending-borrowing-protocol.md)), the +curated vaults ([RFP-012](./RFP-012-curated-lending-vaults.md)), the reflexive +stablecoin ([RFP-013](./RFP-013-reflexive-stablecoin-protocol.md)), the +liquidation engine ([RFP-014](./RFP-014-liquidation-auction-engine.md)), both +launchpads ([RFP-015](./RFP-015-bonding-curve-launchpad.md), +[RFP-016](./RFP-016-lbp-launchpad.md)) and token vesting +([RFP-017](./RFP-017-token-vesting.md)) all converge on the same pattern: gas is +funded by an atomic deshield from the user's own shielded balance, in a single +indivisible action, precisely so that no external funding source links the +ephemeral account to an existing identity. RFP-004 states the constraint +directly: funding the operation account from any external source, such as a CEX +withdrawal or a known wallet, creates an on-chain link and breaks the privacy +guarantee. + +That pattern is correct, and it presupposes the user already has funds on LEZ. +It says nothing about how they got there. A user arriving with nothing cannot +deshield, cannot pay for a first transaction, and cannot use any of the above. +The conventional answers, a faucet or a centralised on-ramp, are either unsuited +to production or reintroduce exactly the identity link the atomic-deshield +pattern exists to avoid. + +This RFP is the trustless entry path. Someone who holds ETH and an Ethereum +wallet can acquire native gas token by burning an ERC-20 representation, with no +custodian, no faucet operator, and no funding source that links their new LEZ +account to their Ethereum identity. It closes the loop that RFP-021 opens: +RFP-021 brings external *value* onto LEZ as wrapped assets, but a user still +needs gas to do anything with it, and wrapped USDC does not pay for a +transaction. Together the two bridges make a user's first interaction with a +zone possible without trusting anyone. + +The same mechanism serves an operational need beyond onboarding. A zone's native +gas token becomes transferable and tradeable on Ethereum, where liquidity and +tooling already exist, which gives the token a market that does not depend on +the zone having bootstrapped its own DEX first. + +## 🏗 Design Rationale + +### Inverted roles + +In RFP-021, the Ethereum contract is the vault and the LEZ program is the +minter. Here the roles swap: + +- **Outbound (LEZ to Ethereum).** A user locks native gas token in the LEZ vault + program. Proof of that lock entitles the holder to mint the corresponding + ERC-20 on Ethereum. The proof is verified natively on Ethereum, the same + problem RFP-021 solves for its burn-to-release leg. +- **Inbound (Ethereum to LEZ).** A user burns the ERC-20 on Ethereum. Proof of + that burn entitles the holder to release native gas token from the LEZ vault. + The proof is verified in-program on LEZ, consuming the attestation primitive + from [RFP-022](./RFP-022-ethereum-state-attestation.md) rather than rebuilding + Ethereum consensus and inclusion verification. + +Everything else follows RFP-021. The requirements below mirror it item for item +wherever the mirroring is exact, and say so rather than restating the reasoning. + +### Supply is demand-driven, and the ERC-20 has no privileged minter + +The ERC-20 is not a float that anyone stocks in advance. It comes into existence +only when someone locks native gas token in the LEZ vault, and it leaves +existence only when someone burns it to release that gas token. Supply tracks +demand by construction, exactly as the wrapped-token supply does in RFP-021, and +no seeding, replenishment, or market-making mechanism is required to make the +mechanism work. + +The invariant that makes this sound is that the ERC-20 has **no privileged +minter and no pre-issued supply**. Every unit in existence is backed by gas +token locked on LEZ; burning is the only way to unlock it. An admin authority, a +deployer, or any other party must have no path to mint a single unit without a +corresponding lock. This is stated as a testable requirement in Bridge Security +#5. + +That invariant is not a theoretical concern. Meter Passport's auto-wrap and +unwrap convenience feature for native gas tokens did not properly restrict +direct interaction with the wrapped ERC-20 contracts, nor verify that a matching +real value transfer had occurred, which let an attacker mint WETH and WBNB +without depositing collateral, for a direct loss of roughly $4.3M and a further +~$3.3M cascading into a dependent lending protocol (see +[Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)). +It is the one documented cross-chain bridge hack specifically about wrapping +native gas tokens, and it is the exact failure this RFP's invariant and its +associated tests exist to foreclose. + +One consequence is worth documenting for users rather than designing against: a +newcomer can only obtain the ERC-20 if someone has already moved gas token +outward to Ethereum and made it available. That is an ordinary liquidity +property of any two-way bridge, not a protocol requirement, and the +documentation must set the expectation plainly rather than implying the bridge +manufactures gas from nothing. + +### The gas circularity + +Releasing native gas token from the LEZ vault requires a LEZ transaction, and +the recipient of that release is, in the motivating case, someone who holds no +gas token at all. If claiming the release requires the claimant to already hold +gas, the bridge does not solve the problem it exists to solve. + +This RFP requires the release path to work for a recipient with a zero balance +(Functionality #4) but does not mandate how. Several shapes are viable, and +which is best depends on LEZ capabilities at delivery time: a permissionless +relayer paid out of the released amount, with the destination bound into the +proof so the relayer can neither redirect funds nor overcharge, which is the +mechanism RFP-021 already relies on for its fee-payer mitigation; a +protocol-level fee abstraction if LEZ offers one; or sequencer-level sponsorship +for this specific program. + +Whatever the mechanism, it is bound by RFP-021's trust model: no specific +relayer or off-chain party may be a required counterparty, any such role must be +permissionless so that a single participant declining to act never blocks the +user, and no participant may be able to steal, redirect, forge, censor +selectively, or deanonymise. It is also bound by the privacy requirement below, +which is the harder constraint: whoever pays for the release must not become a +correlation signal that links the Ethereum burn to the LEZ account receiving the +gas. + +### Privacy mirrors RFP-021 exactly + +The privacy construction carries over with the chains swapped, and it carries +over in full. Each leg of each bridge has exactly one public endpoint, and it is +the Ethereum endpoint in both: + +- RFP-021 inbound: public Ethereum deposit, hidden LEZ mint destination. +- RFP-023 inbound: public Ethereum burn, hidden LEZ release destination. +- RFP-021 outbound: hidden LEZ burn, public Ethereum release recipient. +- RFP-023 outbound: hidden LEZ lock, public Ethereum mint recipient. + +Minting an ERC-20 to a public Ethereum address reveals neither more nor less +than releasing one from escrow to a public Ethereum address. The hard +requirement is therefore identical to RFP-021's, with the terms substituted: +**no information other than amount, token, and timing may enable an adversary +who observes all public state on both chains, indefinitely, and who may +themselves use the bridge, to link an Ethereum burn to the LEZ release it +funded, or a LEZ lock to the Ethereum mint it triggered.** + +The three correlation points from RFP-021, "The privacy requirement, stated +precisely," apply unchanged and proposals must address each: amounts correlate +unless transfers are restricted to fixed per-token denominations; timing +correlates unless the protocol permits and the UI encourages delay; and fee +payers correlate, which here is sharpened by the gas circularity, since the +party paying for a release is structurally more visible than a user paying their +own way. + +### Finality, caps, freeze, and pairing + +These follow RFP-021 without modification in substance: a configured finality +condition on the source chain in each direction, admin-configurable per +deployment; global and per-deployment caps as a rate limiter independent of the +freeze authority; a freeze authority exercisable independently on each half; and +a strict pairing between a specific LEZ zone and program and a specific Ethereum +contract and chain ID, so a proof valid for one pairing is never accepted for +another. A claim once valid remains valid indefinitely, since users are expected +to delay their own submissions for privacy reasons. + +## ✅ Scope of Work + +### Hard Requirements + +Use FURPS framework. Each numbered item should be a testable statement. + +#### Functionality + +01. Implement a LEZ vault program that escrows native gas token. Locking must + support the gas token being held in, and locked from, either a private or a + public LEZ account, at the holder's choice. +02. A lock must not publish, store, or otherwise reveal its Ethereum + destination. No LEZ transaction argument, event, or account-state change may + identify the address that will receive the minted ERC-20. +03. Implement an Ethereum contract that mints the ERC-20 representation on + cryptographic verification of a valid LEZ lock, verified natively on + Ethereum. Verification must require no trusted party. +04. The LEZ vault releases native gas token on cryptographic verification of a + valid ERC-20 burn on Ethereum, consuming the attestation primitive from + [RFP-022](./RFP-022-ethereum-state-attestation.md) rather than implementing + its own Ethereum consensus and inclusion verification. **Claiming that + release must not require the recipient to already hold native gas token**, + and no specific relayer or other off-chain party may be a required + counterparty (see Design Rationale, "The gas circularity"). Test the release + path end to end with a recipient account holding a zero balance. +05. A burn on Ethereum must not publish, store, or otherwise reveal its LEZ + destination. +06. Releasing must support both a private LEZ account and a public LEZ account + as the destination, at the burner's choice. +07. Uniqueness is enforced in both directions: no lock can be minted against + twice and no burn released against twice, deterministically and under + adversarial retry. On the LEZ side this is keyed on the statement identifier + the RFP-022 attestation carries. +08. The amounts visible on Ethereum must not identify which lock or release they + correspond to. Proposals must state the mechanism chosen (fixed + denominations are the expected baseline) and its effect on anonymity-set + size. +09. A user must be able to recover every one of their own unclaimed locks and + unreleased burns from credentials they already hold, with no dependence on + any server-side index and no separately-backed-up secret generated during + the flow, on the same terms as RFP-021, "Loss of access." +10. An admin authority (per [RFP-001](./RFP-001-admin-authority-lib.md), + integrated via the [SPEL framework](https://github.com/logos-co/spel) where + applicable to the LEZ side) can configure the caps, the finality depth, and + the fee parameters per deployment. +11. Global caps, configurable by the admin authority, bound the maximum value + that can be minted or released within a rolling window, as a rate limiter + independent of the freeze authority. Cap enforcement must not require + identifying individual users. +12. The finality depth required before a lock may be minted against, and before + a burn may be released against, is configurable by the admin authority per + deployment. A change to the configured depth must not invalidate a claim + that was already valid under the previous depth. +13. A freeze authority (per [RFP-002](./RFP-002-freeze-authority-lib.md)) can + pause minting and/or release, on the Ethereum contract and the LEZ vault + program independently. +14. Each LEZ vault program deployment refers to a specific Ethereum contract + deployment on a specific chain (contract address plus chain ID), and + reciprocally each Ethereum contract deployment refers to a specific zone + instance (LEZ blockchain ID, zone ID, and program ID), with each pairing + checked as part of proof verification so a lock or burn valid for one + pairing is never accepted as valid for another. The same program and + contract design must be deployable, unmodified, against any EVM chain, + mainnet or testnet. +15. The design must let multiple entities each operate under their own + independent configuration (caps, fees, admin authority, finality depth), on + the same or different pairs of blockchain programs, with strict separation + between them: one entity's configuration must have no privileged access over + another's configuration or funds. Document how a client identifies and + switches between configurations. +16. A protocol fee may be charged on minting and on release, at a rate + configurable by the admin authority per deployment, including zero. The fee + value must not distinguish a user's transaction from others, consistent with + Functionality #8. Where the release-path mechanism compensates a relayer out + of the released amount, document how that compensation interacts with the + fixed-denomination requirement. + +#### Usability + +1. Build core functionalities for both users and admin in a Logos core module, + enabling the delivery of different Logos ui modules: locking gas token, + claiming the Ethereum mint, burning the ERC-20, claiming the LEZ release, + recovering a position from user credentials, and reading and administering + the configuration. +2. Provide a Logos mini-app, aka Logos ui module, covering both flows end to + end, position recovery, and a view showing permitted amounts, caps and + current utilisation. Also provide a UI for the admin functionality; whether + this is combined into one UI or delivered as two separate ones is left to the + applicant's choice. +3. The onboarding flow must be usable by someone who holds nothing on the zone. + The mini-app must not require a funded LEZ account to complete a release, and + must not present a step that silently assumes one. +4. Any long-running off-chain component the design requires must be provided as + a **Logos module accompanied by a Logos Core headless CLI/daemon**, runnable + standalone, supporting configurable RPC endpoints for both chains, + configurable finality depth, structured logging, and a clean shutdown path. + Document the operator journey end-to-end: install, configure, run, monitor. +5. Provide an IDL for the LEZ vault program using the + [SPEL framework](https://github.com/logos-co/spel). +6. The mitigations to the three correlation points in Design Rationale, "Privacy + mirrors RFP-021 exactly" (amount, timing, fee payer) must be enabled by + default. The mini-app and CLI must show a clear indicator of what data would + be leaked by the user's current choices, and default to the recommended + parameters rather than requiring the user to select them. +7. The mini-app and CLI must default to inviting the user to release into, and + lock from, a private account: the private path is the pre-selected option, + and choosing the public path requires an explicit action, consistent with + Privacy Preservation #8. +8. Documentation and UI must clearly explain what is public and what is private + at each step on both chains, and must set the expectation described in Design + Rationale, "Supply is demand-driven", that the ERC-20 is available only to + the extent someone has moved gas token outward. +9. Return clear, actionable error messages for all failure modes: invalid + amount, cap exceeded, verification failure, insufficient finality, already + claimed, and program frozen. Error messages must not reveal which lock or + burn a failed attempt referred to. + +#### Reliability + +1. Minting is atomic: a failed or rejected mint claim leaves the lock claimable + on retry and consumes nothing. +2. Release is atomic: a failed burn does not destroy the ERC-20 without + preserving the holder's entitlement to release, and a failed release leaves + that entitlement intact. +3. No lock can be minted against twice and no burn released against twice, + deterministically and under adversarial retry. +4. A valid claim remains valid indefinitely; later chain activity must never + invalidate a user's outstanding entitlement. +5. Position recovery is complete: a client restored from user credentials alone + must rediscover every claimable lock and unreleased burn, verified by a test + that wipes all local state. +6. Temporary RPC or connectivity failure on either chain leaves any off-chain + component in a recoverable state, able to resume without duplicating work + already done. +7. An interrupted user-side operation does not consume, corrupt, or expose the + user's entitlement. +8. Proposals must integrate mature, audited proof-system implementations rather + than reimplementing zero-knowledge primitives from scratch. +9. CI must be green on the default branch. + +#### Performance + +1. Verifying a burn and releasing gas token must complete within a single LEZ + transaction at the per-transaction compute budget in force at delivery time. + Document the compute-unit cost with a breakdown by component, separating the + RFP-022 attestation verification cost from this RFP's own logic, and + extending the measurement methodology from + [RFP-020](./RFP-020-redstone-oracle-adaptor.md). +2. Document the Ethereum-side gas cost of a mint, of a burn, and of the LEZ-lock + proof verification the mint requires. +3. Any proving the user's own device must perform has to be practical on the + desktop hardware Basecamp runs on. Measure and document wall-clock time and + peak memory on a mid-range laptop and on the lowest specification the team + declares as supported, and state that minimum explicitly. +4. Document end-to-end latency in both directions, each broken down by + source-chain finality wait, proof generation, any privacy-motivated delay, + and on-chain verification. +5. Document the compute resources (CPU, RAM, time) required to run any off-chain + component the design requires. +6. Document the growth rate and on-chain storage cost of all bridge state that + accumulates with usage, with projections at 1M and 10M operations. + +#### Supportability + +01. The LEZ vault program and the Ethereum contract are deployed and tested on a + LEZ testnet and a public Ethereum testnet respectively. +02. End-to-end integration tests exercise the full round trip in both directions + against a LEZ sequencer (standalone mode) and an Ethereum test network or + local fork, and are included in CI. One test must cover the motivating + journey end to end: a user with no LEZ account and no gas token acquires gas + and completes a first unrelated LEZ transaction. +03. Every hard requirement in Functionality, Usability, Reliability, + Performance, and Privacy Preservation has at least one corresponding test. +04. A README documents end-to-end usage: contract and program addresses, + deployment steps for both chains, and step-by-step instructions for both + directions via CLI and mini-app. +05. Submit a + [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) + for the core module, covering the developer integration journey for both + flows including position recovery. +06. Submit a + [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) + for the CLI and any operator-facing components, covering the core user and + operator journeys respectively. +07. Submit a + [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) + for the deployer journey, covering how an entity stands up its own + independently configured deployment (Functionality #15). +08. The Ethereum contract undergoes an independent third-party smart-contract + security audit before mainnet deployment; the audit report must be + published. The audit scope must explicitly include the mint authorisation + path, given the Meter Passport precedent in Design Rationale. +09. Provide a **privacy properties document** on the same terms as RFP-021, + Supportability #9, covering: a formal statement of Privacy Preservation #1 + and #2 and the anonymity set each is measured against; exactly what is + visible on-chain at every step on both chains; what an adversary observing + all public state can and cannot infer; what every off-chain participant can + observe, with specific attention to whoever pays for a release; residual + leakage from timing, amount selection, fee payment, network metadata and + usage patterns; and the conditions under which the guarantees degrade. +10. Document the anonymity-set growth model: expected set size over time at + projected volumes, the minimum below which the guarantees are considered not + to hold, and guidance for users bridging before the pool has matured. +11. The UI must let users change the targeted Ethereum RPC address and the + targeted LEZ sequencer or zone. +12. The deliverable must be published on the module catalog. +13. The repository must use the standard Logos GitHub Actions. + +#### + Bridge Security + +1. Proof verification must be independently verifiable. Both the LEZ vault + program and the Ethereum contract must reject invalid proofs, tested with + incorrect public inputs, proofs for incorrect chain state, tampered headers, + and replayed proofs. +2. A malicious party submitting on a user's behalf must not be able to redirect + funds, inflate their fee, or replay the user's submission to a different + destination: a lock and a burn must each secretly commit to the destination + on the other chain, so that the claim can only be completed by whoever holds + the seed or credentials that produced the commitment. Test that an adversary + who observes everything public about a lock or burn, but does not hold the + originating seed, cannot construct a valid claim for a different destination. + This applies with particular force to the release path, where a relayer may + be submitting on behalf of a user who cannot submit for themselves. +3. Caps (Functionality #11) bound the maximum value at risk in any rolling + window; proposals must document recommended defaults and the reasoning. +4. The freeze authority (Functionality #13) must be exercisable independently on + each half, so either can be paused without the other being operational or + reachable. +5. **Soundness of supply.** Total supply of the ERC-20 on Ethereum must never + exceed the native gas token locked in the LEZ vault. The ERC-20 must have no + privileged minter and no pre-issued supply: every unit in existence is backed + by gas token locked on LEZ, and burning it is the only way to unlock that gas + token. Provide tests attempting to mint without a valid lock, mint twice from + one lock, release without a valid burn, and release twice from one burn. + Testing must explicitly include attempts to mint via any admin, deployer, + owner, or upgrade path, and any path that interacts with the ERC-20 contract + directly rather than through the bridge entry point, since that is the + documented Meter Passport failure mode (see Design Rationale, "Supply is + demand-driven, and the ERC-20 has no privileged minter"). +6. User-facing documentation must state the trustless verification model and the + liveness-only role of any off-chain participant, including whoever submits a + release on a user's behalf. +7. The verifier (the LEZ vault program and the Ethereum contract's proof + verification logic) must be deployed as an immutable program with an explicit + migration path (deploy a new version, drain and redirect to it) in preference + to an upgradeable contract governed by a mutable key, for the reasons set out + in RFP-021, Bridge Security #7 and + [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md). + Proposals must document the chosen migration mechanism and how in-flight + locks and burns are honoured across a migration. +8. The freeze authority stops new activity but does not by itself recover funds + already at risk or resolve locks and burns left in-flight once a + vulnerability in the verification logic is found. Proposals must specify a + failsafe strategy, constrained as in RFP-021, Bridge Security #8: any + recovery must still be claimed by the locker or burner proving their own + entitlement, not by an admin authority identifying who owns what; it must not + be able to mint, redirect, or release to any destination other than the one + the proof specifies; and it must not act on funds beyond what a specific, + proven vulnerability put at risk. If no mechanism satisfying these + constraints is achievable, the proposal must document why and what happens to + affected funds in its absence. + +#### + Privacy Preservation + +1. **Inbound unlinkability must hold under test.** No signal other than amount + and timing may narrow down which LEZ release an Ethereum burn funded, beyond + uniform probability over the remaining candidates. Provide an automated test + that constructs a population of burns and releases and asserts that no + correlation derivable from public state, other than amount and timing, + identifies the true pairing better than chance across the anonymity set those + signals leave unresolved. +2. **Outbound unlinkability must hold under test.** No signal other than amount + and timing may narrow down which Ethereum mint a LEZ lock triggered, beyond + uniform probability over the remaining candidates. The equivalent test for + lock-to-mint pairings. +3. No transaction argument, event, log, or account-state change on either chain + may reveal a lock's Ethereum destination or a burn's LEZ destination. Provide + a test asserting this over full event and state diffs for a complete round + trip. +4. Information that would connect the two legs must never leave the user's + control. Document every component that handles user data, and provide a test + asserting such information is absent from all submitted transaction data. +5. Failure and error paths must not reveal which lock or burn was involved: a + rejected claim, a repeat claim, and a cap rejection must be indistinguishable + in that respect. +6. The client must not make any network request that reveals which lock or burn + it is acting on. Document every network call made during a privacy-sensitive + operation and justify each. +7. **The release payer must not become a correlation signal.** Whoever pays for + a release, whether a relayer, a sponsor, or the protocol itself, must not + thereby link the Ethereum burn to the LEZ account receiving the gas. Document + precisely what that party learns, ensure the user can switch between such + parties per operation, and provide a test asserting that the payer's identity + and payment do not narrow the anonymity set. This is the requirement most at + risk from the gas circularity and must be treated as a primary design + constraint, not a late mitigation. +8. The default configuration must be the private one. No user action may be + required to obtain the privacy guarantees, and any override that weakens them + must require explicit confirmation. + +### Soft Requirements + +1. **Hidden amounts.** Remove the amount-visibility constraint entirely by + concealing transferred values on the LEZ side, rather than relying on a fixed + set of permitted amounts. Whatever is delivered under the hard requirements + should be designed so this can be adopted later without redeploying the + Ethereum contract or resetting accumulated anonymity; document the intended + migration path even if it is not implemented. + +2. **Batching.** Amortise verification cost across multiple operations in a + single transaction, analogous to the batching soft requirement in + [RFP-020](./RFP-020-redstone-oracle-adaptor.md). + +3. **Shared components with RFP-021.** Where the two bridges genuinely share + logic (fixed-denomination handling, position recovery, relayer submission, + the privacy test harness), factor it so both can consume one implementation + rather than maintaining two divergent copies. Document what is shared and + what is necessarily distinct. + +4. **Optional viewing keys** allowing a user to *voluntarily* disclose their own + bridge activity to a chosen third party, without weakening privacy for anyone + else and without any protocol-level disclosure capability. + +5. **Additional EVM chains**, each served by its own deployment per + Functionality #14 (one program per chain ID, not one program juggling several + chains internally). + +6. **Generalisation beyond the gas token.** If the design generalises at no + material cost to other LEZ-native assets, so that a LEZ-native token other + than the gas token can be represented on Ethereum by the same mechanism, + deliver or document that generalisation. This is explicitly not required: the + gas token is the motivating case and a design specialised to it is + acceptable. + +7. **Pluggable proof components**, so that future zkVM improvements, proof + compression, or hardware acceleration can be adopted without restructuring + the vault or the contract. + +### Out of Scope + +The following are explicitly excluded from this RFP: + +- **Wrapping external ERC-20s and ETH into LEZ.** That is the primary flow, + owned by [RFP-021](./RFP-021-wrapped-erc20.md). This RFP inverts the + direction, it does not duplicate the primary flow. +- **The Ethereum state attestation primitive.** Verifying Ethereum consensus, + finality, and state inclusion is owned by + [RFP-022](./RFP-022-ethereum-state-attestation.md). This RFP consumes that + primitive, it does not define or rebuild it. +- **Seeding, replenishment, or market-making for the ERC-20.** Supply is + demand-driven by construction (see Design Rationale); there is no float to + stock and no incentive mechanism to design. +- **Fiat on-ramps, faucets, and centralised distribution** of the gas token. + This RFP delivers a trustless path for a user who already holds assets on + Ethereum; it does not address a user who holds nothing anywhere. +- **Network-level anonymity.** The guarantees here are properties of on-chain + state. IP-level correlation is out of scope as an implementation concern, but + must be disclosed as residual leakage under Supportability #9. +- **Protocol-level compliance, disclosure, or selective-deanonymisation + mechanisms.** Voluntary user-held viewing keys are Soft Requirement #4; any + capability allowing a third party to deanonymise a user without their consent + is contrary to the design and out of scope. +- **Circuit optimisation or custom zkVM accelerators for the LEZ side.** LEZ + runs on RISC0, so proposals should leverage mature existing implementations + rather than implementing novel circuits. + +## ⚠ Platform Dependencies + +### Hard dependencies + +#### Wrapped ERC-20 and Ether bridge (RFP-021) + +This RFP is the reverse-direction counterpart of +[RFP-021](./RFP-021-wrapped-erc20.md) and inherits its vault and mint patterns, +its trust model, its privacy construction, and its approach to caps, freeze +authority, finality and position recovery. RFP-021 establishes those patterns +and carries the reasoning behind them; this RFP applies them with the chains +swapped and does not restate them. Delivering this RFP against a materially +different set of patterns would fragment the two bridges for no benefit, so +RFP-021 is treated as a hard dependency rather than a reference. + +#### Ethereum state attestation (RFP-022) + +The inbound leg releases gas token only against an ERC-20 burn proven to have +been finalised on Ethereum, with no signer or federation trusted to attest to it +(Functionality #4). That verification is delivered as a shared primitive by +[RFP-022](./RFP-022-ethereum-state-attestation.md). This RFP consumes it and +does not rebuild it. The outbound leg, verifying a LEZ lock natively on +Ethereum, is specific to this bridge and remains in scope here. + +#### Admin authority (RFP-001) + +The Functionality requirements specify that an admin authority configures caps, +finality depth, and fee parameters. These admin-gated functions require the +standardised admin authority library from +[RFP-001](./RFP-001-admin-authority-lib.md). + +#### Freeze authority (RFP-002) + +The Bridge Security requirements specify a freeze authority able to pause +minting and/or release as a circuit breaker independent of the caps. This +requires the standardised freeze authority library from +[RFP-002](./RFP-002-freeze-authority-lib.md). + +#### Token authorities (LP-0013) + +The LEZ vault program escrows and releases native gas token under program +control. This requires the token authority primitives in +[LP-0013](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md), +which is **closed** (delivered). + +#### Logos Ethereum core module + +The Ethereum side must use the Logos Ethereum core module, including its +verified proxy features. + +#### Wallet SDK + +The UI must use the wallet SDK from the Lambda Prize wallet-SDK work. + +#### RISC0 zkVM + +The bridge verifies proofs in-program on LEZ. Because LEZ itself runs on RISC0, +this is a LEZ-runtime dependency rather than a choice the proposal makes; +proposals must leverage mature RISC0 implementations (e.g. +[Zisk](https://github.com/risc0/zisk)) rather than building custom circuits. + +#### Event emission (LP-0012) + +Structured on-chain events allow clients and off-chain components to react +without polling every account. +[LP-0012](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) +is **closed** (delivered). + +## 👤 Recommended Team Profile + +Team experienced with: + +- Zero-knowledge proof systems and RISC0 zkVM (guest program development, proof + generation and verification, public/private input handling) +- Privacy-preserving protocol design, including anonymity-set analysis and the + ability to reason rigorously about what public state does and does not reveal +- Solidity smart-contract development, including experience preparing a contract + for third-party security audit, and particular care around mint authorisation + paths +- Cryptographic primitives (Merkle proofs, consensus verification, state root + inclusion proofs) +- LEZ program development, private-state programs, and on-chain proof + verification +- Fee abstraction, relayer design, or account-abstraction style sponsored + transactions, given the gas circularity this RFP has to solve +- Smart-contract security auditing (proof validation, replay attacks, reorg + handling, cap bypass, unauthorised mint paths, privacy-leak analysis) +- Cross-chain system design and integration testing + +## ⏱ Timeline Expectations + +Estimated software delivery duration: **10–14 weeks**. The construction mirrors +[RFP-021](./RFP-021-wrapped-erc20.md) and consumes +[RFP-022](./RFP-022-ethereum-state-attestation.md) for the Ethereum-reading +half, so the patterns and much of the tooling are established rather than +invented here. The new work is the LEZ-side vault, the Ethereum-side mintable +ERC-20 with its authorisation path, and the gasless release mechanism, which is +the largest unknown. This excludes the third-party audit lead time required +before mainnet deployment (Supportability #8), which is typically procured and +scheduled separately. + +## 🌍 Open Source Requirement + +All code must be released under the **MIT+Apache2.0 dual License**. + +## Resources + +- [RFP-001 — Admin Authority Library](./RFP-001-admin-authority-lib.md) +- [RFP-002 — Freeze Authority Library](./RFP-002-freeze-authority-lib.md) +- [RFP-004 — Privacy-Preserving DEX](./RFP-004-privacy-preserving-dex.md) + (states the atomic-deshield gas pattern that presupposes an already-funded + user) +- [RFP-008 — Lending & Borrowing Protocol](./RFP-008-lending-borrowing-protocol.md) + (same atomic-deshield assumption) +- [RFP-020 — RedStone Off-Chain Oracle Adaptor for LEZ](./RFP-020-redstone-oracle-adaptor.md) + (reference for in-program proof verification cost measurement) +- [RFP-021 — Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ](./RFP-021-wrapped-erc20.md) + (the primary flow this RFP inverts) +- [RFP-022 — Trustless Ethereum State Attestation for LEZ](./RFP-022-ethereum-state-attestation.md) + (delivers the verification of finalised Ethereum state the release path + consumes) +- [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md) + (bridge failure taxonomy, including the Meter Passport native-gas-token mint) +- [LP-0012: Event/Log mechanism for LEZ](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) +- [LP-0013: Token program improvements: authorities](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md) +- [RISC0 — Zero-Knowledge VM](https://github.com/risc0/risc0) +- [Zisk — RISC0 Proof Generation](https://github.com/risc0/zisk) + +## ✏️ How to Apply + +👉 Submit a proposal using the Issue form: + +**[Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml)** + +We typically respond within **14 days**. For clarification questions, please use +**Discussions**. From 7dbc146e9bd7606c2cf0091bb29529870537b35e Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Mon, 17 Aug 2026 14:16:14 +1000 Subject: [PATCH 56/69] RFP-023: specify the off-chain paymaster that breaks the gas circularity The release path previously said "must work for a zero-balance recipient" and left the mechanism open. Specify it: an off-chain paymaster is the third component of a deployment, alongside the LEZ vault and the EVM mint/burn contract with its dedicated ERC-20. Eligibility is a property of the proof, never of the requester. The paymaster sponsors a request iff it carries a valid attestation of a burn of its own deployment's ERC-20, above a configured minimum, not already sponsored. The nullifier that exists for double-spend protection doubles as the anti-abuse budget, so abusing the paymaster costs what acquiring and burning real ERC-20 costs. No account, allowlist, or registration. Reachable over Logos Delivery and over Tor, either alone sufficient. Tor is required rather than a nicety: Delivery's RLN spam protection may itself need LEZ gas, which the user by definition lacks, so a Delivery-only deployment could reintroduce the circularity this component exists to break. The paymaster must not observe requester IP addresses, by construction rather than by logging policy. This is the point where the user has no choice but to talk to somebody, so it is where the unlinkability of the whole design is most easily lost. Also require a defence against griefing. lez-proof-vault documents that fee reservation precedes execution and failed transactions are still charged, so a paymaster committing to pay before verifying can be drained by well-formed garbage. Mechanism is the proposal's choice; the cost bound must be measured. Narrows the network-anonymity out-of-scope bullet, which contradicted the new Tor and IP requirements. Co-Authored-By: Claude Opus 5 --- RFPs/RFP-023-gas-token-bridge.md | 414 ++++++++++++++++++++++--------- 1 file changed, 297 insertions(+), 117 deletions(-) diff --git a/RFPs/RFP-023-gas-token-bridge.md b/RFPs/RFP-023-gas-token-bridge.md index 16bb5c42..d5172c0b 100644 --- a/RFPs/RFP-023-gas-token-bridge.md +++ b/RFPs/RFP-023-gas-token-bridge.md @@ -75,7 +75,13 @@ representation, with a correspondingly different audit target. One problem is genuinely new and has no analogue in RFP-021: releasing native gas token to a recipient who, by construction, has no gas with which to pay for -the release. +the release. This RFP resolves it with an **off-chain paymaster service**, the +third component of a deployment alongside the vault and the Ethereum contract. A +user who has burned the ERC-20 drafts the release transaction locally and +contacts the paymaster over Logos Delivery or Tor; the paymaster checks the +attestation, submits the transaction, and pays the gas. It sponsors only burns +of its own deployment's ERC-20, never learns the requester's network address, +and can decline without blocking anyone. Teams will need experience with zero-knowledge proof systems, privacy-preserving protocol design, Solidity smart-contract development, and LEZ program @@ -181,23 +187,99 @@ the recipient of that release is, in the motivating case, someone who holds no gas token at all. If claiming the release requires the claimant to already hold gas, the bridge does not solve the problem it exists to solve. -This RFP requires the release path to work for a recipient with a zero balance -(Functionality #4) but does not mandate how. Several shapes are viable, and -which is best depends on LEZ capabilities at delivery time: a permissionless -relayer paid out of the released amount, with the destination bound into the -proof so the relayer can neither redirect funds nor overcharge, which is the -mechanism RFP-021 already relies on for its fee-payer mitigation; a -protocol-level fee abstraction if LEZ offers one; or sequencer-level sponsorship -for this specific program. - -Whatever the mechanism, it is bound by RFP-021's trust model: no specific -relayer or off-chain party may be a required counterparty, any such role must be -permissionless so that a single participant declining to act never blocks the -user, and no participant may be able to steal, redirect, forge, censor -selectively, or deanonymise. It is also bound by the privacy requirement below, -which is the harder constraint: whoever pays for the release must not become a -correlation signal that links the Ethereum burn to the LEZ account receiving the -gas. +The mechanism this RFP specifies is an **off-chain paymaster service**, deployed +alongside the vault and the Ethereum contract as the third component of a +deployment. A user who has burned the ERC-20 on Ethereum drafts the LEZ release +transaction locally, contacts the paymaster over an anonymising transport, and +the paymaster submits it and pays the gas. The complete deployer journey is +therefore: deploy the LEZ vault program, deploy the EVM mint and burn contract +with its dedicated ERC-20, and run the paymaster. + +The eligibility rule is what keeps this from being an open faucet, and it is +expressed entirely in terms of the proof rather than the requester. The +paymaster sponsors a transaction if and only if that transaction carries a valid +attestation of a burn of **its own deployment's** ERC-20, at or above a +configured minimum amount, whose statement identifier has not already been +sponsored. Nothing about the requester enters the decision: no account, no +allowlist, no registration, no payment relationship. Someone who has not burned +the ERC-20 cannot obtain sponsorship, and someone who has burned it once cannot +obtain it twice, because the nullifier that already exists for double-spend +protection (Functionality #14) doubles as the anti-abuse budget. The cost of +abusing the paymaster is the cost of acquiring and burning real ERC-20, which is +the same barrier that protects the vault itself. + +The paymaster is a liveness convenience, never a trust dependency. It cannot +redirect the release, because the destination is bound into the proof (Bridge +Security #2); it cannot forge or censor selectively without simply declining, +which any other paymaster instance can cover; and it holds nothing of the +user's. A deployment may run several, a user may try them in any order, and a +user who already holds gas can always submit the transaction themselves and skip +the paymaster entirely. Nothing in the protocol privileges a particular +paymaster or requires one to exist. + +#### Transport, and why it needs care + +The paymaster is contacted over **Logos Delivery**, the ecosystem-native +transport, with **Tor as a required alternative**. The alternative is not +redundancy for its own sake: Delivery's spam protection may itself require LEZ +gas for RLN, which the user by definition does not have, so a deployment that +offered only Delivery could reintroduce the very circularity this component +exists to break. Proposals must establish whether that dependency applies at +delivery time and document the finding either way; the Tor path must work +regardless, so the user always has a route that assumes nothing on LEZ. + +Transport is where the privacy of this whole construction is most easily lost. +The paymaster necessarily learns the release transaction it is asked to submit, +which names the destination account. If it also learns the requester's IP, it +can link that account to a network identity, and the unlinkability the rest of +the design works to preserve is gone at the last step, in the one place where +the user has no choice but to talk to somebody. **The paymaster must therefore +never observe or record requester IP addresses.** Both transports are chosen for +this reason (Delivery and Tor each conceal the origin), and the requirement is +not satisfied by a promise not to log: the service must be built so that the +address is not available to it in the first place, and any deployment +configuration that would expose it, such as a plain HTTP fallback or a reverse +proxy passing an originating-address header, must be absent rather than merely +discouraged. + +What the paymaster does learn is the destination account and the amount, at the +moment of submission. That is unavoidable for any party that submits on a user's +behalf, and it is why the operator's knowledge is an explicit documentation +deliverable (Supportability #9) rather than something to gloss over. It does not +link back to the Ethereum burn unless the transport leaks the requester, which +is what the IP requirement forecloses. + +#### Griefing the paymaster + +Eligibility is checked against the attestation, but *checking* it costs the +paymaster something, and on LEZ that cost may land before the check completes. +Fee reservation precedes execution and failed transactions are still charged, so +a paymaster that commits to paying before the proof is verified can be drained +by an attacker submitting well-formed garbage: each submission costs the +attacker nothing and costs the paymaster a reserved fee. This is not a +hypothetical concern about the design; it is the concrete blocker identified in +[`fryorcraken/lez-proof-vault`](https://github.com/fryorcraken/lez-proof-vault), +whose README works through why naive program-sponsored gas is unsafe under a fee +market and suggests deposit-and-reimburse as the alternative shape. + +Proposals must therefore specify how the paymaster bounds this cost, and the +choice is theirs: verifying the attestation off-chain before submitting anything +on-chain, so the paymaster spends nothing on an invalid request; a cheap +reservation-time check that rejects the bulk of garbage before the expensive +path; a deposit-and-reimburse construction where the submitter fronts the fee +and is repaid out of the release; or per-transport rate limiting that does not +require identifying the requester. Whatever is chosen must not reintroduce a +requester identity, since that would defeat the transport privacy above, and +must be measured rather than asserted (Performance #7). + +That repository is the closest prior art for the LEZ-side vault and its +proof-submission shape, and is useful reading for the ownership-versus- +authorization framing of a program-owned vault and for the claimant, submitter +and payer role split it sets out. It is prior art and not a specification: it +implements no paymaster, no transport, and no burn or mint flow, its proof is a +SHA-256 preimage standing in for a real proof system, and it documents its own +gaps (no recipient binding, no authority binding on initialisation). Proposals +should not treat it as a pattern to conform to. ### Privacy mirrors RFP-021 exactly @@ -259,41 +341,83 @@ Use FURPS framework. Each numbered item should be a testable statement. [RFP-022](./RFP-022-ethereum-state-attestation.md) rather than implementing its own Ethereum consensus and inclusion verification. **Claiming that release must not require the recipient to already hold native gas token**, - and no specific relayer or other off-chain party may be a required + and no specific paymaster or other off-chain party may be a required counterparty (see Design Rationale, "The gas circularity"). Test the release path end to end with a recipient account holding a zero balance. -05. A burn on Ethereum must not publish, store, or otherwise reveal its LEZ +05. **Paymaster service.** Provide an off-chain paymaster that accepts a drafted + LEZ release transaction, submits it, and pays the gas, so that a user with a + zero balance can complete a release. It must be implemented as a **Logos + module accompanied by a Logos Core headless CLI/daemon**, runnable + standalone by the deployer of a vault and contract pair. +06. The paymaster sponsors a request if and only if the transaction carries a + valid attestation of a burn of its own deployment's ERC-20, at or above a + configured minimum amount, whose statement identifier it has not already + sponsored. Eligibility must depend on no property of the requester: no + account, allowlist, registration, or payment relationship. Test that a + request carrying no burn, a burn of a different token or deployment, a burn + below the minimum, or an already-sponsored burn is refused, and that a + request carrying a valid unsponsored burn is accepted regardless of who + sends it. +07. The paymaster is reachable over **Logos Delivery** and over **Tor**, and a + user must be able to complete a release using either transport alone. + Proposals must establish whether Logos Delivery's spam protection requires + LEZ gas for RLN at delivery time and document the finding; the Tor path must + function regardless, so that a user holding nothing on LEZ always has a + working route. +08. **The paymaster must not observe or record requester IP addresses.** This + must hold by construction rather than by logging policy: the service must + have no configuration, deployment shape, or transport fallback through which + an originating address becomes available to it. Provide a test asserting + that no requester address is present in any log, metric, persisted record, + or in-memory request context, and document the deployment constraints that + preserve this (see Privacy Preservation #7). +09. Sponsorship is refused without revealing why in a way that identifies the + burn: refusal responses for an ineligible request, an already-sponsored + burn, and a paymaster out of funds must be indistinguishable in that + respect. +10. Nothing in the protocol may privilege a particular paymaster. A deployment + must support running several, a user must be able to select or switch + between them per operation, and a user who holds gas must be able to submit + the release themselves with no paymaster involved. Test the release path + with no paymaster running. +11. The paymaster's exposure to invalid or repeated requests must be bounded, so + that an attacker submitting well-formed but ineligible requests cannot drain + it (see Design Rationale, "Griefing the paymaster"). Proposals must state + the chosen mechanism, which must not require identifying the requester. + Provide a test that floods the paymaster with ineligible requests and + asserts a bounded cost per request and continued service to a valid one. +12. A burn on Ethereum must not publish, store, or otherwise reveal its LEZ destination. -06. Releasing must support both a private LEZ account and a public LEZ account +13. Releasing must support both a private LEZ account and a public LEZ account as the destination, at the burner's choice. -07. Uniqueness is enforced in both directions: no lock can be minted against +14. Uniqueness is enforced in both directions: no lock can be minted against twice and no burn released against twice, deterministically and under adversarial retry. On the LEZ side this is keyed on the statement identifier the RFP-022 attestation carries. -08. The amounts visible on Ethereum must not identify which lock or release they +15. The amounts visible on Ethereum must not identify which lock or release they correspond to. Proposals must state the mechanism chosen (fixed denominations are the expected baseline) and its effect on anonymity-set size. -09. A user must be able to recover every one of their own unclaimed locks and +16. A user must be able to recover every one of their own unclaimed locks and unreleased burns from credentials they already hold, with no dependence on any server-side index and no separately-backed-up secret generated during the flow, on the same terms as RFP-021, "Loss of access." -10. An admin authority (per [RFP-001](./RFP-001-admin-authority-lib.md), +17. An admin authority (per [RFP-001](./RFP-001-admin-authority-lib.md), integrated via the [SPEL framework](https://github.com/logos-co/spel) where applicable to the LEZ side) can configure the caps, the finality depth, and the fee parameters per deployment. -11. Global caps, configurable by the admin authority, bound the maximum value +18. Global caps, configurable by the admin authority, bound the maximum value that can be minted or released within a rolling window, as a rate limiter independent of the freeze authority. Cap enforcement must not require identifying individual users. -12. The finality depth required before a lock may be minted against, and before +19. The finality depth required before a lock may be minted against, and before a burn may be released against, is configurable by the admin authority per deployment. A change to the configured depth must not invalidate a claim that was already valid under the previous depth. -13. A freeze authority (per [RFP-002](./RFP-002-freeze-authority-lib.md)) can +20. A freeze authority (per [RFP-002](./RFP-002-freeze-authority-lib.md)) can pause minting and/or release, on the Ethereum contract and the LEZ vault program independently. -14. Each LEZ vault program deployment refers to a specific Ethereum contract +21. Each LEZ vault program deployment refers to a specific Ethereum contract deployment on a specific chain (contract address plus chain ID), and reciprocally each Ethereum contract deployment refers to a specific zone instance (LEZ blockchain ID, zone ID, and program ID), with each pairing @@ -301,81 +425,94 @@ Use FURPS framework. Each numbered item should be a testable statement. pairing is never accepted as valid for another. The same program and contract design must be deployable, unmodified, against any EVM chain, mainnet or testnet. -15. The design must let multiple entities each operate under their own +22. The design must let multiple entities each operate under their own independent configuration (caps, fees, admin authority, finality depth), on the same or different pairs of blockchain programs, with strict separation between them: one entity's configuration must have no privileged access over another's configuration or funds. Document how a client identifies and switches between configurations. -16. A protocol fee may be charged on minting and on release, at a rate +23. A protocol fee may be charged on minting and on release, at a rate configurable by the admin authority per deployment, including zero. The fee value must not distinguish a user's transaction from others, consistent with - Functionality #8. Where the release-path mechanism compensates a relayer out - of the released amount, document how that compensation interacts with the - fixed-denomination requirement. + Functionality #15. Where the release-path mechanism reimburses a paymaster + out of the released amount, document how that reimbursement interacts with + the fixed-denomination requirement. #### Usability -1. Build core functionalities for both users and admin in a Logos core module, - enabling the delivery of different Logos ui modules: locking gas token, - claiming the Ethereum mint, burning the ERC-20, claiming the LEZ release, - recovering a position from user credentials, and reading and administering - the configuration. -2. Provide a Logos mini-app, aka Logos ui module, covering both flows end to - end, position recovery, and a view showing permitted amounts, caps and - current utilisation. Also provide a UI for the admin functionality; whether - this is combined into one UI or delivered as two separate ones is left to the - applicant's choice. -3. The onboarding flow must be usable by someone who holds nothing on the zone. - The mini-app must not require a funded LEZ account to complete a release, and - must not present a step that silently assumes one. -4. Any long-running off-chain component the design requires must be provided as - a **Logos module accompanied by a Logos Core headless CLI/daemon**, runnable - standalone, supporting configurable RPC endpoints for both chains, - configurable finality depth, structured logging, and a clean shutdown path. - Document the operator journey end-to-end: install, configure, run, monitor. -5. Provide an IDL for the LEZ vault program using the - [SPEL framework](https://github.com/logos-co/spel). -6. The mitigations to the three correlation points in Design Rationale, "Privacy - mirrors RFP-021 exactly" (amount, timing, fee payer) must be enabled by - default. The mini-app and CLI must show a clear indicator of what data would - be leaked by the user's current choices, and default to the recommended - parameters rather than requiring the user to select them. -7. The mini-app and CLI must default to inviting the user to release into, and - lock from, a private account: the private path is the pre-selected option, - and choosing the public path requires an explicit action, consistent with - Privacy Preservation #8. -8. Documentation and UI must clearly explain what is public and what is private - at each step on both chains, and must set the expectation described in Design - Rationale, "Supply is demand-driven", that the ERC-20 is available only to - the extent someone has moved gas token outward. -9. Return clear, actionable error messages for all failure modes: invalid - amount, cap exceeded, verification failure, insufficient finality, already - claimed, and program frozen. Error messages must not reveal which lock or - burn a failed attempt referred to. +01. Build core functionalities for both users and admin in a Logos core module, + enabling the delivery of different Logos ui modules: locking gas token, + claiming the Ethereum mint, burning the ERC-20, claiming the LEZ release, + recovering a position from user credentials, and reading and administering + the configuration. +02. Provide a Logos mini-app, aka Logos ui module, covering both flows end to + end, position recovery, and a view showing permitted amounts, caps and + current utilisation. Also provide a UI for the admin functionality; whether + this is combined into one UI or delivered as two separate ones is left to + the applicant's choice. +03. The onboarding flow must be usable by someone who holds nothing on the zone. + The mini-app must not require a funded LEZ account to complete a release, + and must not present a step that silently assumes one. +04. Any long-running off-chain component the design requires, including the + paymaster, must be provided as a **Logos module accompanied by a Logos Core + headless CLI/daemon**, runnable standalone, supporting configurable RPC + endpoints for both chains, configurable finality depth, structured logging, + and a clean shutdown path. Document the operator journey end-to-end: + install, configure, run, monitor. +05. The client must let the user select which paymaster to contact and over + which transport, retry against another on refusal or timeout, and fall back + to self-submission when the user holds gas. A paymaster refusing or being + unreachable must produce a clear, actionable state rather than a stalled + flow. +06. Provide an IDL for the LEZ vault program using the + [SPEL framework](https://github.com/logos-co/spel). +07. The mitigations to the three correlation points in Design Rationale, + "Privacy mirrors RFP-021 exactly" (amount, timing, fee payer) must be + enabled by default. The mini-app and CLI must show a clear indicator of what + data would be leaked by the user's current choices, and default to the + recommended parameters rather than requiring the user to select them. +08. The mini-app and CLI must default to inviting the user to release into, and + lock from, a private account: the private path is the pre-selected option, + and choosing the public path requires an explicit action, consistent with + Privacy Preservation #8. +09. Documentation and UI must clearly explain what is public and what is private + at each step on both chains, and must set the expectation described in + Design Rationale, "Supply is demand-driven", that the ERC-20 is available + only to the extent someone has moved gas token outward. +10. Return clear, actionable error messages for all failure modes: invalid + amount, cap exceeded, verification failure, insufficient finality, already + claimed, and program frozen. Error messages must not reveal which lock or + burn a failed attempt referred to. #### Reliability -1. Minting is atomic: a failed or rejected mint claim leaves the lock claimable - on retry and consumes nothing. -2. Release is atomic: a failed burn does not destroy the ERC-20 without - preserving the holder's entitlement to release, and a failed release leaves - that entitlement intact. -3. No lock can be minted against twice and no burn released against twice, - deterministically and under adversarial retry. -4. A valid claim remains valid indefinitely; later chain activity must never - invalidate a user's outstanding entitlement. -5. Position recovery is complete: a client restored from user credentials alone - must rediscover every claimable lock and unreleased burn, verified by a test - that wipes all local state. -6. Temporary RPC or connectivity failure on either chain leaves any off-chain - component in a recoverable state, able to resume without duplicating work - already done. -7. An interrupted user-side operation does not consume, corrupt, or expose the - user's entitlement. -8. Proposals must integrate mature, audited proof-system implementations rather - than reimplementing zero-knowledge primitives from scratch. -9. CI must be green on the default branch. +01. Minting is atomic: a failed or rejected mint claim leaves the lock claimable + on retry and consumes nothing. +02. Release is atomic: a failed burn does not destroy the ERC-20 without + preserving the holder's entitlement to release, and a failed release leaves + that entitlement intact. +03. No lock can be minted against twice and no burn released against twice, + deterministically and under adversarial retry. +04. A valid claim remains valid indefinitely; later chain activity must never + invalidate a user's outstanding entitlement. +05. Position recovery is complete: a client restored from user credentials alone + must rediscover every claimable lock and unreleased burn, verified by a test + that wipes all local state. +06. Temporary RPC or connectivity failure on either chain leaves any off-chain + component in a recoverable state, able to resume without duplicating work + already done. +07. An interrupted user-side operation does not consume, corrupt, or expose the + user's entitlement. A paymaster that accepts a request and then fails, + crashes, or never submits must leave the user's entitlement intact and + re-submittable, to the same or another paymaster, with no state stranded on + the failed one. +08. No paymaster is required for correctness. With every paymaster offline, a + user holding gas must still be able to complete a release themselves, and a + user without gas must be left in a recoverable state rather than losing the + entitlement. Test with no paymaster reachable over either transport. +09. Proposals must integrate mature, audited proof-system implementations rather + than reimplementing zero-knowledge primitives from scratch. +10. CI must be green on the default branch. #### Performance @@ -393,11 +530,18 @@ Use FURPS framework. Each numbered item should be a testable statement. declares as supported, and state that minimum explicitly. 4. Document end-to-end latency in both directions, each broken down by source-chain finality wait, proof generation, any privacy-motivated delay, - and on-chain verification. + on-chain verification, and the paymaster round trip over each supported + transport, since Delivery and Tor differ materially in latency. 5. Document the compute resources (CPU, RAM, time) required to run any off-chain - component the design requires. + component the design requires, including the paymaster. 6. Document the growth rate and on-chain storage cost of all bridge state that accumulates with usage, with projections at 1M and 10M operations. +7. **Measure the paymaster's cost per request**, separately for an eligible + request and for each class of rejected request, and state the resulting bound + on what an attacker can force the paymaster to spend per unit of their own + cost (see Design Rationale, "Griefing the paymaster"). Document the operating + budget a paymaster needs at a stated request volume, and the behaviour when + its funds are exhausted. #### Supportability @@ -424,7 +568,12 @@ Use FURPS framework. Each numbered item should be a testable statement. 07. Submit a [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) for the deployer journey, covering how an entity stands up its own - independently configured deployment (Functionality #15). + independently configured deployment (Functionality #22) as a complete set: + deploying the LEZ vault program, deploying the EVM mint and burn contract + with its dedicated ERC-20, and running the paymaster. The paymaster section + must cover funding it, configuring the minimum sponsored amount, exposing it + over Logos Delivery and Tor, and the deployment constraints that keep + requester addresses out of reach (Functionality #8). 08. The Ethereum contract undergoes an independent third-party smart-contract security audit before mainnet deployment; the audit report must be published. The audit scope must explicitly include the mint authorisation @@ -434,9 +583,13 @@ Use FURPS framework. Each numbered item should be a testable statement. and #2 and the anonymity set each is measured against; exactly what is visible on-chain at every step on both chains; what an adversary observing all public state can and cannot infer; what every off-chain participant can - observe, with specific attention to whoever pays for a release; residual - leakage from timing, amount selection, fee payment, network metadata and - usage patterns; and the conditions under which the guarantees degrade. + observe, with a specific section on the paymaster stating exactly what it + learns (the destination account and amount at submission time), what it + cannot learn (the requester's network address, and the link back to the + Ethereum burn), and what a malicious or compromised paymaster could and + could not do; residual leakage from timing, amount selection, fee payment, + network metadata and usage patterns, including what each supported transport + exposes; and the conditions under which the guarantees degrade. 10. Document the anonymity-set growth model: expected set size over time at projected volumes, the minimum below which the guarantees are considered not to hold, and guidance for users bridging before the pool has matured. @@ -458,11 +611,11 @@ Use FURPS framework. Each numbered item should be a testable statement. the seed or credentials that produced the commitment. Test that an adversary who observes everything public about a lock or burn, but does not hold the originating seed, cannot construct a valid claim for a different destination. - This applies with particular force to the release path, where a relayer may - be submitting on behalf of a user who cannot submit for themselves. -3. Caps (Functionality #11) bound the maximum value at risk in any rolling + This applies with particular force to the release path, where a paymaster is + submitting on behalf of a user who cannot submit for themselves. +3. Caps (Functionality #18) bound the maximum value at risk in any rolling window; proposals must document recommended defaults and the reasoning. -4. The freeze authority (Functionality #13) must be exercisable independently on +4. The freeze authority (Functionality #20) must be exercisable independently on each half, so either can be paused without the other being operational or reachable. 5. **Soundness of supply.** Total supply of the ERC-20 on Ethereum must never @@ -525,14 +678,18 @@ Use FURPS framework. Each numbered item should be a testable statement. 6. The client must not make any network request that reveals which lock or burn it is acting on. Document every network call made during a privacy-sensitive operation and justify each. -7. **The release payer must not become a correlation signal.** Whoever pays for - a release, whether a relayer, a sponsor, or the protocol itself, must not - thereby link the Ethereum burn to the LEZ account receiving the gas. Document - precisely what that party learns, ensure the user can switch between such - parties per operation, and provide a test asserting that the payer's identity - and payment do not narrow the anonymity set. This is the requirement most at - risk from the gas circularity and must be treated as a primary design - constraint, not a late mitigation. +7. **The paymaster must not become a correlation signal.** Whoever pays for a + release must not thereby link the Ethereum burn to the LEZ account receiving + the gas. Concretely: the paymaster must not observe or record requester IP + addresses (Functionality #8), must not require or accept any requester + identifier, and its own on-chain footprint as fee payer must not distinguish + one sponsored release from another. Document precisely what it learns, ensure + the user can switch between paymasters and transports per operation, and + provide a test asserting that neither the paymaster's identity nor its + payment narrows the anonymity set. This is the requirement most at risk from + the gas circularity, since it is the one point where the user must talk to + somebody, and must be treated as a primary design constraint rather than a + late mitigation. 8. The default configuration must be the private one. No user action may be required to obtain the privacy guarantees, and any override that weakens them must require explicit confirmation. @@ -551,8 +708,8 @@ Use FURPS framework. Each numbered item should be a testable statement. [RFP-020](./RFP-020-redstone-oracle-adaptor.md). 3. **Shared components with RFP-021.** Where the two bridges genuinely share - logic (fixed-denomination handling, position recovery, relayer submission, - the privacy test harness), factor it so both can consume one implementation + logic (fixed-denomination handling, position recovery, submission paths, the + privacy test harness), factor it so both can consume one implementation rather than maintaining two divergent copies. Document what is shared and what is necessarily distinct. @@ -561,7 +718,7 @@ Use FURPS framework. Each numbered item should be a testable statement. else and without any protocol-level disclosure capability. 5. **Additional EVM chains**, each served by its own deployment per - Functionality #14 (one program per chain ID, not one program juggling several + Functionality #21 (one program per chain ID, not one program juggling several chains internally). 6. **Generalisation beyond the gas token.** If the design generalises at no @@ -592,9 +749,13 @@ The following are explicitly excluded from this RFP: - **Fiat on-ramps, faucets, and centralised distribution** of the gas token. This RFP delivers a trustless path for a user who already holds assets on Ethereum; it does not address a user who holds nothing anywhere. -- **Network-level anonymity.** The guarantees here are properties of on-chain - state. IP-level correlation is out of scope as an implementation concern, but - must be disclosed as residual leakage under Supportability #9. +- **Building new anonymising network infrastructure.** The paymaster must be + reachable over Logos Delivery and Tor and must not observe requester addresses + (Functionality #7, #8), but this RFP integrates existing transports rather + than designing a mixnet or hardening the transports themselves. Residual + network-level leakage outside the paymaster path, such as which Ethereum RPC + or LEZ sequencer a user's client contacts, stays an implementation concern and + must be disclosed under Supportability #9 rather than solved here. - **Protocol-level compliance, disclosure, or selective-deanonymisation mechanisms.** Voluntary user-held viewing keys are Soft Requirement #4; any capability allowing a third party to deanonymise a user without their consent @@ -648,6 +809,17 @@ control. This requires the token authority primitives in [LP-0013](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md), which is **closed** (delivered). +#### Logos Delivery + +The paymaster is reachable over Logos Delivery as its ecosystem-native transport +(Functionality #7). Tor is a required alternative and the release path must work +over Tor alone, so Delivery being unavailable never blocks a user. Proposals +must establish whether Delivery's RLN spam protection requires LEZ gas at +delivery time, since a user in the motivating case has none, and document the +finding either way. Following [RFP-003](./RFP-003-atomic-swaps.md), the +application must handle Delivery being temporarily unreachable gracefully and +must not depend on it to complete an operation already in progress. + #### Logos Ethereum core module The Ethereum side must use the Logos Ethereum core module, including its @@ -686,8 +858,11 @@ Team experienced with: inclusion proofs) - LEZ program development, private-state programs, and on-chain proof verification -- Fee abstraction, relayer design, or account-abstraction style sponsored - transactions, given the gas circularity this RFP has to solve +- Fee abstraction, paymaster or relayer design, or account-abstraction style + sponsored transactions, given the gas circularity this RFP has to solve +- Anonymising transports (Tor hidden services, mixnets, Logos Delivery) and + building services that are structurally unable to observe client network + addresses - Smart-contract security auditing (proof validation, replay attacks, reorg handling, cap bypass, unauthorised mint paths, privacy-leak analysis) - Cross-chain system design and integration testing @@ -724,8 +899,13 @@ All code must be released under the **MIT+Apache2.0 dual License**. - [RFP-022 — Trustless Ethereum State Attestation for LEZ](./RFP-022-ethereum-state-attestation.md) (delivers the verification of finalised Ethereum state the release path consumes) +- [RFP-003 — Atomic Swaps](./RFP-003-atomic-swaps.md) (precedent for using Logos + Delivery for coordination without depending on it for completion) - [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md) (bridge failure taxonomy, including the Meter Passport native-gas-token mint) +- [`fryorcraken/lez-proof-vault`](https://github.com/fryorcraken/lez-proof-vault) + (prior art for a program-owned LEZ vault releasing on proof; documents the + reserve-before-verify griefing problem for sponsored gas) - [LP-0012: Event/Log mechanism for LEZ](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) - [LP-0013: Token program improvements: authorities](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md) - [RISC0 — Zero-Knowledge VM](https://github.com/risc0/risc0) From 102f992e135fdb052b4889e993903e229cb0cd1b Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Mon, 17 Aug 2026 15:42:34 +1000 Subject: [PATCH 57/69] RFPs 021-023: drop per-item test instructions, keep the conditions Supportability already requires every hard requirement in Functionality, Usability, Reliability, Performance and Privacy Preservation to have at least one corresponding test. Restating that inside individual FURPS items as "Provide a test asserting..." was redundant. Where a clause named specific adversarial cases (tampered headers, mint-twice from one deposit, minting via an admin path, flooding the paymaster with ineligible requests), those cases are kept but phrased as conditions the requirement demands rather than as test instructions, so nothing is lost from the spec and the coverage obligation flows from Supportability as intended. Co-Authored-By: Claude Opus 5 --- RFPs/RFP-021-wrapped-erc20.md | 26 ++++--- RFPs/RFP-022-ethereum-state-attestation.md | 3 +- RFPs/RFP-023-gas-token-bridge.md | 82 ++++++++++------------ 3 files changed, 52 insertions(+), 59 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 53be0f2c..1b35732a 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -593,9 +593,9 @@ Use FURPS framework. Each numbered item should be a testable statement. #### + Bridge Security 1. Proof verification must be independently verifiable. Both the LEZ program and - the Ethereum vault must reject invalid proofs, tested with incorrect public - inputs, proofs for incorrect chain state, tampered headers, and replayed - proofs. + the Ethereum vault must reject invalid proofs, including those with incorrect + public inputs, proofs for incorrect chain state, tampered headers, and + replayed proofs. 2. A malicious party submitting on a user's behalf must not be able to redirect funds, inflate their fee, or replay the user's submission to a different destination: a deposit and a burn must each secretly commit to the @@ -603,10 +603,9 @@ Use FURPS framework. Each numbered item should be a testable statement. whoever holds the seed or credentials that produced the commitment, and no information that leaks beyond that seed, whether from the deposit or burn transaction itself, public or observable state, or any party the flow depends - on, can be used to steal it (see Functionality #2, #5). Test that an - adversary who observes everything public about a deposit or burn, but does - not hold the originating seed, cannot construct a valid claim for a different - destination. + on, can be used to steal it (see Functionality #2, #5). An adversary who + observes everything public about a deposit or burn, but does not hold the + originating seed, cannot construct a valid claim for a different destination. 3. Caps (Functionality #11) bound the maximum value at risk in any rolling window; proposals must document recommended defaults and the reasoning behind them. @@ -614,8 +613,8 @@ Use FURPS framework. Each numbered item should be a testable statement. each half, so either can be paused without the other being operational or reachable. 5. Soundness of supply: total wrapped supply on LEZ must never exceed the - vault's holdings. Provide tests attempting to mint without a valid deposit, - mint twice from one deposit, and release without a valid burn. + vault's holdings. Minting without a valid deposit, minting twice from one + deposit, and releasing without a valid burn must all fail. 6. User-facing documentation must state the trustless verification model and the liveness-only role of any off-chain participant (see Design Rationale, "Trust model"). @@ -660,12 +659,11 @@ Use FURPS framework. Each numbered item should be a testable statement. triggered, beyond uniform probability over the remaining candidates. The equivalent test for burn-to-release pairings. 3. No transaction argument, event, log, or account-state change on either chain - may reveal a deposit's LEZ destination or a burn's Ethereum destination. - Provide a test asserting this over full event and state diffs for a complete - round trip. + may reveal a deposit's LEZ destination or a burn's Ethereum destination. This + must hold over full event and state diffs for a complete round trip. 4. Information that would connect the two legs must never leave the user's - control. Document every component that handles user data, and provide a test - asserting such information is absent from all submitted transaction data. + control. Document every component that handles user data; such information + must be absent from all submitted transaction data. 5. Failure and error paths must not reveal which deposit or burn was involved: a rejected claim, a repeat claim, and a cap rejection must be indistinguishable in that respect. diff --git a/RFPs/RFP-022-ethereum-state-attestation.md b/RFPs/RFP-022-ethereum-state-attestation.md index f02bfe02..1f65e7df 100644 --- a/RFPs/RFP-022-ethereum-state-attestation.md +++ b/RFPs/RFP-022-ethereum-state-attestation.md @@ -318,8 +318,7 @@ Use FURPS framework. Each numbered item should be a testable statement. signal beyond what is already public on Ethereum. The public inputs of the verified statement must be limited to what the consumer explicitly chooses to expose, and must not reveal the identity of the consuming LEZ account or - the consuming transaction. Provide a test asserting this over full event and - state diffs. + the consuming transaction. This must hold over full event and state diffs. 09. An admin authority (per [RFP-001](./RFP-001-admin-authority-lib.md), integrated via the [SPEL framework](https://github.com/logos-co/spel) where applicable) can configure the weak-subjectivity checkpoint, the supported diff --git a/RFPs/RFP-023-gas-token-bridge.md b/RFPs/RFP-023-gas-token-bridge.md index d5172c0b..5e002e89 100644 --- a/RFPs/RFP-023-gas-token-bridge.md +++ b/RFPs/RFP-023-gas-token-bridge.md @@ -342,8 +342,8 @@ Use FURPS framework. Each numbered item should be a testable statement. its own Ethereum consensus and inclusion verification. **Claiming that release must not require the recipient to already hold native gas token**, and no specific paymaster or other off-chain party may be a required - counterparty (see Design Rationale, "The gas circularity"). Test the release - path end to end with a recipient account holding a zero balance. + counterparty (see Design Rationale, "The gas circularity"). This must hold + end to end for a recipient account holding a zero balance. 05. **Paymaster service.** Provide an off-chain paymaster that accepts a drafted LEZ release transaction, submits it, and pays the gas, so that a user with a zero balance can complete a release. It must be implemented as a **Logos @@ -353,11 +353,10 @@ Use FURPS framework. Each numbered item should be a testable statement. valid attestation of a burn of its own deployment's ERC-20, at or above a configured minimum amount, whose statement identifier it has not already sponsored. Eligibility must depend on no property of the requester: no - account, allowlist, registration, or payment relationship. Test that a - request carrying no burn, a burn of a different token or deployment, a burn - below the minimum, or an already-sponsored burn is refused, and that a - request carrying a valid unsponsored burn is accepted regardless of who - sends it. + account, allowlist, registration, or payment relationship. A request + carrying no burn, a burn of a different token or deployment, a burn below + the minimum, or an already-sponsored burn is refused; a request carrying a + valid unsponsored burn is accepted regardless of who sends it. 07. The paymaster is reachable over **Logos Delivery** and over **Tor**, and a user must be able to complete a release using either transport alone. Proposals must establish whether Logos Delivery's spam protection requires @@ -367,10 +366,10 @@ Use FURPS framework. Each numbered item should be a testable statement. 08. **The paymaster must not observe or record requester IP addresses.** This must hold by construction rather than by logging policy: the service must have no configuration, deployment shape, or transport fallback through which - an originating address becomes available to it. Provide a test asserting - that no requester address is present in any log, metric, persisted record, - or in-memory request context, and document the deployment constraints that - preserve this (see Privacy Preservation #7). + an originating address becomes available to it. No requester address may be + present in any log, metric, persisted record, or in-memory request context. + Document the deployment constraints that preserve this (see Privacy + Preservation #7). 09. Sponsorship is refused without revealing why in a way that identifies the burn: refusal responses for an ineligible request, an already-sponsored burn, and a paymaster out of funds must be indistinguishable in that @@ -378,14 +377,14 @@ Use FURPS framework. Each numbered item should be a testable statement. 10. Nothing in the protocol may privilege a particular paymaster. A deployment must support running several, a user must be able to select or switch between them per operation, and a user who holds gas must be able to submit - the release themselves with no paymaster involved. Test the release path - with no paymaster running. + the release themselves with no paymaster involved, including when no + paymaster is running at all. 11. The paymaster's exposure to invalid or repeated requests must be bounded, so that an attacker submitting well-formed but ineligible requests cannot drain it (see Design Rationale, "Griefing the paymaster"). Proposals must state the chosen mechanism, which must not require identifying the requester. - Provide a test that floods the paymaster with ineligible requests and - asserts a bounded cost per request and continued service to a valid one. + Under a flood of ineligible requests, cost per request stays bounded and a + valid request is still served. 12. A burn on Ethereum must not publish, store, or otherwise reveal its LEZ destination. 13. Releasing must support both a private LEZ account and a public LEZ account @@ -496,8 +495,8 @@ Use FURPS framework. Each numbered item should be a testable statement. 04. A valid claim remains valid indefinitely; later chain activity must never invalidate a user's outstanding entitlement. 05. Position recovery is complete: a client restored from user credentials alone - must rediscover every claimable lock and unreleased burn, verified by a test - that wipes all local state. + must rediscover every claimable lock and unreleased burn, after all local + state is wiped. 06. Temporary RPC or connectivity failure on either chain leaves any off-chain component in a recoverable state, able to resume without duplicating work already done. @@ -601,15 +600,15 @@ Use FURPS framework. Each numbered item should be a testable statement. #### + Bridge Security 1. Proof verification must be independently verifiable. Both the LEZ vault - program and the Ethereum contract must reject invalid proofs, tested with - incorrect public inputs, proofs for incorrect chain state, tampered headers, - and replayed proofs. + program and the Ethereum contract must reject invalid proofs, including those + with incorrect public inputs, proofs for incorrect chain state, tampered + headers, and replayed proofs. 2. A malicious party submitting on a user's behalf must not be able to redirect funds, inflate their fee, or replay the user's submission to a different destination: a lock and a burn must each secretly commit to the destination on the other chain, so that the claim can only be completed by whoever holds - the seed or credentials that produced the commitment. Test that an adversary - who observes everything public about a lock or burn, but does not hold the + the seed or credentials that produced the commitment. An adversary who + observes everything public about a lock or burn, but does not hold the originating seed, cannot construct a valid claim for a different destination. This applies with particular force to the release path, where a paymaster is submitting on behalf of a user who cannot submit for themselves. @@ -622,13 +621,13 @@ Use FURPS framework. Each numbered item should be a testable statement. exceed the native gas token locked in the LEZ vault. The ERC-20 must have no privileged minter and no pre-issued supply: every unit in existence is backed by gas token locked on LEZ, and burning it is the only way to unlock that gas - token. Provide tests attempting to mint without a valid lock, mint twice from - one lock, release without a valid burn, and release twice from one burn. - Testing must explicitly include attempts to mint via any admin, deployer, - owner, or upgrade path, and any path that interacts with the ERC-20 contract - directly rather than through the bridge entry point, since that is the - documented Meter Passport failure mode (see Design Rationale, "Supply is - demand-driven, and the ERC-20 has no privileged minter"). + token. Minting without a valid lock, minting twice from one lock, releasing + without a valid burn, and releasing twice from one burn must all fail, as + must any attempt to mint via an admin, deployer, or owner path, or by + interacting with the ERC-20 contract directly rather than through the bridge + entry point, since that is the documented Meter Passport failure mode (see + Design Rationale, "Supply is demand-driven, and the ERC-20 has no privileged + minter"). 6. User-facing documentation must state the trustless verification model and the liveness-only role of any off-chain participant, including whoever submits a release on a user's behalf. @@ -656,22 +655,20 @@ Use FURPS framework. Each numbered item should be a testable statement. 1. **Inbound unlinkability must hold under test.** No signal other than amount and timing may narrow down which LEZ release an Ethereum burn funded, beyond - uniform probability over the remaining candidates. Provide an automated test - that constructs a population of burns and releases and asserts that no - correlation derivable from public state, other than amount and timing, - identifies the true pairing better than chance across the anonymity set those - signals leave unresolved. + uniform probability over the remaining candidates. Across a population of + burns and releases, no correlation derivable from public state, other than + amount and timing, identifies the true pairing better than chance across the + anonymity set those signals leave unresolved. 2. **Outbound unlinkability must hold under test.** No signal other than amount and timing may narrow down which Ethereum mint a LEZ lock triggered, beyond uniform probability over the remaining candidates. The equivalent test for lock-to-mint pairings. 3. No transaction argument, event, log, or account-state change on either chain may reveal a lock's Ethereum destination or a burn's LEZ destination. Provide - a test asserting this over full event and state diffs for a complete round - trip. + This must hold over full event and state diffs for a complete round trip. 4. Information that would connect the two legs must never leave the user's - control. Document every component that handles user data, and provide a test - asserting such information is absent from all submitted transaction data. + control. Document every component that handles user data; such information + must be absent from all submitted transaction data. 5. Failure and error paths must not reveal which lock or burn was involved: a rejected claim, a repeat claim, and a cap rejection must be indistinguishable in that respect. @@ -685,11 +682,10 @@ Use FURPS framework. Each numbered item should be a testable statement. identifier, and its own on-chain footprint as fee payer must not distinguish one sponsored release from another. Document precisely what it learns, ensure the user can switch between paymasters and transports per operation, and - provide a test asserting that neither the paymaster's identity nor its - payment narrows the anonymity set. This is the requirement most at risk from - the gas circularity, since it is the one point where the user must talk to - somebody, and must be treated as a primary design constraint rather than a - late mitigation. + ensure that neither the paymaster's identity nor its payment narrows the + anonymity set. This is the requirement most at risk from the gas circularity, + since it is the one point where the user must talk to somebody, and must be + treated as a primary design constraint rather than a late mitigation. 8. The default configuration must be the private one. No user action may be required to obtain the privacy guarantees, and any override that weakens them must require explicit confirmation. From dacc46eb4f5a0bc113b66d26056e6aee1bd73f5d Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Mon, 17 Aug 2026 15:46:26 +1000 Subject: [PATCH 58/69] RFPs 021-023: state immutability in LEZ terms, not EVM/Solana terms The requirement said the verifier "must be deployed as an immutable program ... in preference to an upgradeable contract governed by a mutable key". That is EVM proxy language mixed with Solana upgrade-authority language, and neither describes LEZ. LEZ has no upgradeability at all. A ProgramId is the RISC0 image ID computed from the bytecode, the deployed-program registry is append-only, redeploying identical bytecode is rejected, and a deployment transaction carries no authority or deployer identity. Changing one byte yields a different program, not a new version of the same one. So "deploy as immutable rather than upgradeable" was not a choice a proposal could make on the LEZ side, and the stolen-upgrade-key attack cannot arise there. What can arise is indirection. ChainedCall takes a ProgramId as an ordinary runtime field, and a program may hold one in its own account state, so an immutable bridge could still point at swappable verification logic. Whoever controls that pointer can repoint it at a verifier that accepts anything, which is the same fund-stealing capability relocated from the code to the pointer. The requirement now addresses the pointer on LEZ and the upgrade path on Ethereum, since only the Ethereum half has a genuine upgradeability question. RFP-022 additionally notes that its consumers inherit the same discipline, because they reference the module by image ID. Verified against logos-execution-zone: lee/state_machine/src/program/mod.rs (image ID derivation), validated_state_diff/mod.rs (append-only registry, ChainedCall dispatch), program_deployment_transaction/message.rs (bytecode only, unsigned). Co-Authored-By: Claude Opus 5 --- RFPs/RFP-021-wrapped-erc20.md | 77 ++++++++++++++++------ RFPs/RFP-022-ethereum-state-attestation.md | 29 ++++++-- RFPs/RFP-023-gas-token-bridge.md | 19 ++++-- 3 files changed, 91 insertions(+), 34 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 1b35732a..74d6e66a 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -156,16 +156,34 @@ cryptographic design does not remove, because it depends on that logic being correct (see [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md) for the sourced figures, per-hack root causes, and the exact Chainalysis -citation). A verifier deployed as an upgradeable contract carries a related risk -one layer down: no cross-chain bridge hack has traced to a stolen upgrade key, -but legitimate, authorised upgrades have shipped catastrophic verification bugs -(Nomad; a second Ronin incident in 2024), which an immutable program with no -upgrade path forecloses by construction. For that reason this RFP prefers an -immutable program with an explicit migration path over an upgradeable one, and -treats verification logic correctness (audit, formal methods, extensive -adversarial testing) as a security requirement of the same order as eliminating -signer trust. Per-token and global caps and an admin-governed freeze authority -remain as operational safety nets against both failure modes. +citation). Mutable verification logic carries a related risk one layer down: no +cross-chain bridge hack has traced to a stolen upgrade key, but legitimate, +authorised upgrades have shipped catastrophic verification bugs (Nomad; a second +Ronin incident in 2024), which fixed verification logic forecloses by +construction. + +The two chains differ in how that risk arises, and the requirement below is +written accordingly. On Ethereum it is the familiar one: a verifier behind an +upgradeable proxy can have its implementation replaced, whether by a stolen key +or by an authorised upgrade that ships a bug. On LEZ it cannot arise the same +way, because a program's identity is the hash of its code: a `ProgramId` is the +RISC0 image ID computed from the bytecode, the deployed-program registry is +append-only, and a deployment transaction carries no authority or deployer +identity that could later authorise a change. Changing one byte produces a +different program, not a new version of the same one. LEZ program code is +therefore immutable by construction rather than by choice. + +What remains possible on LEZ is indirection. A program may hold another +program's `ProgramId` in its own account state and dispatch to it at runtime, so +an immutable bridge program could still point at swappable verification logic +and a party controlling that pointer could repoint it at a verifier that accepts +anything. That is the same fund-stealing capability as a stolen upgrade key, +relocated from the code to the pointer, which is why the requirement below +addresses the pointer rather than the deployment. This RFP treats verification +logic correctness (audit, formal methods, extensive adversarial testing) as a +security requirement of the same order as eliminating signer trust. Per-token +and global caps and an admin-governed freeze authority remain as operational +safety nets against both failure modes. ## 🏗 Design Rationale @@ -596,6 +614,7 @@ Use FURPS framework. Each numbered item should be a testable statement. the Ethereum vault must reject invalid proofs, including those with incorrect public inputs, proofs for incorrect chain state, tampered headers, and replayed proofs. + 2. A malicious party submitting on a user's behalf must not be able to redirect funds, inflate their fee, or replay the user's submission to a different destination: a deposit and a burn must each secretly commit to the @@ -606,29 +625,47 @@ Use FURPS framework. Each numbered item should be a testable statement. on, can be used to steal it (see Functionality #2, #5). An adversary who observes everything public about a deposit or burn, but does not hold the originating seed, cannot construct a valid claim for a different destination. + 3. Caps (Functionality #11) bound the maximum value at risk in any rolling window; proposals must document recommended defaults and the reasoning behind them. + 4. The freeze authority (Functionality #14) must be exercisable independently on each half, so either can be paused without the other being operational or reachable. + 5. Soundness of supply: total wrapped supply on LEZ must never exceed the vault's holdings. Minting without a valid deposit, minting twice from one deposit, and releasing without a valid burn must all fail. + 6. User-facing documentation must state the trustless verification model and the liveness-only role of any off-chain participant (see Design Rationale, "Trust model"). -7. The verifier (the LEZ bridge program and the Ethereum vault's proof - verification logic) must be deployed as an immutable program with an explicit - migration path (deploy a new version, drain and redirect to it) in preference - to an upgradeable contract governed by a mutable key. An upgradeable verifier - carries two risks this eliminates by construction: a stolen or misused - upgrade key substituting malicious logic, and a legitimate, authorised - upgrade shipping a catastrophic bug, the latter being the documented cause of + +7. **Verification logic must be fixed at deployment on both chains.** No party, + however privileged, may change what the bridge accepts as a valid proof after + deployment. Concretely: + + - **LEZ.** Program code is immutable by construction, so the requirement is + about dispatch: the bridge program must not reach its verification logic + through a `ProgramId` held in mutable account state, or any equivalent + indirection that lets an authority repoint it. The verifying program's + image ID is fixed in the bridge program's own code at deployment. + - **Ethereum.** The vault's proof verification logic must have no upgrade + path: no proxy whose implementation can be substituted, no + admin-replaceable verification key or address, no privileged path to alter + what the verifier accepts. + + The risk being foreclosed is the same on both sides, and is documented in real bridge losses (see Why This Matters and - [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)). - Proposals must document the chosen migration mechanism and how in-flight - deposits and burns are honoured across a migration. + [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)): + an authority that can substitute verification logic, whether by holding an + upgrade key or by controlling a program pointer, can point the bridge at a + verifier that accepts anything and drain it. Change is delivered by migration + instead: deploy a new version and drain and redirect to it. Proposals must + document the migration mechanism and how in-flight deposits and burns are + honoured across a migration. + 8. The freeze authority (Functionality #14) stops new activity but does not by itself recover funds already at risk or resolve deposits and burns left in-flight once a vulnerability in the verification logic is found. Proposals diff --git a/RFPs/RFP-022-ethereum-state-attestation.md b/RFPs/RFP-022-ethereum-state-attestation.md index 1f65e7df..10b7634f 100644 --- a/RFPs/RFP-022-ethereum-state-attestation.md +++ b/RFPs/RFP-022-ethereum-state-attestation.md @@ -462,24 +462,39 @@ Use FURPS framework. Each numbered item should be a testable statement. and inclusion proof over state that was never finalised on the canonical chain, verification must fail. This is the central adversarial test of the RFP and must be exercised explicitly, not implied by other tests. + 2. Verification must reject: a header signed by a committee that was never validly handed off from the configured checkpoint; a sync-committee signature below the required participation threshold; a valid inclusion proof against a header that is not finalised; a valid finalised header with a tampered state or receipts root; a proof replayed against a different chain ID; and a predicate asserted over state the inclusion proof does not cover. -3. The verifier must be deployed as an immutable program with an explicit - migration path (deploy a new version, redirect consumers to it) in preference - to an upgradeable one governed by a mutable key. Legitimate, authorised - upgrades have shipped catastrophic verification bugs in production bridges - (see + +3. **Verification logic must be fixed at deployment.** LEZ program code is + immutable by construction, since a `ProgramId` is the RISC0 image ID computed + from the bytecode and the deployed-program registry is append-only, so this + requirement is about indirection rather than upgradeability: the module must + not reach any part of its consensus or inclusion verification through a + `ProgramId` held in mutable account state, or any equivalent that lets a + party repoint it after deployment. Legitimate, authorised upgrades have + shipped catastrophic verification bugs in production bridges (see [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)), - which an immutable program forecloses by construction. Document the migration - mechanism and how consumers are expected to move across a migration. + and a repointable verifier reintroduces that risk in a different form. Change + is delivered by deploying a new version and having consumers move to it; + document the migration mechanism and what consumers must do. + + Because consumers reference this module by its image ID, the same discipline + applies on their side, and the consumer documentation (Supportability #6) + must say so: a consuming program that holds this module's `ProgramId` in + mutable state inherits exactly the risk this requirement removes, since + whoever controls that pointer can substitute a module that attests to + anything. + 4. Document the failure modes that follow from a compromised or colluding sync committee, and what a consuming application can do to bound its exposure (for example, caps and freeze authorities on the consumer side, as [RFP-021](./RFP-021-wrapped-erc20.md) specifies). + 5. User-facing and developer-facing documentation must state the trustless verification model and the liveness-only role of any off-chain participant (see Design Rationale, "The anchor: Ethereum finality via the sync diff --git a/RFPs/RFP-023-gas-token-bridge.md b/RFPs/RFP-023-gas-token-bridge.md index 5e002e89..9cee1ba9 100644 --- a/RFPs/RFP-023-gas-token-bridge.md +++ b/RFPs/RFP-023-gas-token-bridge.md @@ -631,14 +631,19 @@ Use FURPS framework. Each numbered item should be a testable statement. 6. User-facing documentation must state the trustless verification model and the liveness-only role of any off-chain participant, including whoever submits a release on a user's behalf. -7. The verifier (the LEZ vault program and the Ethereum contract's proof - verification logic) must be deployed as an immutable program with an explicit - migration path (deploy a new version, drain and redirect to it) in preference - to an upgradeable contract governed by a mutable key, for the reasons set out - in RFP-021, Bridge Security #7 and +7. **Verification logic must be fixed at deployment on both chains**, on the + same terms as RFP-021, Bridge Security #7: no party may change what the + bridge accepts as a valid proof after deployment. On LEZ, where program code + is immutable by construction, this means the vault program must not reach its + verification logic through a `ProgramId` held in mutable account state or any + equivalent repointable indirection. On Ethereum, the contract's verification + logic must have no upgrade path, proxy substitution, or admin-replaceable + verifier address. This matters as much here as in RFP-021, since a + substituted verifier on the Ethereum side could mint the gas-token ERC-20 + against a lock that never happened, breaking the supply invariant in #5. See [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md). - Proposals must document the chosen migration mechanism and how in-flight - locks and burns are honoured across a migration. + Change is delivered by migration; proposals must document the mechanism and + how in-flight locks and burns are honoured across it. 8. The freeze authority stops new activity but does not by itself recover funds already at risk or resolve locks and burns left in-flight once a vulnerability in the verification logic is found. Proposals must specify a From 3f96e358c278b75b696446bbcd432b6496fd8fdf Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Mon, 17 Aug 2026 16:00:00 +1000 Subject: [PATCH 59/69] RFPs 021-023: cut the over-explanation around mutable verification logic The requirement is one sentence and had grown into twenty lines of platform background, plus two rationale paragraphs explaining LEZ program identity and ChainedCall indirection. None of it changed what an applicant builds. Requirements now read "The verification logic cannot be swapped", followed only by the two chain-specific bans that are the actual testable content. The rationale states plainly that mutable verification logic is unwanted and attributes the two risks correctly: whoever can change it can point the bridge at a verifier that accepts anything, which has no documented cross-chain bridge example, and an upgrade made in good faith can ship a catastrophic bug, which caused Nomad (~$190M) and nearly caused a second Ronin incident in 2024 ($12M, returned). Both figures and the no-stolen-upgrade-key finding are as sourced in the appendix. Also removes "which fixed verification logic forecloses by construction", which was ambiguous about what forecloses what. Net -45 lines. Co-Authored-By: Claude Opus 5 --- RFPs/RFP-021-wrapped-erc20.md | 70 +++++++--------------- RFPs/RFP-022-ethereum-state-attestation.md | 26 +++----- RFPs/RFP-023-gas-token-bridge.md | 21 +++---- 3 files changed, 36 insertions(+), 81 deletions(-) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-021-wrapped-erc20.md index 74d6e66a..e0c9d48a 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-021-wrapped-erc20.md @@ -156,34 +156,16 @@ cryptographic design does not remove, because it depends on that logic being correct (see [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md) for the sourced figures, per-hack root causes, and the exact Chainalysis -citation). Mutable verification logic carries a related risk one layer down: no -cross-chain bridge hack has traced to a stolen upgrade key, but legitimate, -authorised upgrades have shipped catastrophic verification bugs (Nomad; a second -Ronin incident in 2024), which fixed verification logic forecloses by -construction. - -The two chains differ in how that risk arises, and the requirement below is -written accordingly. On Ethereum it is the familiar one: a verifier behind an -upgradeable proxy can have its implementation replaced, whether by a stolen key -or by an authorised upgrade that ships a bug. On LEZ it cannot arise the same -way, because a program's identity is the hash of its code: a `ProgramId` is the -RISC0 image ID computed from the bytecode, the deployed-program registry is -append-only, and a deployment transaction carries no authority or deployer -identity that could later authorise a change. Changing one byte produces a -different program, not a new version of the same one. LEZ program code is -therefore immutable by construction rather than by choice. - -What remains possible on LEZ is indirection. A program may hold another -program's `ProgramId` in its own account state and dispatch to it at runtime, so -an immutable bridge program could still point at swappable verification logic -and a party controlling that pointer could repoint it at a verifier that accepts -anything. That is the same fund-stealing capability as a stolen upgrade key, -relocated from the code to the pointer, which is why the requirement below -addresses the pointer rather than the deployment. This RFP treats verification -logic correctness (audit, formal methods, extensive adversarial testing) as a -security requirement of the same order as eliminating signer trust. Per-token -and global caps and an admin-governed freeze authority remain as operational -safety nets against both failure modes. +citation). This RFP therefore does not want mutable verification logic, which +carries two distinct risks: whoever can change it can point the bridge at a +verifier that accepts anything, and an upgrade made in good faith can ship a +catastrophic bug. The first has no documented cross-chain bridge example; the +second caused Nomad (~$190M) and nearly caused a second Ronin incident in 2024 +($12M, returned). This RFP treats verification logic correctness (audit, formal +methods, extensive adversarial testing) as a security requirement of the same +order as eliminating signer trust. Per-token and global caps and an +admin-governed freeze authority remain as operational safety nets against both +failure modes. ## 🏗 Design Rationale @@ -642,29 +624,17 @@ Use FURPS framework. Each numbered item should be a testable statement. liveness-only role of any off-chain participant (see Design Rationale, "Trust model"). -7. **Verification logic must be fixed at deployment on both chains.** No party, - however privileged, may change what the bridge accepts as a valid proof after - deployment. Concretely: - - - **LEZ.** Program code is immutable by construction, so the requirement is - about dispatch: the bridge program must not reach its verification logic - through a `ProgramId` held in mutable account state, or any equivalent - indirection that lets an authority repoint it. The verifying program's - image ID is fixed in the bridge program's own code at deployment. - - **Ethereum.** The vault's proof verification logic must have no upgrade - path: no proxy whose implementation can be substituted, no - admin-replaceable verification key or address, no privileged path to alter - what the verifier accepts. - - The risk being foreclosed is the same on both sides, and is documented in - real bridge losses (see Why This Matters and - [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)): - an authority that can substitute verification logic, whether by holding an - upgrade key or by controlling a program pointer, can point the bridge at a - verifier that accepts anything and drain it. Change is delivered by migration - instead: deploy a new version and drain and redirect to it. Proposals must +7. **The verification logic cannot be swapped.** No party may change what the + bridge accepts as a valid proof after deployment. + + - **LEZ.** The verifying program's image ID is fixed in the bridge program's + code, never read from mutable account state. + - **Ethereum.** No proxy whose implementation can be substituted, and no + admin-replaceable verifier address or key. + + Change requires deploying a new version and migrating to it. Proposals must document the migration mechanism and how in-flight deposits and burns are - honoured across a migration. + honoured across it. 8. The freeze authority (Functionality #14) stops new activity but does not by itself recover funds already at risk or resolve deposits and burns left diff --git a/RFPs/RFP-022-ethereum-state-attestation.md b/RFPs/RFP-022-ethereum-state-attestation.md index 10b7634f..577fb1bc 100644 --- a/RFPs/RFP-022-ethereum-state-attestation.md +++ b/RFPs/RFP-022-ethereum-state-attestation.md @@ -470,24 +470,14 @@ Use FURPS framework. Each numbered item should be a testable statement. or receipts root; a proof replayed against a different chain ID; and a predicate asserted over state the inclusion proof does not cover. -3. **Verification logic must be fixed at deployment.** LEZ program code is - immutable by construction, since a `ProgramId` is the RISC0 image ID computed - from the bytecode and the deployed-program registry is append-only, so this - requirement is about indirection rather than upgradeability: the module must - not reach any part of its consensus or inclusion verification through a - `ProgramId` held in mutable account state, or any equivalent that lets a - party repoint it after deployment. Legitimate, authorised upgrades have - shipped catastrophic verification bugs in production bridges (see - [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)), - and a repointable verifier reintroduces that risk in a different form. Change - is delivered by deploying a new version and having consumers move to it; - document the migration mechanism and what consumers must do. - - Because consumers reference this module by its image ID, the same discipline - applies on their side, and the consumer documentation (Supportability #6) - must say so: a consuming program that holds this module's `ProgramId` in - mutable state inherits exactly the risk this requirement removes, since - whoever controls that pointer can substitute a module that attests to +3. **The verification logic cannot be swapped.** No consensus or inclusion + verification may be reached through a `ProgramId` held in mutable account + state. Change requires deploying a new version and having consumers move to + it; document the migration mechanism and what consumers must do. + + The consumer documentation (Supportability #6) must state that the same rule + applies to consumers: a program holding this module's `ProgramId` in mutable + state lets whoever controls that pointer substitute a module that attests to anything. 4. Document the failure modes that follow from a compromised or colluding sync diff --git a/RFPs/RFP-023-gas-token-bridge.md b/RFPs/RFP-023-gas-token-bridge.md index 9cee1ba9..7ca28c83 100644 --- a/RFPs/RFP-023-gas-token-bridge.md +++ b/RFPs/RFP-023-gas-token-bridge.md @@ -631,19 +631,14 @@ Use FURPS framework. Each numbered item should be a testable statement. 6. User-facing documentation must state the trustless verification model and the liveness-only role of any off-chain participant, including whoever submits a release on a user's behalf. -7. **Verification logic must be fixed at deployment on both chains**, on the - same terms as RFP-021, Bridge Security #7: no party may change what the - bridge accepts as a valid proof after deployment. On LEZ, where program code - is immutable by construction, this means the vault program must not reach its - verification logic through a `ProgramId` held in mutable account state or any - equivalent repointable indirection. On Ethereum, the contract's verification - logic must have no upgrade path, proxy substitution, or admin-replaceable - verifier address. This matters as much here as in RFP-021, since a - substituted verifier on the Ethereum side could mint the gas-token ERC-20 - against a lock that never happened, breaking the supply invariant in #5. See - [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md). - Change is delivered by migration; proposals must document the mechanism and - how in-flight locks and burns are honoured across it. +7. **The verification logic cannot be swapped**, on the same terms as RFP-021, + Bridge Security #7: on LEZ the verifying program's image ID is fixed in the + vault program's code and never read from mutable account state; on Ethereum + there is no substitutable proxy and no admin-replaceable verifier address. A + swapped verifier here would mint the gas-token ERC-20 against a lock that + never happened, breaking the supply invariant in #5. Change requires + deploying a new version and migrating; document the mechanism and how + in-flight locks and burns are honoured across it. 8. The freeze authority stops new activity but does not by itself recover funds already at risk or resolve locks and burns left in-flight once a vulnerability in the verification logic is found. Proposals must specify a From cdb150539016af7cb01200e17cfd1aba57d72237 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 18 Aug 2026 12:44:40 +1000 Subject: [PATCH 60/69] Swap RFP-021 and RFP-022; fix references after restructure The wrapped ERC-20 and Ether bridge becomes RFP-022 and the Ethereum state attestation primitive becomes RFP-021, so the shared primitive carries the lower number and its consumers follow it. Renames both files and swaps every ID, title, link and cross-reference across the three RFPs, the README table, the proposal dropdown and the bridges appendix. README and dropdown rows reordered to stay numeric. Also fixes references broken by the section restructure in the bridge RFP: - Privacy Preservation #8 -> #7 (an item was removed) - Supportability #8 (audit) -> Security #1, following the move to the new Security section - Supportability #9 (privacy properties document) was deleted, so the out-of-scope note now points at Privacy Preservation #6, which carries the surviving disclosure obligation - Soft Requirement #3 -> #2 (viewing keys, after deletions) - Soft Requirement #4's "as per F TODO" resolved to Security #8, the rule that verification logic cannot be swapped RFP-023's references into the bridge RFP updated for the same restructure: Bridge Security #8 -> Security #9, Bridge Security #7 -> Security #8, and the privacy-properties reference made self-contained since its target no longer exists. Minor: stray double space, a stray indent in a doc-packet item, and reflow of the newly added unwrapped lines. Co-Authored-By: Claude Opus 5 --- .github/ISSUE_TEMPLATE/proposal.yml | 4 +- ... => RFP-021-ethereum-state-attestation.md} | 20 +- ...pped-erc20.md => RFP-022-wrapped-erc20.md} | 289 ++++++++---------- RFPs/RFP-023-gas-token-bridge.md | 122 ++++---- appendix/bridges-and-wrapped-tokens.md | 28 +- 5 files changed, 206 insertions(+), 257 deletions(-) rename RFPs/{RFP-022-ethereum-state-attestation.md => RFP-021-ethereum-state-attestation.md} (98%) rename RFPs/{RFP-021-wrapped-erc20.md => RFP-022-wrapped-erc20.md} (82%) diff --git a/.github/ISSUE_TEMPLATE/proposal.yml b/.github/ISSUE_TEMPLATE/proposal.yml index 6ae0ea2a..c1d3fa28 100644 --- a/.github/ISSUE_TEMPLATE/proposal.yml +++ b/.github/ISSUE_TEMPLATE/proposal.yml @@ -14,8 +14,8 @@ body: - "RFP-015 — Token Launchpad: Bonding Curve" - "RFP-016 — Token Launchpad: LBP" - "RFP-017 — Privacy-Preserving Token Vesting" - - "RFP-021 — Wrapped ERC-20 Bridge for LEZ" - - "RFP-022 — Trustless Ethereum State Attestation for LEZ" + - "RFP-021 — Trustless Ethereum State Attestation for LEZ" + - "RFP-022 — Wrapped ERC-20 Bridge for LEZ" - "RFP-023 — Native Gas Token Bridge for LEZ" validations: required: true diff --git a/RFPs/RFP-022-ethereum-state-attestation.md b/RFPs/RFP-021-ethereum-state-attestation.md similarity index 98% rename from RFPs/RFP-022-ethereum-state-attestation.md rename to RFPs/RFP-021-ethereum-state-attestation.md index 577fb1bc..bb6f846e 100644 --- a/RFPs/RFP-022-ethereum-state-attestation.md +++ b/RFPs/RFP-021-ethereum-state-attestation.md @@ -1,5 +1,5 @@ --- -id: RFP-022 +id: RFP-021 title: Trustless Ethereum State Attestation for LEZ tier: M status: open @@ -13,7 +13,7 @@ dependencies: -# RFP-022 — Trustless Ethereum State Attestation for LEZ +# RFP-021 — Trustless Ethereum State Attestation for LEZ > **Note.** This specification describes an outcome that may benefit the Logos > ecosystem. It is a proposal rather than an instruction. Its requirements @@ -80,11 +80,11 @@ Every LEZ program that wants to react to something that happened on Ethereum faces the same problem, and today each would have to solve it independently. Three workstreams already need it, and they need the same thing: -- **The wrapped-token bridge** ([RFP-021](./RFP-021-wrapped-erc20.md)). An +- **The wrapped-token bridge** ([RFP-022](./RFP-022-wrapped-erc20.md)). An Ethereum vault escrows an ERC-20 or native ETH and a LEZ program mints a canonical wrapped representation. Minting must happen only against a real, finalised deposit, with no signer or federation trusted to attest to it. That - is a verified deposit statement feeding a mint. RFP-021 already requires + is a verified deposit statement feeding a mint. RFP-022 already requires trustless verification of Ethereum consensus and state rather than an inclusion check alone; this RFP is where that verification is specified and built. @@ -95,7 +95,7 @@ Three workstreams already need it, and they need the same thing: the read-only consumer, using the same attestation with no minting action attached. - **The native gas token bridge** ([RFP-023](./RFP-023-gas-token-bridge.md)). - The reverse-direction counterpart to RFP-021, in which LEZ is the vault and + The reverse-direction counterpart to RFP-022, in which LEZ is the vault and Ethereum the minter. Releasing native gas token from the LEZ vault requires proof that the corresponding ERC-20 was really burned on Ethereum, which is another verified statement over finalised Ethereum state, consumed by a @@ -235,7 +235,7 @@ documentation deliverable (Supportability #6). by construction. Amounts and timing of deposits and releases are visible on the public chain, and linking them to LEZ activity is a separate privacy problem, handled by the consuming application through fixed denominations, delayed -submission, and anonymity-set growth (see [RFP-021](./RFP-021-wrapped-erc20.md), +submission, and anonymity-set growth (see [RFP-022](./RFP-022-wrapped-erc20.md), Design Rationale, "The privacy requirement, stated precisely"). What this RFP must guarantee is narrower and still essential: verifying and consuming an attestation must not itself add a new correlation signal beyond what Ethereum @@ -245,7 +245,7 @@ statement's public inputs are constrained in Functionality #8. **It does not verify LEZ state on Ethereum.** The reverse direction, proving a LEZ event natively on Ethereum, is specific to the bridge and stays in -[RFP-021](./RFP-021-wrapped-erc20.md). +[RFP-022](./RFP-022-wrapped-erc20.md). ### Consumption model @@ -483,7 +483,7 @@ Use FURPS framework. Each numbered item should be a testable statement. 4. Document the failure modes that follow from a compromised or colluding sync committee, and what a consuming application can do to bound its exposure (for example, caps and freeze authorities on the consumer side, as - [RFP-021](./RFP-021-wrapped-erc20.md) specifies). + [RFP-022](./RFP-022-wrapped-erc20.md) specifies). 5. User-facing and developer-facing documentation must state the trustless verification model and the liveness-only role of any off-chain participant @@ -527,7 +527,7 @@ Use FURPS framework. Each numbered item should be a testable statement. The following are explicitly excluded from this RFP: - **Verifying LEZ state or events on Ethereum.** The reverse direction is - specific to the bridge and stays in [RFP-021](./RFP-021-wrapped-erc20.md). + specific to the bridge and stays in [RFP-022](./RFP-022-wrapped-erc20.md). - **Any application action.** Minting, escrow release, settlement, and every other action belong to the consuming program. This RFP emits a verified statement and stops there. @@ -618,7 +618,7 @@ All code must be released under the **MIT+Apache2.0 dual License**. - [RFP-020 — RedStone Off-Chain Oracle Adaptor for LEZ](./RFP-020-redstone-oracle-adaptor.md) (reference for in-program verification cost measurement, and for the shared verification core between a library and a program deployment shape) -- [RFP-021 — Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ](./RFP-021-wrapped-erc20.md) +- [RFP-022 — Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ](./RFP-022-wrapped-erc20.md) (primary consumer; the mint side depends on this attestation) - [RFP-023 — Native Gas Token Bridge for LEZ](./RFP-023-gas-token-bridge.md) (consumer; the gas-token release path depends on this attestation) diff --git a/RFPs/RFP-021-wrapped-erc20.md b/RFPs/RFP-022-wrapped-erc20.md similarity index 82% rename from RFPs/RFP-021-wrapped-erc20.md rename to RFPs/RFP-022-wrapped-erc20.md index e0c9d48a..4dafd6d7 100644 --- a/RFPs/RFP-021-wrapped-erc20.md +++ b/RFPs/RFP-022-wrapped-erc20.md @@ -1,11 +1,11 @@ --- -id: RFP-021 +id: RFP-022 title: Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ tier: L status: open category: Developer Tooling & Infrastructure dependencies: - - id: RFP-022 + - id: RFP-021 reason: The trustless Ethereum state attestation primitive is what the LEZ bridge program uses to verify a deposit really happened on Ethereum, as specified in Functionality. - id: RFP-001 reason: Admin authority governs the supported-token registry and the deposit/redemption caps, as specified in Functionality. @@ -17,7 +17,7 @@ dependencies: -# RFP-021 — Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ +# RFP-022 — Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ > **Note.** This specification describes an outcome that may benefit the Logos > ecosystem. It is a proposal rather than an instruction. Its requirements @@ -58,7 +58,7 @@ An Ethereum-side vault contract escrows deposits. A LEZ-side program mints the corresponding wrapped token once it has cryptographically verified, with no trusted intermediary, that the deposit really happened on Ethereum; that verification is the attestation primitive specified in -[RFP-022](./RFP-022-ethereum-state-attestation.md), which this RFP consumes +[RFP-021](./RFP-021-ethereum-state-attestation.md), which this RFP consumes rather than rebuilds. Redemption reverses the flow: burning the wrapped token on LEZ entitles the holder to release the original ERC-20 from the vault, again on cryptographic proof alone. @@ -395,7 +395,7 @@ Use FURPS framework. Each numbered item should be a testable statement. 03. Implement a LEZ bridge program that mints the corresponding wrapped token on cryptographic verification of a valid Ethereum deposit. Verification must require no trusted party, and must consume the attestation primitive from - [RFP-022](./RFP-022-ethereum-state-attestation.md) rather than implementing + [RFP-021](./RFP-021-ethereum-state-attestation.md) rather than implementing its own Ethereum consensus and inclusion verification. Uniqueness (that one deposit cannot be minted against twice, per Reliability #3) is this program's responsibility, keyed on the statement identifier the attestation @@ -420,15 +420,14 @@ Use FURPS framework. Each numbered item should be a testable statement. the flow. This does not extend to the wrapped token itself: once minted, it is an ordinary LEZ token redeemable by whoever holds it, regardless of who made the original deposit. -10. An admin authority (per RFP-001, integrated via the SPEL framework where - applicable to the LEZ side) can register a supported ERC-20 (Ethereum +10. An admin authority (per RFP-001) can register a supported ERC-20 (Ethereum address, LEZ wrapped mint, decimals, permitted amounts, caps) and deregister a token. Documentation needs to be provided to handle registration changes with minimum impact for users, including delisting of a token. 11. Global and per-token deposit and redemption caps, configurable by the admin authority, bound the maximum value that can be minted or released within a rolling window, as a rate limiter independent of the freeze authority. Cap - enforcement must not require identifying individual users. + enforcement per blockchain account is sufficient. 12. The finality depth required before a deposit may be claimed, and before a burn may be released, is configurable by the admin authority per deployment, defaulting to the depth recommended in Design Rationale, "Finality and reorg @@ -462,64 +461,88 @@ Use FURPS framework. Each numbered item should be a testable statement. #### Usability -1. Build core functionalities for both users and admin in a Logos core module, - enabling the delivery of different Logos ui modules to use these programs: - depositing, claiming a deposit on LEZ, redeeming, releasing on Ethereum, - recovering a position from user credentials, and reading and administering - the supported-token registry and its permitted amounts. -2. Provide a Logos mini-app, aka Logos ui module, covering the deposit and - redemption flows end to end, position recovery, and a registry view showing - supported tokens, permitted amounts, caps and current utilisation. Also - provide a UI for the admin functionality; whether this is combined into one - UI or delivered as two separate ones is left to the applicant's choice. -3. Any long-running off-chain component the design requires must be provided as - a **Logos module accompanied by a Logos Core headless CLI/daemon**, runnable - standalone, supporting configurable RPC endpoints for both chains, - configurable finality depth, structured logging, and a clean shutdown path. - Document the operator journey end-to-end: install, configure, run, monitor. -4. Provide an IDL for the LEZ bridge program using the - [SPEL framework](https://github.com/logos-co/spel). -5. The mitigations to the three correlation points in Design Rationale, "The - privacy requirement, stated precisely" (amount, timing, fee payer) must be - enabled by default for users. The mini-app and CLI must show a clear - indicator of what data would be leaked by the user's current choices, and - default to the recommended parameters (fixed denomination, delayed - submission, permissionless relayer) rather than requiring the user to select - them. -6. Although minting and burning both support public LEZ accounts (Functionality - #4, #6), the mini-app and CLI must default to inviting the user to mint into, - and burn from, a private account: the private path is the pre-selected option - in the flow, and choosing the public path instead requires an explicit - action, consistent with Privacy Preservation #8. -7. Documentation and UI must clearly explain what is public and what is private - at each step on both chains, so users can judge their own exposure. -8. Return clear, actionable error messages for all failure modes: unsupported - token, invalid amount, cap exceeded, verification failure, insufficient - finality, already claimed, and program or per-token frozen. Error messages - must not reveal which deposit or burn a failed attempt referred to. +01. Build core functionalities for both users and admin in a Logos core module, + enabling the delivery of different Logos ui modules to use these programs: + depositing, claiming a deposit on LEZ, redeeming, releasing on Ethereum, + recovering a position from user credentials, and reading and administering + the supported-token registry and its permitted amounts. +02. Provide a Logos mini-app, aka Logos ui module, covering the deposit and + redemption flows end to end, position recovery, and a registry view showing + supported tokens, permitted amounts, caps and current utilisation. Also + provide a UI for the admin functionality; whether this is combined into one + UI or delivered as two separate ones is left to the applicant's choice. +03. Any long-running off-chain component the design requires must be provided as + a **Logos module accompanied by a Logos Core headless CLI/daemon**, runnable + standalone, using LEZ module and Ethereum module for the respective chains + access, configurable finality depth, structured logging, and a clean + shutdown path. Document the operator journey end-to-end: install, configure, + run, monitor. +04. Provide an IDL for the LEZ bridge program using the + [SPEL framework](https://github.com/logos-co/spel). +05. The mitigations to the three correlation points in Design Rationale, "The + privacy requirement, stated precisely" (amount, timing, fee payer) must be + enabled by default for users. The mini-app and CLI must show a clear + indicator of what data would be leaked by the user's current choices, and + default to the recommended parameters (fixed denomination, delayed + submission, permissionless relayer) rather than requiring the user to select + them. +06. Although minting and burning both support public LEZ accounts (Functionality + #4, #6), the mini-app and CLI must default to inviting the user to mint + into, and burn from, a private account: the private path is the pre-selected + option in the flow, and choosing the public path instead requires an + explicit action, consistent with Privacy Preservation #7. +07. Documentation and UI must clearly explain what is public and what is private + at each step on both chains, so users can judge their own exposure. +08. Return clear, actionable error messages for all failure modes: unsupported + token, invalid amount, cap exceeded, verification failure, insufficient + finality, already claimed, and program or per-token frozen. Error messages + must not reveal which deposit or burn a failed attempt referred to. +09. The UI must let users change the targeted Ethereum RPC address and the + targeted LEZ sequencer or zone. +10. All resulting modules are published in catalogue for easy installation. #### Reliability -1. Minting is atomic: a failed or rejected claim leaves the deposit claimable on - retry and consumes nothing. -2. Redemption is atomic at each stage: a failed burn does not destroy wrapped - tokens without preserving the holder's entitlement to release, and a failed - release leaves that entitlement intact. -3. No deposit can be claimed twice and no burn redeemed twice, deterministically - and under adversarial retry. -4. A valid claim remains valid indefinitely; later chain activity must never - invalidate a user's outstanding entitlement. -5. Position recovery is complete: a client restored from user credentials alone - must rediscover every claimable deposit and unredeemed burn, verified by a - test that wipes all local state. -6. Temporary RPC or connectivity failure on either chain leaves any off-chain - component in a recoverable state, able to resume without duplicating work - already done. -7. An interrupted user-side operation does not consume, corrupt, or expose the - user's entitlement. -8. Proposals must integrate mature, audited proof-system implementations rather - than reimplementing zero-knowledge primitives from scratch. -9. CI must be green on the default branch. +01. Minting is atomic: a failed or rejected claim leaves the deposit claimable + on retry and consumes nothing. +02. Redemption is atomic at each stage: a failed burn does not destroy wrapped + tokens without preserving the holder's entitlement to release, and a failed + release leaves that entitlement intact. +03. No deposit can be claimed twice and no burn redeemed twice, + deterministically and under adversarial retry. +04. A valid claim remains valid indefinitely; later chain activity must never + invalidate a user's outstanding entitlement. +05. Position recovery is complete: a client restored from user credentials alone + must rediscover every claimable deposit and unredeemed burn, verified by a + test that wipes all local state. +06. Temporary RPC or connectivity failure on either chain leaves any off-chain + component in a recoverable state, able to resume without duplicating work + already done. +07. An interrupted user-side operation does not consume, corrupt, or expose the + user's entitlement. +08. Proposals must integrate mature, audited proof-system implementations rather + than reimplementing zero-knowledge primitives from scratch. +09. If any off-chain component is necessary, and expected to be run by a 3rd + party, document the effect, and mitigate it, of an outage or malfunction of + said component. +10. End-to-end integration tests exercise the full deposit and redemption round + trip against a LEZ sequencer (standalone mode) and an Ethereum test network + or local fork, and are included in CI. +11. Every hard requirement has at least one corresponding test. +12. Submit a + [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) + for the core module, covering the developer integration journey for both + flows including position recovery. +13. Submit a + [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) + for the CLI and any operator-facing components, covering the core user and + operator journeys respectively. +14. Submit a + [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) + for the deployer journey, covering how an entity stands up its own + independently configured deployment (Functionality #16): registering tokens, + setting fees, configuring the admin and freeze authorities, and the finality + depth. #### Performance @@ -548,56 +571,20 @@ Use FURPS framework. Each numbered item should be a testable statement. #### Supportability -01. The Ethereum vault contract and the LEZ bridge program are deployed and - tested on a public Ethereum testnet and LEZ testnet respectively. -02. End-to-end integration tests exercise the full deposit and redemption round - trip against a LEZ sequencer (standalone mode) and an Ethereum test network - or local fork, and are included in CI. -03. Every hard requirement in Functionality, Usability, Reliability, - Performance, and Privacy Preservation has at least one corresponding test. -04. A README documents end-to-end usage: contract and program addresses, - deployment steps for both chains, and step-by-step instructions for - depositing and redeeming via CLI and mini-app. -05. Submit a - [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for the core module, covering the developer integration journey for both - flows including position recovery. -06. Submit a - [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for the CLI and any operator-facing components, covering the core user and - operator journeys respectively. -07. Submit a - [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for the deployer journey, covering how an entity stands up its own - independently configured deployment (Functionality #16): registering tokens, - setting fees, configuring the admin and freeze authorities, and the finality - depth. -08. The Ethereum vault contract undergoes an independent third-party - smart-contract security audit before mainnet deployment; the audit report - must be published. -09. Provide a **privacy properties document** covering: a formal statement of - Privacy Preservation #1 and #2 and the anonymity set each is measured - against; exactly what is visible on-chain at every step on both chains; what - an adversary observing all public state can and cannot infer; what every - off-chain participant in the design can observe; residual leakage from - timing, amount selection, fee payment, network metadata and usage patterns; - and the conditions under which the guarantees degrade or fail. -10. Document the anonymity-set growth model: expected set size over time at - projected volumes, the minimum below which the guarantees are considered not - to hold, and guidance for users bridging before the pool has matured. -11. The UI must let users change the targeted Ethereum RPC address and the - targeted LEZ sequencer or zone. -12. The deliverable must be published on the module catalog. -13. The repository must use the standard Logos GitHub Actions. +1. The Ethereum vault contract and the LEZ bridge program are deployed and + tested on a public Ethereum testnet and LEZ testnet respectively. +2. The modules work on both Linux and MacOS platforms. +3. The repository must use the standard Logos GitHub Actions. -#### + Bridge Security +#### + Security -1. Proof verification must be independently verifiable. Both the LEZ program and +1. Both blockchain contracts undergoes an independent third-party smart-contract + security audit before mainnet deployment; the audit report must be published. +2. Proof verification must be independently verifiable. Both the LEZ program and the Ethereum vault must reject invalid proofs, including those with incorrect public inputs, proofs for incorrect chain state, tampered headers, and replayed proofs. - -2. A malicious party submitting on a user's behalf must not be able to redirect +3. A malicious party submitting on a user's behalf must not be able to redirect funds, inflate their fee, or replay the user's submission to a different destination: a deposit and a burn must each secretly commit to the destination on the other chain, so that the claim can only be completed by @@ -607,36 +594,23 @@ Use FURPS framework. Each numbered item should be a testable statement. on, can be used to steal it (see Functionality #2, #5). An adversary who observes everything public about a deposit or burn, but does not hold the originating seed, cannot construct a valid claim for a different destination. - -3. Caps (Functionality #11) bound the maximum value at risk in any rolling +4. Caps (Functionality #11) bound the maximum value at risk in any rolling window; proposals must document recommended defaults and the reasoning behind them. - -4. The freeze authority (Functionality #14) must be exercisable independently on +5. The freeze authority (Functionality #14) must be exercisable independently on each half, so either can be paused without the other being operational or reachable. - -5. Soundness of supply: total wrapped supply on LEZ must never exceed the +6. Soundness of supply: total wrapped supply on LEZ must never exceed the vault's holdings. Minting without a valid deposit, minting twice from one deposit, and releasing without a valid burn must all fail. - -6. User-facing documentation must state the trustless verification model and the +7. User-facing documentation must state the trustless verification model and the liveness-only role of any off-chain participant (see Design Rationale, "Trust model"). - -7. **The verification logic cannot be swapped.** No party may change what the - bridge accepts as a valid proof after deployment. - - - **LEZ.** The verifying program's image ID is fixed in the bridge program's - code, never read from mutable account state. - - **Ethereum.** No proxy whose implementation can be substituted, and no - admin-replaceable verifier address or key. - - Change requires deploying a new version and migrating to it. Proposals must - document the migration mechanism and how in-flight deposits and burns are - honoured across it. - -8. The freeze authority (Functionality #14) stops new activity but does not by +8. **The verification logic cannot be swapped.** No party may change what the + bridge accepts as a valid proof after deployment. Change requires deploying a + new version and migrating to it. Proposals must document the migration + mechanism and how in-flight deposits and burns are honoured across it. +9. The freeze authority (Functionality #14) stops new activity but does not by itself recover funds already at risk or resolve deposits and burns left in-flight once a vulnerability in the verification logic is found. Proposals must specify a failsafe strategy for this scenario, constrained as follows: @@ -674,13 +648,10 @@ Use FURPS framework. Each numbered item should be a testable statement. 5. Failure and error paths must not reveal which deposit or burn was involved: a rejected claim, a repeat claim, and a cap rejection must be indistinguishable in that respect. -6. The client must not make any network request that reveals which deposit or - burn it is acting on. Document every network call made during a - privacy-sensitive operation and justify each. -7. Where a third party submits on the user's behalf, document precisely what +6. Where a third party submits on the user's behalf, document precisely what that party learns, and ensure the user can switch between such parties per operation. -8. The default configuration must be the private one. No user action may be +7. The default configuration must be the private one. No user action may be required to obtain the privacy guarantees, and any override that weakens them must require explicit confirmation. @@ -693,39 +664,17 @@ Use FURPS framework. Each numbered item should be a testable statement. under the hard requirements should be designed so this can be adopted later without redeploying the vault or resetting accumulated anonymity; document the intended migration path even if it is not implemented. - -2. Batching: amortise verification cost across multiple operations in a single - transaction, analogous to the multi-feed batching soft requirement in - RFP-020. - -3. Optional viewing keys allowing a user to *voluntarily* disclose their own +2. Optional viewing keys allowing a user to *voluntarily* disclose their own bridge activity to a chosen third party, without weakening privacy for anyone else and without any protocol-level disclosure capability. - -4. A configurable per-token release delay, in addition to finality and any +3. A configurable per-token release delay, in addition to finality and any user-chosen delay, as an extra circuit-breaker window allowing the admin authority to react to anomalous redemption volume before funds leave the vault. - -5. Support for wrapping ERC-20 tokens from additional EVM chains (e.g. Arbitrum, - Base), each served by its own LEZ bridge program deployment per Functionality - #15 (one program per chain ID, not one program juggling several chains - internally). - -6. Hardware acceleration as an optional path for users with capable machines, - without making it a requirement. - -7. Design the proof-system components as pluggable, so that future zkVM +4. Design the proof-system components as pluggable, so that future zkVM improvements, proof compression, or hardware acceleration can be adopted - without restructuring the vault or the bridge program. - -8. **Reverse direction for a zone's native gas token**, letting a user who holds - nothing on the zone acquire gas from Ethereum, is delivered separately by - [RFP-023](./RFP-023-gas-token-bridge.md), which inverts the roles so that the - LEZ program is the vault and the Ethereum contract is the minter. It builds - on the vault, mint, and privacy construction specified here. Proposals for - this RFP are not asked to address it, but should avoid design choices that - would make the reverse direction harder to build on the same patterns. + without restructuring the vault or the bridge program (redeployment and + migration would be necessary, per Security #8) ### Out of Scope @@ -735,9 +684,9 @@ The following are explicitly excluded from this RFP: - Network-level anonymity. The guarantees here are properties of on-chain state. IP-level correlation between a user's Ethereum deposit and their later LEZ activity is out of scope as an implementation concern, but must be disclosed - as residual leakage under Supportability #9. + as residual leakage under Privacy Preservation #6. - Protocol-level compliance, disclosure, or selective-deanonymisation - mechanisms. Voluntary user-held viewing keys are Soft Requirement #3; any + mechanisms. Voluntary user-held viewing keys are Soft Requirement #2; any capability allowing a third party to deanonymise a user without their consent is contrary to the design and out of scope. - Circuit optimisation or custom zkVM accelerators for the LEZ side: LEZ itself @@ -751,14 +700,14 @@ The following are explicitly excluded from this RFP: ### Hard dependencies -#### Ethereum state attestation (RFP-022) +#### Ethereum state attestation (RFP-021) The inbound leg mints only against a deposit proven to have been finalised on Ethereum, with no signer or federation trusted to attest to it (Functionality #3). That verification, establishing Ethereum finality, proving inclusion of the deposit under a finalised header, and emitting a verified statement, is delivered as a shared primitive by -[RFP-022](./RFP-022-ethereum-state-attestation.md). This RFP consumes it and +[RFP-021](./RFP-021-ethereum-state-attestation.md). This RFP consumes it and does not rebuild it, so that the consensus verification path is audited once and shared with the other LEZ programs that need to read Ethereum state. The outbound leg, verifying a LEZ burn natively on Ethereum, is specific to this @@ -800,7 +749,7 @@ The UI must use the wallet SDK from the Lambda Prize wallet-SDK work. #### RISC0 zkVM The bridge verifies proofs in-program on LEZ (the deposit attestation from -RFP-022 on the inbound leg, and the bridge's own claim and burn logic +RFP-021 on the inbound leg, and the bridge's own claim and burn logic throughout). Because LEZ itself runs on RISC0, a production-ready zkVM, this leg of the design is a LEZ-runtime dependency rather than a choice the proposal makes; proposals must leverage mature RISC0 implementations (e.g. @@ -839,8 +788,8 @@ Estimated software delivery duration: **16–20 weeks**. This is longer than a transparent lock-and-mint bridge would require; the privacy construction, user-side proving, position recovery, and the privacy test suite are the additional scope. This excludes the third-party audit lead time required before -mainnet deployment (Supportability #8), which is typically procured and -scheduled separately. +mainnet deployment (Security #1), which is typically procured and scheduled +separately. ## 🌍 Open Source Requirement @@ -862,7 +811,7 @@ All code must be released under the **MIT+Apache2.0 dual License**. external assets as priced collateral) - [RFP-020 — RedStone Off-Chain Oracle Adaptor for LEZ](./RFP-020-redstone-oracle-adaptor.md) (reference for in-program proof verification cost measurement) -- [RFP-022 — Trustless Ethereum State Attestation for LEZ](./RFP-022-ethereum-state-attestation.md) +- [RFP-021 — Trustless Ethereum State Attestation for LEZ](./RFP-021-ethereum-state-attestation.md) (delivers the verification of finalised Ethereum state that the inbound mint path consumes) - [RFP-023 — Native Gas Token Bridge for LEZ](./RFP-023-gas-token-bridge.md) diff --git a/RFPs/RFP-023-gas-token-bridge.md b/RFPs/RFP-023-gas-token-bridge.md index 7ca28c83..69386d01 100644 --- a/RFPs/RFP-023-gas-token-bridge.md +++ b/RFPs/RFP-023-gas-token-bridge.md @@ -5,9 +5,9 @@ tier: M status: open category: Developer Tooling & Infrastructure dependencies: - - id: RFP-021 - reason: Delivers the vault, mint, registry, caps and privacy construction this RFP inverts; the two bridges share their patterns and their proof-verification approach. - id: RFP-022 + reason: Delivers the vault, mint, registry, caps and privacy construction this RFP inverts; the two bridges share their patterns and their proof-verification approach. + - id: RFP-021 reason: The trustless Ethereum state attestation primitive is what the LEZ vault program uses to verify an ERC-20 burn really happened on Ethereum, as specified in Functionality. - id: RFP-001 reason: Admin authority governs the caps, the finality depth, and the chain and zone pairing, as specified in Functionality. @@ -53,7 +53,7 @@ dependencies: ## 🧭 Overview Build the reverse-direction counterpart to -[RFP-021](./RFP-021-wrapped-erc20.md): a trustless, privacy-preserving bridge in +[RFP-022](./RFP-022-wrapped-erc20.md): a trustless, privacy-preserving bridge in which **LEZ is the vault** and Ethereum is the minter, so a zone's native gas token can be represented as an ERC-20 on Ethereum and acquired by someone who holds nothing on the zone yet. @@ -63,9 +63,9 @@ vault entitles the holder to mint the corresponding ERC-20 on Ethereum, on cryptographic proof of the lock. Burning that ERC-20 on Ethereum entitles the holder to release native gas token from the LEZ vault, on cryptographic proof of the burn, verified in-program on LEZ via the attestation primitive from -[RFP-022](./RFP-022-ethereum-state-attestation.md). +[RFP-021](./RFP-021-ethereum-state-attestation.md). -This is RFP-021's construction with the chains swapped, and it inherits that +This is RFP-022's construction with the chains swapped, and it inherits that RFP's requirements accordingly: the same trustless verification model, the same unlinkability guarantees, the same caps and freeze authority, the same immutable verifier preference. It is a separate deliverable because the roles invert. The @@ -73,7 +73,7 @@ vault logic and the mint logic move to opposite chains, which makes the LEZ program the thing holding value and the Ethereum contract the thing issuing a representation, with a correspondingly different audit target. -One problem is genuinely new and has no analogue in RFP-021: releasing native +One problem is genuinely new and has no analogue in RFP-022: releasing native gas token to a recipient who, by construction, has no gas with which to pay for the release. This RFP resolves it with an **off-chain paymaster service**, the third component of a deployment alongside the vault and the Ethereum contract. A @@ -115,8 +115,8 @@ pattern exists to avoid. This RFP is the trustless entry path. Someone who holds ETH and an Ethereum wallet can acquire native gas token by burning an ERC-20 representation, with no custodian, no faucet operator, and no funding source that links their new LEZ -account to their Ethereum identity. It closes the loop that RFP-021 opens: -RFP-021 brings external *value* onto LEZ as wrapped assets, but a user still +account to their Ethereum identity. It closes the loop that RFP-022 opens: +RFP-022 brings external *value* onto LEZ as wrapped assets, but a user still needs gas to do anything with it, and wrapped USDC does not pay for a transaction. Together the two bridges make a user's first interaction with a zone possible without trusting anyone. @@ -130,20 +130,20 @@ the zone having bootstrapped its own DEX first. ### Inverted roles -In RFP-021, the Ethereum contract is the vault and the LEZ program is the +In RFP-022, the Ethereum contract is the vault and the LEZ program is the minter. Here the roles swap: - **Outbound (LEZ to Ethereum).** A user locks native gas token in the LEZ vault program. Proof of that lock entitles the holder to mint the corresponding ERC-20 on Ethereum. The proof is verified natively on Ethereum, the same - problem RFP-021 solves for its burn-to-release leg. + problem RFP-022 solves for its burn-to-release leg. - **Inbound (Ethereum to LEZ).** A user burns the ERC-20 on Ethereum. Proof of that burn entitles the holder to release native gas token from the LEZ vault. The proof is verified in-program on LEZ, consuming the attestation primitive - from [RFP-022](./RFP-022-ethereum-state-attestation.md) rather than rebuilding + from [RFP-021](./RFP-021-ethereum-state-attestation.md) rather than rebuilding Ethereum consensus and inclusion verification. -Everything else follows RFP-021. The requirements below mirror it item for item +Everything else follows RFP-022. The requirements below mirror it item for item wherever the mirroring is exact, and say so rather than restating the reasoning. ### Supply is demand-driven, and the ERC-20 has no privileged minter @@ -151,7 +151,7 @@ wherever the mirroring is exact, and say so rather than restating the reasoning. The ERC-20 is not a float that anyone stocks in advance. It comes into existence only when someone locks native gas token in the LEZ vault, and it leaves existence only when someone burns it to release that gas token. Supply tracks -demand by construction, exactly as the wrapped-token supply does in RFP-021, and +demand by construction, exactly as the wrapped-token supply does in RFP-022, and no seeding, replenishment, or market-making mechanism is required to make the mechanism work. @@ -281,26 +281,26 @@ SHA-256 preimage standing in for a real proof system, and it documents its own gaps (no recipient binding, no authority binding on initialisation). Proposals should not treat it as a pattern to conform to. -### Privacy mirrors RFP-021 exactly +### Privacy mirrors RFP-022 exactly The privacy construction carries over with the chains swapped, and it carries over in full. Each leg of each bridge has exactly one public endpoint, and it is the Ethereum endpoint in both: -- RFP-021 inbound: public Ethereum deposit, hidden LEZ mint destination. +- RFP-022 inbound: public Ethereum deposit, hidden LEZ mint destination. - RFP-023 inbound: public Ethereum burn, hidden LEZ release destination. -- RFP-021 outbound: hidden LEZ burn, public Ethereum release recipient. +- RFP-022 outbound: hidden LEZ burn, public Ethereum release recipient. - RFP-023 outbound: hidden LEZ lock, public Ethereum mint recipient. Minting an ERC-20 to a public Ethereum address reveals neither more nor less than releasing one from escrow to a public Ethereum address. The hard -requirement is therefore identical to RFP-021's, with the terms substituted: +requirement is therefore identical to RFP-022's, with the terms substituted: **no information other than amount, token, and timing may enable an adversary who observes all public state on both chains, indefinitely, and who may themselves use the bridge, to link an Ethereum burn to the LEZ release it funded, or a LEZ lock to the Ethereum mint it triggered.** -The three correlation points from RFP-021, "The privacy requirement, stated +The three correlation points from RFP-022, "The privacy requirement, stated precisely," apply unchanged and proposals must address each: amounts correlate unless transfers are restricted to fixed per-token denominations; timing correlates unless the protocol permits and the UI encourages delay; and fee @@ -310,7 +310,7 @@ own way. ### Finality, caps, freeze, and pairing -These follow RFP-021 without modification in substance: a configured finality +These follow RFP-022 without modification in substance: a configured finality condition on the source chain in each direction, admin-configurable per deployment; global and per-deployment caps as a rate limiter independent of the freeze authority; a freeze authority exercisable independently on each half; and @@ -338,7 +338,7 @@ Use FURPS framework. Each numbered item should be a testable statement. Ethereum. Verification must require no trusted party. 04. The LEZ vault releases native gas token on cryptographic verification of a valid ERC-20 burn on Ethereum, consuming the attestation primitive from - [RFP-022](./RFP-022-ethereum-state-attestation.md) rather than implementing + [RFP-021](./RFP-021-ethereum-state-attestation.md) rather than implementing its own Ethereum consensus and inclusion verification. **Claiming that release must not require the recipient to already hold native gas token**, and no specific paymaster or other off-chain party may be a required @@ -392,7 +392,7 @@ Use FURPS framework. Each numbered item should be a testable statement. 14. Uniqueness is enforced in both directions: no lock can be minted against twice and no burn released against twice, deterministically and under adversarial retry. On the LEZ side this is keyed on the statement identifier - the RFP-022 attestation carries. + the RFP-021 attestation carries. 15. The amounts visible on Ethereum must not identify which lock or release they correspond to. Proposals must state the mechanism chosen (fixed denominations are the expected baseline) and its effect on anonymity-set @@ -400,7 +400,7 @@ Use FURPS framework. Each numbered item should be a testable statement. 16. A user must be able to recover every one of their own unclaimed locks and unreleased burns from credentials they already hold, with no dependence on any server-side index and no separately-backed-up secret generated during - the flow, on the same terms as RFP-021, "Loss of access." + the flow, on the same terms as RFP-022, "Loss of access." 17. An admin authority (per [RFP-001](./RFP-001-admin-authority-lib.md), integrated via the [SPEL framework](https://github.com/logos-co/spel) where applicable to the LEZ side) can configure the caps, the finality depth, and @@ -466,7 +466,7 @@ Use FURPS framework. Each numbered item should be a testable statement. 06. Provide an IDL for the LEZ vault program using the [SPEL framework](https://github.com/logos-co/spel). 07. The mitigations to the three correlation points in Design Rationale, - "Privacy mirrors RFP-021 exactly" (amount, timing, fee payer) must be + "Privacy mirrors RFP-022 exactly" (amount, timing, fee payer) must be enabled by default. The mini-app and CLI must show a clear indicator of what data would be leaked by the user's current choices, and default to the recommended parameters rather than requiring the user to select them. @@ -518,7 +518,7 @@ Use FURPS framework. Each numbered item should be a testable statement. 1. Verifying a burn and releasing gas token must complete within a single LEZ transaction at the per-transaction compute budget in force at delivery time. Document the compute-unit cost with a breakdown by component, separating the - RFP-022 attestation verification cost from this RFP's own logic, and + RFP-021 attestation verification cost from this RFP's own logic, and extending the measurement methodology from [RFP-020](./RFP-020-redstone-oracle-adaptor.md). 2. Document the Ethereum-side gas cost of a mint, of a burn, and of the LEZ-lock @@ -577,18 +577,18 @@ Use FURPS framework. Each numbered item should be a testable statement. security audit before mainnet deployment; the audit report must be published. The audit scope must explicitly include the mint authorisation path, given the Meter Passport precedent in Design Rationale. -09. Provide a **privacy properties document** on the same terms as RFP-021, - Supportability #9, covering: a formal statement of Privacy Preservation #1 - and #2 and the anonymity set each is measured against; exactly what is - visible on-chain at every step on both chains; what an adversary observing - all public state can and cannot infer; what every off-chain participant can - observe, with a specific section on the paymaster stating exactly what it - learns (the destination account and amount at submission time), what it - cannot learn (the requester's network address, and the link back to the - Ethereum burn), and what a malicious or compromised paymaster could and - could not do; residual leakage from timing, amount selection, fee payment, - network metadata and usage patterns, including what each supported transport - exposes; and the conditions under which the guarantees degrade. +09. Provide a **privacy properties document** covering: a formal statement of + Privacy Preservation #1 and #2 and the anonymity set each is measured + against; exactly what is visible on-chain at every step on both chains; what + an adversary observing all public state can and cannot infer; what every + off-chain participant can observe, with a specific section on the paymaster + stating exactly what it learns (the destination account and amount at + submission time), what it cannot learn (the requester's network address, and + the link back to the Ethereum burn), and what a malicious or compromised + paymaster could and could not do; residual leakage from timing, amount + selection, fee payment, network metadata and usage patterns, including what + each supported transport exposes; and the conditions under which the + guarantees degrade. 10. Document the anonymity-set growth model: expected set size over time at projected volumes, the minimum below which the guarantees are considered not to hold, and guidance for users bridging before the pool has matured. @@ -631,10 +631,10 @@ Use FURPS framework. Each numbered item should be a testable statement. 6. User-facing documentation must state the trustless verification model and the liveness-only role of any off-chain participant, including whoever submits a release on a user's behalf. -7. **The verification logic cannot be swapped**, on the same terms as RFP-021, - Bridge Security #7: on LEZ the verifying program's image ID is fixed in the - vault program's code and never read from mutable account state; on Ethereum - there is no substitutable proxy and no admin-replaceable verifier address. A +7. **The verification logic cannot be swapped**, on the same terms as RFP-022, + Security #8: on LEZ the verifying program's image ID is fixed in the vault + program's code and never read from mutable account state; on Ethereum there + is no substitutable proxy and no admin-replaceable verifier address. A swapped verifier here would mint the gas-token ERC-20 against a lock that never happened, breaking the supply invariant in #5. Change requires deploying a new version and migrating; document the mechanism and how @@ -642,14 +642,14 @@ Use FURPS framework. Each numbered item should be a testable statement. 8. The freeze authority stops new activity but does not by itself recover funds already at risk or resolve locks and burns left in-flight once a vulnerability in the verification logic is found. Proposals must specify a - failsafe strategy, constrained as in RFP-021, Bridge Security #8: any - recovery must still be claimed by the locker or burner proving their own - entitlement, not by an admin authority identifying who owns what; it must not - be able to mint, redirect, or release to any destination other than the one - the proof specifies; and it must not act on funds beyond what a specific, - proven vulnerability put at risk. If no mechanism satisfying these - constraints is achievable, the proposal must document why and what happens to - affected funds in its absence. + failsafe strategy, constrained as in RFP-022, Security #9: any recovery must + still be claimed by the locker or burner proving their own entitlement, not + by an admin authority identifying who owns what; it must not be able to mint, + redirect, or release to any destination other than the one the proof + specifies; and it must not act on funds beyond what a specific, proven + vulnerability put at risk. If no mechanism satisfying these constraints is + achievable, the proposal must document why and what happens to affected funds + in its absence. #### + Privacy Preservation @@ -703,7 +703,7 @@ Use FURPS framework. Each numbered item should be a testable statement. single transaction, analogous to the batching soft requirement in [RFP-020](./RFP-020-redstone-oracle-adaptor.md). -3. **Shared components with RFP-021.** Where the two bridges genuinely share +3. **Shared components with RFP-022.** Where the two bridges genuinely share logic (fixed-denomination handling, position recovery, submission paths, the privacy test harness), factor it so both can consume one implementation rather than maintaining two divergent copies. Document what is shared and @@ -733,11 +733,11 @@ Use FURPS framework. Each numbered item should be a testable statement. The following are explicitly excluded from this RFP: - **Wrapping external ERC-20s and ETH into LEZ.** That is the primary flow, - owned by [RFP-021](./RFP-021-wrapped-erc20.md). This RFP inverts the + owned by [RFP-022](./RFP-022-wrapped-erc20.md). This RFP inverts the direction, it does not duplicate the primary flow. - **The Ethereum state attestation primitive.** Verifying Ethereum consensus, finality, and state inclusion is owned by - [RFP-022](./RFP-022-ethereum-state-attestation.md). This RFP consumes that + [RFP-021](./RFP-021-ethereum-state-attestation.md). This RFP consumes that primitive, it does not define or rebuild it. - **Seeding, replenishment, or market-making for the ERC-20.** Supply is demand-driven by construction (see Design Rationale); there is no float to @@ -764,23 +764,23 @@ The following are explicitly excluded from this RFP: ### Hard dependencies -#### Wrapped ERC-20 and Ether bridge (RFP-021) +#### Wrapped ERC-20 and Ether bridge (RFP-022) This RFP is the reverse-direction counterpart of -[RFP-021](./RFP-021-wrapped-erc20.md) and inherits its vault and mint patterns, +[RFP-022](./RFP-022-wrapped-erc20.md) and inherits its vault and mint patterns, its trust model, its privacy construction, and its approach to caps, freeze -authority, finality and position recovery. RFP-021 establishes those patterns +authority, finality and position recovery. RFP-022 establishes those patterns and carries the reasoning behind them; this RFP applies them with the chains swapped and does not restate them. Delivering this RFP against a materially different set of patterns would fragment the two bridges for no benefit, so -RFP-021 is treated as a hard dependency rather than a reference. +RFP-022 is treated as a hard dependency rather than a reference. -#### Ethereum state attestation (RFP-022) +#### Ethereum state attestation (RFP-021) The inbound leg releases gas token only against an ERC-20 burn proven to have been finalised on Ethereum, with no signer or federation trusted to attest to it (Functionality #4). That verification is delivered as a shared primitive by -[RFP-022](./RFP-022-ethereum-state-attestation.md). This RFP consumes it and +[RFP-021](./RFP-021-ethereum-state-attestation.md). This RFP consumes it and does not rebuild it. The outbound leg, verifying a LEZ lock natively on Ethereum, is specific to this bridge and remains in scope here. @@ -866,8 +866,8 @@ Team experienced with: ## ⏱ Timeline Expectations Estimated software delivery duration: **10–14 weeks**. The construction mirrors -[RFP-021](./RFP-021-wrapped-erc20.md) and consumes -[RFP-022](./RFP-022-ethereum-state-attestation.md) for the Ethereum-reading +[RFP-022](./RFP-022-wrapped-erc20.md) and consumes +[RFP-021](./RFP-021-ethereum-state-attestation.md) for the Ethereum-reading half, so the patterns and much of the tooling are established rather than invented here. The new work is the LEZ-side vault, the Ethereum-side mintable ERC-20 with its authorisation path, and the gasless release mechanism, which is @@ -890,9 +890,9 @@ All code must be released under the **MIT+Apache2.0 dual License**. (same atomic-deshield assumption) - [RFP-020 — RedStone Off-Chain Oracle Adaptor for LEZ](./RFP-020-redstone-oracle-adaptor.md) (reference for in-program proof verification cost measurement) -- [RFP-021 — Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ](./RFP-021-wrapped-erc20.md) +- [RFP-022 — Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ](./RFP-022-wrapped-erc20.md) (the primary flow this RFP inverts) -- [RFP-022 — Trustless Ethereum State Attestation for LEZ](./RFP-022-ethereum-state-attestation.md) +- [RFP-021 — Trustless Ethereum State Attestation for LEZ](./RFP-021-ethereum-state-attestation.md) (delivers the verification of finalised Ethereum state the release path consumes) - [RFP-003 — Atomic Swaps](./RFP-003-atomic-swaps.md) (precedent for using Logos diff --git a/appendix/bridges-and-wrapped-tokens.md b/appendix/bridges-and-wrapped-tokens.md index 855f1cf2..877b3c28 100644 --- a/appendix/bridges-and-wrapped-tokens.md +++ b/appendix/bridges-and-wrapped-tokens.md @@ -1,13 +1,13 @@ # Appendix: Bridges and Wrapped Tokens This appendix surveys the ecosystem context behind -[RFP-021](../RFPs/RFP-021-wrapped-erc20.md), a privacy-preserving wrapped ERC-20 +[RFP-022](../RFPs/RFP-022-wrapped-erc20.md), a privacy-preserving wrapped ERC-20 bridge for LEZ, in two parts. The first and larger part surveys major cross-chain bridge exploits, classifies their root causes, and sources the loss -figures relevant to RFP-021's claim that bridges are the most-attacked category +figures relevant to RFP-022's claim that bridges are the most-attacked category of DeFi infrastructure, and to its design choice to eliminate signer/validator trust while still treating verification-logic correctness and upgrade-key -custody as first-order risks. The second, shorter part sources RFP-021's +custody as first-order risks. The second, shorter part sources RFP-022's stablecoin market-size claim, which motivates the specific tokens (USDC, USDT, DAI, WETH) the RFP proposes wrapping first. @@ -64,7 +64,7 @@ THORChain's own post-mortem confirms both as router logic bugs, not key compromises [27][28]. Losses were approximately $8M in each incident. Included here as a borderline case: it is a cross-chain bridging component being exploited via a logic bug, but THORChain's overall architecture is an -AMM/liquidity network, not a lock-and-mint bridge in the RFP-021 sense. +AMM/liquidity network, not a lock-and-mint bridge in the RFP-022 sense. ### Qubit Finance / QBridge (27-28 January 2022) @@ -227,7 +227,7 @@ in a multisig-controlled vault. ## Upgrade-key compromise: what the evidence shows -RFP-021 treats an upgradeable verifier contract's *upgrade key* as a key-custody +RFP-022 treats an upgradeable verifier contract's *upgrade key* as a key-custody attack surface of the same kind as a validator or multisig key, one layer removed: whoever holds the upgrade key can substitute the verification logic itself, rather than directly signing a fraudulent withdrawal. This is a distinct @@ -284,7 +284,7 @@ and OpenZeppelin) treats post-deployment upgrade mechanisms as a disproportionate source of protocol losses as a general class, but without a bridge-specific incident list to cite. -The practical reading for RFP-021's argument: the *category* of risk (a mutable +The practical reading for RFP-022's argument: the *category* of risk (a mutable verifier controlled by a key that can swap in malicious or broken logic) is real, attested by security-firm framing, and has caused actual bridge losses through Pattern A (a legitimate upgrade shipping a bug, Nomad and Ronin 2024) @@ -299,7 +299,7 @@ patterns rather than only the one with a clean historical precedent. ## Root-cause breakdown Excluding THORChain (a borderline case, not a lock-and-mint bridge in the -RFP-021 sense) and treating Poly Network and Multichain per their categorization +RFP-022 sense) and treating Poly Network and Multichain per their categorization above, the ten core hacks in the summary table break down as follows by dollar value (approximate, using the midpoint of any reported range): @@ -323,7 +323,7 @@ Network because the bug's effect mimicked a stolen governance key without one being stolen). If Poly Network is instead counted toward key custody (its effect being equivalent to a stolen keeper key) and BNB Bridge's actually-exfiltrated figure is used rather than its minted figure, category (a) plus Poly Network's -$611M would dominate instead. The underlying point RFP-021 makes — that key +$611M would dominate instead. The underlying point RFP-022 makes — that key custody is a large but not exclusive source of bridge losses, and verification-logic bugs are a comparably large source — holds directionally across every reasonable way of drawing the boundary cases; a precise 50/50 split @@ -333,7 +333,7 @@ counted. ## Chainalysis figures: what the primary sources actually say -RFP-021 cites Chainalysis for the claim that over $2B was stolen from +RFP-022 cites Chainalysis for the claim that over $2B was stolen from cross-chain bridges in 2022, representing 64% of that year's DeFi hacking losses. Chainalysis in fact published two separate figures, from two separate reports, that are often conflated: @@ -356,7 +356,7 @@ reports, that are often conflated: Both figures are directionally consistent and both support the underlying claim that bridges were the single largest category of DeFi hacking losses in 2022. But the $2B dollar figure and the 64% percentage, as commonly paired in -secondary reporting (including news aggregation that RFP-021's figure likely +secondary reporting (including news aggregation that RFP-022's figure likely traces to), actually come from two different Chainalysis reports measuring different populations over different time windows, not from a single, internally consistent statistic. The more defensible citation is the February 2023 report's @@ -390,7 +390,7 @@ categories (notably exchange and private-key compromises). ## Stablecoin Market Context -RFP-021 cites USDT and USDC together holding "over 80%" of a stablecoin market +RFP-022 cites USDT and USDC together holding "over 80%" of a stablecoin market "above $300B in mid-2026" as the rationale for prioritising those two assets (alongside DAI and WETH) as the bridge's first wrapped tokens. DefiLlama tracks total stablecoin market capitalisation at approximately $310B-$313B through @@ -404,7 +404,7 @@ approximately $183.4B and roughly 59-64% of total stablecoin supply depending on the exact date sampled [36][37]. Circle's USDC is second, at approximately $72B-$75B, roughly 23-24% of supply [37][38]. Combined, USDT and USDC hold approximately 89% of total stablecoin market capitalisation as of early August -2026 [36][37] — comfortably clearing RFP-021's "over 80%" claim rather than +2026 [36][37] — comfortably clearing RFP-022's "over 80%" claim rather than merely meeting it. Supply share is not the same claim as settlement dominance, and the two should @@ -417,7 +417,7 @@ USDC/USDT pairs, and stablecoin swaps make up the majority of DEX trading volume on Ethereum [39]. On lending markets, Aave, the largest lending venue by deposits, reportedly holds an 80%+ share of USDT and USDC deposits/borrows on Ethereum, with stablecoin pools forming the protocol's largest liquidity base -[41]. Taken together, this supports RFP-021's framing that USDT and USDC are the +[41]. Taken together, this supports RFP-022's framing that USDT and USDC are the settlement asset most DeFi money markets and DEXes actually run on, though the volume and collateral-share figures are drawn from secondary market trackers and platform-level reporting rather than a single authoritative cross-protocol @@ -478,5 +478,5 @@ measured. ______________________________________________________________________ -*This appendix was prepared to support RFP-021. For clarification or additions, +*This appendix was prepared to support RFP-022. For clarification or additions, please use the RFP repository Discussions.* From 813c8903ff0477c953d70cdbf92db0c8509be405 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 18 Aug 2026 15:54:35 +1000 Subject: [PATCH 61/69] RFPs 022-023: state privacy conditions, not test instructions FURPS items state the condition to be met; Supportability already requires a test for every hard requirement, so embedded "provide a test that..." instructions are redundant. Also drops a stranded "Provide" fragment left in RFP-023 item 3 by an earlier cleanup pass, and makes each outbound-unlinkability item readable on its own rather than deferring to the inbound item. Co-Authored-By: Claude Opus 5 --- RFPs/RFP-022-wrapped-erc20.md | 26 ++++++++++++-------------- RFPs/RFP-023-gas-token-bridge.md | 22 ++++++++++------------ 2 files changed, 22 insertions(+), 26 deletions(-) diff --git a/RFPs/RFP-022-wrapped-erc20.md b/RFPs/RFP-022-wrapped-erc20.md index 4dafd6d7..b6617f51 100644 --- a/RFPs/RFP-022-wrapped-erc20.md +++ b/RFPs/RFP-022-wrapped-erc20.md @@ -512,9 +512,9 @@ Use FURPS framework. Each numbered item should be a testable statement. deterministically and under adversarial retry. 04. A valid claim remains valid indefinitely; later chain activity must never invalidate a user's outstanding entitlement. -05. Position recovery is complete: a client restored from user credentials alone - must rediscover every claimable deposit and unredeemed burn, verified by a - test that wipes all local state. +05. Position recovery is complete: a client restored from user credentials + alone, with no local state, rediscovers every claimable deposit and + unredeemed burn. 06. Temporary RPC or connectivity failure on either chain leaves any off-chain component in a recoverable state, able to resume without duplicating work already done. @@ -628,17 +628,15 @@ Use FURPS framework. Each numbered item should be a testable statement. #### + Privacy Preservation -1. **Inbound unlinkability must hold under test.** No signal other than amount, - token, and timing may narrow down which LEZ mint an Ethereum deposit funded, - beyond uniform probability over the remaining candidates. Provide an - automated test that constructs a population of deposits and mints and asserts - that no correlation derivable from public state, other than amount, token, - and timing, identifies the true pairing better than chance across the - anonymity set those three signals leave unresolved. -2. **Outbound unlinkability must hold under test.** No signal other than amount, - token, and timing may narrow down which Ethereum release a LEZ burn - triggered, beyond uniform probability over the remaining candidates. The - equivalent test for burn-to-release pairings. +1. **Inbound unlinkability.** No signal other than amount, token, and timing may + narrow down which LEZ mint an Ethereum deposit funded. Across the anonymity + set those three signals leave unresolved, no correlation derivable from + public state identifies the true deposit-to-mint pairing better than chance. +2. **Outbound unlinkability.** No signal other than amount, token, and timing + may narrow down which Ethereum release a LEZ burn triggered. Across the + anonymity set those three signals leave unresolved, no correlation derivable + from public state identifies the true burn-to-release pairing better than + chance. 3. No transaction argument, event, log, or account-state change on either chain may reveal a deposit's LEZ destination or a burn's Ethereum destination. This must hold over full event and state diffs for a complete round trip. diff --git a/RFPs/RFP-023-gas-token-bridge.md b/RFPs/RFP-023-gas-token-bridge.md index 69386d01..51eefc71 100644 --- a/RFPs/RFP-023-gas-token-bridge.md +++ b/RFPs/RFP-023-gas-token-bridge.md @@ -653,19 +653,17 @@ Use FURPS framework. Each numbered item should be a testable statement. #### + Privacy Preservation -1. **Inbound unlinkability must hold under test.** No signal other than amount - and timing may narrow down which LEZ release an Ethereum burn funded, beyond - uniform probability over the remaining candidates. Across a population of - burns and releases, no correlation derivable from public state, other than - amount and timing, identifies the true pairing better than chance across the - anonymity set those signals leave unresolved. -2. **Outbound unlinkability must hold under test.** No signal other than amount - and timing may narrow down which Ethereum mint a LEZ lock triggered, beyond - uniform probability over the remaining candidates. The equivalent test for - lock-to-mint pairings. +1. **Inbound unlinkability.** No signal other than amount and timing may narrow + down which LEZ release an Ethereum burn funded. Across the anonymity set + those signals leave unresolved, no correlation derivable from public state + identifies the true burn-to-release pairing better than chance. +2. **Outbound unlinkability.** No signal other than amount and timing may narrow + down which Ethereum mint a LEZ lock triggered. Across the anonymity set those + signals leave unresolved, no correlation derivable from public state + identifies the true lock-to-mint pairing better than chance. 3. No transaction argument, event, log, or account-state change on either chain - may reveal a lock's Ethereum destination or a burn's LEZ destination. Provide - This must hold over full event and state diffs for a complete round trip. + may reveal a lock's Ethereum destination or a burn's LEZ destination. This + must hold over full event and state diffs for a complete round trip. 4. Information that would connect the two legs must never leave the user's control. Document every component that handles user data; such information must be absent from all submitted transaction data. From 7f8c281513b2df9e7e94612e074ac835fb91fdb4 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Tue, 18 Aug 2026 15:54:49 +1000 Subject: [PATCH 62/69] RFP-021: specify the permissionless operator that keeps consensus state The RFP required trustless Ethereum verification but never said where the tracked sync-committee state lives, leaving applicants to guess between a shared on-chain light client and a bring-your-own-chain design that almost certainly cannot fit a single transaction. Specifies the expected shape: an operator advances shared consensus state, anyone may submit a proof-checked update, and consumers supply only inclusion proofs. Trust is a one-off deployment-time checkpoint, recoverable by fresh deployment rather than by a privileged party mutating an existing one. This removes the admin surface entirely, so the RFP-001 dependency goes with it. Adds an appendix surveying Telepathy, SP1 Helios and r0vm-helios, plus the Across fork that deliberately gates submission behind a role: the clearest evidence that permissionlessness is a design choice rather than something zk proofs confer automatically. Points applicants at r0vm-helios as a RISC Zero reuse candidate to assess, not to assume. Also corrects the consumption model, which described the primitive as a library and forbade depending on any account written by a third party. That contradicted the operator architecture. On testnet and mainnet this is a deployed program with an interface; what must stay in the consumer's transaction is inclusion and predicate evaluation. Co-Authored-By: Claude Opus 5 --- RFPs/RFP-021-ethereum-state-attestation.md | 258 ++++++++++++----- appendix/ethereum-light-client-ecosystem.md | 295 ++++++++++++++++++++ 2 files changed, 489 insertions(+), 64 deletions(-) create mode 100644 appendix/ethereum-light-client-ecosystem.md diff --git a/RFPs/RFP-021-ethereum-state-attestation.md b/RFPs/RFP-021-ethereum-state-attestation.md index bb6f846e..d0af795e 100644 --- a/RFPs/RFP-021-ethereum-state-attestation.md +++ b/RFPs/RFP-021-ethereum-state-attestation.md @@ -5,8 +5,6 @@ tier: M status: open category: Developer Tooling & Infrastructure dependencies: - - id: RFP-001 - reason: Admin authority governs the weak-subjectivity checkpoint, the chain registry, and the finality parameters, as specified in Functionality. - id: LP-0012 reason: Structured on-chain events let clients and off-chain components follow committee handoffs and attestation submissions without polling every account. --- @@ -171,6 +169,64 @@ produce a proof, which is why proof generation must be a liveness role rather than a trust role: no single party may be able to turn a refusal into a block on an honest user. +### Where the tracking state lives: the permissionless operator + +Two costs sit inside an attestation and they are not alike. Proving a header is +finalised requires BLS12-381 aggregate signature verification over +sync-committee signatures plus verification of committee handoffs, and it is +expensive. Proving a piece of state is included under that header is +Merkle-Patricia path verification, and it is cheap. Header finality is also a +fact every consumer needs and no consumer needs privately, whereas inclusion is +specific to the consumer's own transaction. + +The expected design follows that asymmetry. An **operator** runs off-chain, +follows sync-committee handoffs, generates a proof that a light-client finality +update is validly signed, and submits it to LEZ, where a module account +accumulates the verified committee and finalised header roots. A **consumer** +then submits only an inclusion proof against a header already verified in that +shared state, performing no signature verification of its own. + +**The operator must be permissionless.** Anyone can spend the gas and advance +the state; no party is designated, and none can be excluded. The operator is +untrusted because submission is proof-checked: it cannot insert a header the +sync committee did not sign, since doing so would require forging signatures +from two thirds of the committee. It can only stop, which is a liveness failure +repaired by anyone else running the same software. + +Nobody is obliged to run an operator, and the design does not pretend otherwise. +What makes the role viable is that the cost of one submission is small, it +amortises across every consumer reading the resulting header, and the protocols +whose users depend on fresh headers are motivated to keep them fresh. The +guarantee is not that an operator will always act; it is that a stalled +deployment can be restarted by any party willing to pay, without permission and +without any prior relationship to the deployment. The failure mode is delay, not +loss. + +Trust enters once, at deployment, through the weak-subjectivity checkpoint. That +input is independently verifiable against public Ethereum history, which is why +Functionality #9 requires a documented procedure for confirming it rather than +only a configured value. And it is recoverable: nothing prevents a second +deployment with a corrected checkpoint, so a failed bootstrap is repaired by +deploying again rather than by a privileged party mutating the existing one. + +The counterweight is that fragmenting across deployments splits the operator +incentive, duplicates gas, and forces every consumer to choose which contract to +trust, dissolving the shared-state benefit that motivates the architecture. A +single canonical deployment that consumers converge on is the intended outcome, +and redeployment is a recovery path rather than a routine one. + +This pattern is established rather than novel, and it has been built and audited +several times over: Telepathy and SP1 Helios both implement it, and +`r0vm-helios` implements it on the RISC Zero zkVM. Telepathy was audited by +Veridise, SP1 Helios by Zellic, and `r0vm-helios` by zkSecurity. Applicants +should assess reuse rather than assume a rewrite, per the Design Rationale note +below. The +[Ethereum Light Client Ecosystem appendix](../appendix/ethereum-light-client-ecosystem.md) +surveys these implementations, their trust models, and a production fork that +deliberately made submission permissioned, which is direct evidence that +permissionlessness is a design choice rather than a property zk proofs confer +automatically. + ### Trust assumptions the design carries The anchor is not free of assumptions, and both must be documented for consumers @@ -187,9 +243,9 @@ rather than buried: from a trusted checkpoint, a known-good committee, following handoffs forward from there. That initial checkpoint is a trust anchor. The design is trustless after bootstrap, given a correct starting committee, so the specification must - say who supplies the checkpoint, how a verifier confirms it independently, and - how it is refreshed if a deployment falls outside the weak-subjectivity - period. + say how a verifier confirms the checkpoint independently, and when a + deployment that has fallen outside the weak-subjectivity period must be + replaced. Applicants may propose a stronger anchor than sync-committee tracking (full validator-set verification, or a hybrid) and are encouraged to state the cost @@ -249,19 +305,31 @@ LEZ event natively on Ethereum, is specific to the bridge and stays in ### Consumption model -The primitive is delivered as a library callable from a consuming LEZ program, -not only as a standalone program with an account interface. A consumer must be -able to verify an attestation inline within its own transaction, so that -verification and the action it authorises are atomic and the consumer never has -to trust an intermediate account written by someone else. - -A standalone program that verifies and records attestations to a public account -is a legitimate additional deployment shape, since it lets cost be amortised -when many consumers care about the same Ethereum state, and it is specified as a -soft requirement rather than a hard one. Where both shapes exist they must share -a single verification core, so the audit surface and the cost profile stay -common, following the pattern established in -[RFP-020](./RFP-020-redstone-oracle-adaptor.md). +On testnet and mainnet the primitive is a deployed LEZ program with a published +interface, and a consumer calls it. Source-level availability matters for local +testing, review, and reproducing the cost measurements, but it is not the +deployment model: consumers do not each compile and deploy their own copy of the +verification logic, because doing so would fragment the shared consensus state +the architecture depends on and multiply the audited surface. + +What has to be atomic in the consumer's transaction is the part specific to that +consumer. Two things are being consumed and they differ: + +- **Verified consensus state**, the tracked committee and the finalised header + roots, is necessarily shared and necessarily written by an operator. That is + the point of the architecture, and it is safe because submission is + proof-checked: the consumer's trust rests on the verification the module + performed on submission, not on the operator's honesty. +- **Inclusion and predicate evaluation** must occur inside the consumer's own + transaction, against a header the consumer checks for itself, so that + verification and the action it authorises cannot come apart. + +A deployment shape that records evaluated statements to a public account, so +that cost can be amortised when many consumers care about the same Ethereum +state, is a legitimate addition and is specified as a soft requirement. Where it +exists it must share a single verification core with the direct path, so the +audit surface and the cost profile stay common, following the pattern +established in [RFP-020](./RFP-020-redstone-oracle-adaptor.md). ### Cost is a primary deliverable @@ -278,6 +346,27 @@ as it was for RFP-020. Consumers cannot size their own designs without those numbers, and if the cost turns out to be unacceptable the measurement is the input to a follow-on RFP proposing a BLS12-381 precompile for LEZ. +The shared-state architecture changes the shape of this problem without removing +it. Consensus verification cost sits in the operator's submission and amortises +across every consumer, while a consumer's own transaction carries only inclusion +verification. The BLS cost still has to be paid and still has to be measured; +what it no longer has to do is fit inside each consumer's budget. + +### Assess reuse before rewriting + +[`r0vm-helios`](https://github.com/boundless-xyz/r0vm-helios) is an Ethereum +light client built on the RISC Zero zkVM, forked from SP1 Helios and +independently audited by zkSecurity. It solves the hardest and most +security-critical component of this RFP on the same zkVM LEZ runs on, which +makes it a materially different starting point from a blank sheet. + +It is not a drop-in. It targets EVM destination chains with Solidity contracts, +and LEZ is neither. How much transfers, whether the guest program, the operator, +or only the architecture, is a judgement the applicant is better placed to make +than this specification. That evaluation is itself work, and Reliability #6 +scopes it as a deliverable. Reuse is expected to be assessed seriously; it is +not mandated. + ## ✅ Scope of Work ### Hard Requirements @@ -310,44 +399,59 @@ Use FURPS framework. Each numbered item should be a testable statement. identifier derived from the attested Ethereum state, suitable for a consumer to key a nullifier on. Identical Ethereum state yields an identical identifier; distinct state yields a distinct one. -07. The module is callable as a library from a consuming LEZ program, so that - verification and the action it authorises occur in a single transaction. A - consumer must be able to integrate without depending on any account written - by a third party. +07. The module is deployed as a LEZ program with a published interface any + consuming program can call. Inclusion verification and predicate evaluation + occur inside the consuming transaction, and no consumption path requires a + consumer to act on a predicate result computed in an earlier transaction. 08. Verifying and consuming an attestation must not introduce any correlation signal beyond what is already public on Ethereum. The public inputs of the verified statement must be limited to what the consumer explicitly chooses to expose, and must not reveal the identity of the consuming LEZ account or the consuming transaction. This must hold over full event and state diffs. -09. An admin authority (per [RFP-001](./RFP-001-admin-authority-lib.md), - integrated via the [SPEL framework](https://github.com/logos-co/spel) where - applicable) can configure the weak-subjectivity checkpoint, the supported - chain and chain ID, and the finality parameters, per deployment. Document a +09. The weak-subjectivity checkpoint, the supported chain and chain ID, and the + finality parameters are set once per deployment, at deployment. Document a procedure by which anyone can independently verify a configured checkpoint against public Ethereum sources before relying on the deployment. -10. Provide a checkpoint-refresh path for a deployment that has fallen outside - the weak-subjectivity period, and document when a deployment is required to - use it. -11. Proof generation must be a permissionless liveness role: no specific party - may be required to produce an attestation, and any party declining to act - must not block a user. Proposals must identify every off-chain participant - the design requires and justify that none of them, individually or as a - class, can block an attestation from eventually being produced. -12. The design must not assume Ethereum mainnet is the only target. The same +10. A deployment that has fallen outside the weak-subjectivity period is + replaced by a fresh deployment rather than refreshed in place. Document when + a deployment must be replaced, and what a consumer must do to migrate to a + replacement. +11. Advancing the tracked consensus state is permissionless: any party may + submit a valid update, and submission carries no access control, allowlist, + role, or registration. A deployment in which one party, or a fixed set fixed + at deployment, is the only entity able to advance the state does not satisfy + this requirement. An account with no prior relationship to the deployment + can advance the state. +12. Proof generation and submission are liveness roles, not trust roles: no + specific party may be required for an attestation to be produced, and any + party declining to act must not block a user. Proposals must identify every + off-chain participant the design requires, state for each whether it can + affect safety or only liveness, and justify that none of them, individually + or as a class, can block an attestation from eventually being produced. +13. The weak-subjectivity checkpoint is fixed at deployment and is not mutable + by any party thereafter. Recovery from a mis-configured or stale checkpoint + is by fresh deployment, per Functionality #10, not by mutation of an + existing one. +14. The design must not assume Ethereum mainnet is the only target. The same module must be deployable, unmodified, against any Ethereum-consensus chain, mainnet or testnet, with the chain binding in Functionality #5 keeping deployments separate. +15. Multiple independent deployments of the module can coexist, each with its + own checkpoint and chain configuration, without interfering with one + another. A consumer binds to a specific deployment and a statement from one + deployment is never accepted by a consumer bound to another. #### Usability -1. Build the attestation functionality for both consumers and admins in a Logos +1. Build the attestation functionality for consumers and operators in a Logos core module, so that different Logos ui modules can be built on it: producing - an attestation, verifying one, and reading and administering the checkpoint - and chain configuration. + an attestation, verifying one, submitting a consensus-state update, and + reading the checkpoint and chain configuration of a deployment. 2. Provide a CLI that covers producing an attestation for a given `(chain, contract, storage slot or log, predicate)` tuple, verifying one - off-chain as a dry run, and reading and administering the configuration. The - dry run must report the same typed error codes the on-chain path returns. + off-chain as a dry run, submitting a consensus-state update, and reading a + deployment's configuration. The dry run must report the same typed error + codes the on-chain path returns. 3. Any long-running off-chain component the design requires (for example a process that follows sync-committee handoffs and keeps update material available) must be provided as a **Logos module accompanied by a Logos Core @@ -380,14 +484,24 @@ Use FURPS framework. Each numbered item should be a testable statement. 6. Proposals must integrate mature, audited implementations of BLS12-381 signature verification, Merkle-Patricia proof verification, and the light-client protocol rather than reimplementing cryptographic primitives - from scratch. -7. CI must be green on the default branch. + from scratch. Evaluating what existing implementations offer, and stating + what is reused, what is rewritten, and the cost and audit-surface + consequences of that split, is a scoped deliverable to be budgeted in the + proposal (see Design Rationale, "Assess reuse before rewriting"). +7. A deployment left unadvanced does not lose safety: attestations against + already-verified headers continue to verify, and a stalled deployment resumes + correctly when any party submits the outstanding updates, with no manual + repair and no gap in the verified handoff chain. +8. Concurrent submission of the same update by competing operators is handled + without corrupting tracked state: a duplicate or already-applied update is + rejected cleanly rather than double-applied. +9. CI must be green on the default branch. #### Performance 1. Verifying an attestation and evaluating its predicate must complete within a single LEZ transaction at the per-transaction compute budget in force at - delivery time, in the library consumption path of Functionality #7. If this + delivery time, in the direct consumption path of Functionality #7. If this proves infeasible at delivery time, the measurement in Performance #2 stands as the deliverable and the shortfall must be documented with the specific component responsible. @@ -448,13 +562,19 @@ Use FURPS framework. Each numbered item should be a testable statement. supermajority assumption and the cost of the attack it admits; the weak-subjectivity checkpoint, who supplies it and how a verifier confirms it independently; what an attestation does and does not prove; what every - off-chain participant in the design can observe; and the conditions under - which the guarantees degrade or fail. -09. The module undergoes an independent third-party security audit of the + off-chain participant in the design can observe; whether each can affect + safety or only liveness; and the conditions under which the guarantees + degrade or fail. +09. Document the operator role for the deployment: what running an operator + costs, at what cadence updates should be submitted, how anyone can start one + without permission, and how to detect that a deployment has stalled. State + plainly that no party is obliged to operate and that liveness rests on + interested parties choosing to spend the gas. +10. The module undergoes an independent third-party security audit of the consensus and inclusion verification logic before any mainnet-facing deployment; the audit report must be published. -10. The deliverable must be published on the module catalog. -11. The repository must use the standard Logos GitHub Actions. +11. The deliverable must be published on the module catalog. +12. The repository must use the standard Logos GitHub Actions. #### + Verification Security @@ -490,15 +610,20 @@ Use FURPS framework. Each numbered item should be a testable statement. (see Design Rationale, "The anchor: Ethereum finality via the sync committee"). +6. An update is accepted on proof validity alone and never on the submitter's + identity: any account submitting a valid proof advances the state, and any + account submitting an invalid proof is rejected. + ### Soft Requirements -1. **Standalone attestation program.** In addition to the library path - (Functionality #7), provide a LEZ program that verifies attestations and - records verified statements to a public account, so cost can be amortised +1. **Recorded-statement account.** In addition to the direct path (Functionality + #7), provide a deployment shape that evaluates a predicate and records the + resulting verified statement to a public account, so cost can be amortised when many consumers care about the same Ethereum state. It must share a - single verification core with the library path, following the pattern in + single verification core with the direct path, following the pattern in [RFP-020](./RFP-020-redstone-oracle-adaptor.md), so that the audit surface - and the cost profile stay common. + and the cost profile stay common. Document that a consumer reading such an + account trusts whoever wrote it, which the direct path does not require. 2. **Batching.** Amortise verification cost across multiple attestations over the same finalised header in a single transaction, analogous to the @@ -520,7 +645,13 @@ Use FURPS framework. Each numbered item should be a testable statement. 6. **Additional chains.** Extend the attestation to other chains with a light-client-verifiable consensus, each served by its own configuration per - Functionality #12. + Functionality #14. + +7. **Operator incentive.** Propose a mechanism that rewards whoever advances the + consensus state, so that liveness does not rest solely on interested parties + choosing to spend the gas. Any such mechanism must preserve the + permissionless property in Functionality #11: it may make operating + attractive, but must not make it exclusive. ### Out of Scope @@ -551,13 +682,6 @@ The following are explicitly excluded from this RFP: ### Hard dependencies -#### Admin authority (RFP-001) - -The Functionality requirements specify that an admin authority configures the -weak-subjectivity checkpoint, the supported chain and chain ID, and the finality -parameters. These admin-gated functions require the standardised admin authority -library from [RFP-001](./RFP-001-admin-authority-lib.md). - #### Event emission (LP-0012) Structured on-chain events let clients and off-chain components follow committee @@ -603,7 +727,7 @@ Estimated software delivery duration: **8–12 weeks**. The scope is a single primitive with no application logic, but sync-committee tracking, in-zkVM BLS12-381 verification, and the cost measurement deliverable are each substantial. This excludes the third-party audit lead time required before any -mainnet-facing deployment (Supportability #9), which is typically procured and +mainnet-facing deployment (Supportability #10), which is typically procured and scheduled separately. ## 🌍 Open Source Requirement @@ -612,21 +736,27 @@ All code must be released under the **MIT+Apache2.0 dual License**. ## Resources -- [RFP-001 — Admin Authority Library](./RFP-001-admin-authority-lib.md) - [RFP-003 — Atomic Swaps](./RFP-003-atomic-swaps.md) (trustless swap path for chains without general smart-contract expressiveness) - [RFP-020 — RedStone Off-Chain Oracle Adaptor for LEZ](./RFP-020-redstone-oracle-adaptor.md) (reference for in-program verification cost measurement, and for the shared - verification core between a library and a program deployment shape) + verification core between two consumption paths) - [RFP-022 — Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ](./RFP-022-wrapped-erc20.md) (primary consumer; the mint side depends on this attestation) - [RFP-023 — Native Gas Token Bridge for LEZ](./RFP-023-gas-token-bridge.md) (consumer; the gas-token release path depends on this attestation) +- [Appendix: Ethereum Light Client Ecosystem](../appendix/ethereum-light-client-ecosystem.md) + (production zk light clients, operator models, and the permissioned-updater + counter-example) - [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md) (bridge failure taxonomy, including verification-logic bugs) - [LP-0012: Event/Log mechanism for LEZ](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) - [Ethereum Altair light-client specification](https://github.com/ethereum/consensus-specs/tree/dev/specs/altair/light-client) - [Ethereum weak subjectivity specification](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/weak-subjectivity.md) +- [`boundless-xyz/r0vm-helios`](https://github.com/boundless-xyz/r0vm-helios) + (Boundless Ethereum light client, audited by zkSecurity; reuse candidate) +- [`succinctlabs/sp1-helios`](https://github.com/succinctlabs/sp1-helios) + (upstream implementation of the same pattern) - [RISC0 — Zero-Knowledge VM](https://github.com/risc0/risc0) - [Zisk — RISC0 Proof Generation](https://github.com/risc0/zisk) - [`fryorcraken/lez-signature-bench`](https://github.com/fryorcraken/lez-signature-bench) diff --git a/appendix/ethereum-light-client-ecosystem.md b/appendix/ethereum-light-client-ecosystem.md new file mode 100644 index 00000000..31846a6a --- /dev/null +++ b/appendix/ethereum-light-client-ecosystem.md @@ -0,0 +1,295 @@ +# Appendix: Ethereum Light Client Ecosystem + +This appendix surveys the production zk light-client implementations relevant to +[RFP-021](../RFPs/RFP-021-ethereum-state-attestation.md), a trustless Ethereum +state attestation primitive for LEZ. It exists to source one specific claim in +that RFP: that a **permissionless operator advancing shared on-chain +light-client state** is an established, audited, production pattern rather than +a novel design, and that the trust properties of that pattern are well +understood. + +The survey covers what each implementation does, who is permitted to advance the +on-chain state, what the resulting trust model is, and what a LEZ implementation +can reuse. It deliberately includes one implementation that **restricts** update +submission, because the contrast is the clearest evidence that +permissionlessness is a deployment choice rather than an automatic consequence +of using zero-knowledge proofs. + +## The pattern + +Every implementation surveyed here decomposes the problem the same way. + +Verifying that an Ethereum fact is true requires two things: proving that a +block header is a finalised header of the canonical chain, and proving that some +piece of state is included under that header. The first is expensive, involving +BLS12-381 aggregate signature verification over sync-committee signatures and +the verification of committee handoffs across sync-committee periods. The second +is comparatively cheap, being Merkle-Patricia path verification. + +The two are also asymmetric in another way. Header finality is a fact about +Ethereum that every consumer needs and no consumer needs privately. Inclusion is +specific to the consumer's own transaction. + +That asymmetry drives the architecture: + +1. An **operator** runs off-chain. It follows the beacon chain, generates a + zero-knowledge proof that a light-client finality update is validly signed by + the sync committee, and submits that proof to a contract on the destination + chain. Committee handoffs are proven the same way. +2. A **contract** on the destination chain verifies the proof and stores the + resulting verified state: the current sync committee, and finalised header + roots. The stored state accumulates and is readable by any consumer. +3. A **consumer** submits only a Merkle inclusion proof against a header already + verified in that contract. It performs no signature verification of its own. + +The operator is untrusted. It cannot insert a header the sync committee did not +sign, because the contract verifies the proof on submission; forging a header +would require forging BLS signatures from two thirds of the committee. The only +thing an operator can do is stop, which is a liveness failure rather than a +safety failure, and which is repaired by anyone else running the same operator +software. + +This is the property that makes the operator role viable in a trust-minimised +design, and it is the property RFP-021 requires in Functionality #11. + +## Implementations Surveyed + +| Implementation | zkVM / proof system | Update submission | Audit | Notes | +| ------------------------------------------- | ----------------------- | --------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- | +| Telepathy (Succinct) | Custom zkSNARK circuits | Permissionless, no access control | **Veridise** | Clearest published statement of the trust model; `step` and `rotate` are `external` with no modifiers | +| SP1 Helios (Succinct) | SP1 zkVM | Permissionless in upstream | **Zellic** | Helios light client compiled into SP1; the modern reference implementation | +| r0vm-helios (Boundless, formerly RISC Zero) | **RISC Zero zkVM** | Follows upstream | **zkSecurity** | Fork of SP1 Helios; the closest existing artefact to a LEZ port target | +| SP1 Helios (Across fork) | SP1 zkVM | **Permissioned**, `UPDATER_ROLE` | **OpenZeppelin** | Deliberate divergence; the counter-example | + +The audits named above are published: Veridise for Telepathy [10], Zellic for +upstream SP1 Helios [11], zkSecurity for r0vm-helios [4], and OpenZeppelin for +the Across fork [5]. The upstream and fork audits are separate engagements +covering different code. + +The [Axelar light client](https://github.com/commonprefix/axelar-light-client) +[8] belongs to the same family but is omitted from the table: it applies the +sync-committee protocol directly rather than through a zkVM, and its repository +does not state an update-submission policy, so it contributes no evidence either +way on the question this survey is asking. + +zkBridge [6] is adjacent but is deliberately not listed above. It follows the +same shared-state shape, an updater contract maintaining verified headers which +applications read with their own Merkle proofs, and its paper claims +permissionless header relay. It is not an Ethereum sync-committee light client, +however: the paper is generic over light-client protocols, its +Ethereum-as-source instantiation is pre-Merge longest-chain proof of work, and +Polyhedra's production deployment runs as a LayerZero DVN attesting per message +rather than as an open header store. It is prior art for the shape, not for the +anchor. + +### Telepathy + +Telepathy states the trust model explicitly, which is why it is the primary +source for the pattern rather than the most current implementation. + +An Operator queries the sync committee for the latest finalised block header and +generates a zkSNARK attesting that enough of the committee signed it, submitted +via `step`. The same Operator handles committee rotation: the sync committee +rotates roughly every 27 hours, and the Operator generates a separate proof +attesting to the correct selection of the next committee, submitted via `rotate` +[1]. + +On permissionlessness, the documentation is unambiguous: "these actors are +completely permissionless. Succinct operates their own version of these actors +so that the user experience of integrating with Telepathy painless, but as all +`LightClient` and `TelepathyRouter` update functions are permissionless (with no +access control), anyone who wishes to can run their own versions of an operator +and relayer can do so" [1]. The `step(...)` and `rotate(...)` functions are +`external` with no access control modifiers. + +The division of labour matters for RFP-021's cost analysis: the Operator bears +the proving cost of consensus verification, and a Relayer separately submits +Merkle proofs validating a message against the header root already stored in the +light client [1]. + +### SP1 Helios + +SP1 Helios is an implementation of a zk Ethereum light client using the Altair +sync committee, combining the Helios light client with the SP1 zkVM [2]. It +verifies the consensus of a source chain inside the execution environment of a +destination chain. + +The operator "keeps an on-chain SP1 Helios light client updated by proving +finalized source-chain consensus updates and submitting them to the +destination-chain SP1 Helios contract" [2]. + +Two commitment modes are relevant to RFP-021's Functionality #3, which requires +inclusion proofs for accounts, storage slots, and receipts or logs. The default +mode commits the finalised light-client state and the execution state root. An +execution-header mode additionally commits the finalised execution block hash +and the finalised execution receipts root [2]. A design that needs receipt and +log proofs requires the receipts root to be committed, which is a concrete +interface decision an applicant will face; the documentation puts the cost of +that mode at approximately 45k additional gas per successful update [2]. + +### r0vm-helios + +r0vm-helios is the implementation most directly relevant to LEZ, because LEZ +runs on RISC0. + +It is a fork of SP1 Helios that verifies source-chain consensus in the execution +environment of a destination chain, built on the RISC Zero zkVM, and it has +received an independent security audit from zkSecurity, published in the +`risc0/rz-security` repository [3][4]. + +Architecturally it matches the pattern: a consensus RPC endpoint (a beacon node +supporting the Altair light-client protocol methods), an operator that generates +proofs and maintains light-client state, and a destination-chain contract +storing verified consensus data [3]. + +Its existence is why RFP-021 directs applicants to assess reuse rather than +reimplement. An audited RISC Zero implementation of the hardest and most +security-critical component is a materially different starting point from a +blank sheet, and the RFP's Reliability #6 requirement to integrate mature +audited implementations points here. What it is **not** is a drop-in: it targets +EVM destination chains with Solidity contracts, and LEZ is neither. The port +surface, what changes and what carries over unmodified, is an assessment the +applicant must perform and justify. + +### The Across fork: where the pattern is deliberately broken + +Across Protocol maintains a fork of SP1 Helios that makes update submission +permissioned, and it is the most instructive entry in this survey. + +The contract inherits `AccessControlEnumerable` and gates the `update` function +behind an `UPDATER_ROLE`. (The repository has since been restructured and its +`main` branch no longer carries the Solidity contracts; the contract described +here lives on the `audit/march-31-2024` branch, which is what the audit covers.) +Per the OpenZeppelin audit, "the updaters set is immutable, defined at +deployment and cannot be modified afterward, meaning that no new addresses can +be added or removed post-deployment", and "Risk Labs will control the updater +role, ensuring that only trusted entities can submit updates" [5]. No address +holds `DEFAULT_ADMIN_ROLE`, so the role cannot be granted or revoked after +deployment. The audit reached that end state via a finding rather than +confirming a clean intent: code comments said the role "should be admin-less" +while a redundant `_setRoleAdmin` call and contradictory test comments muddied +it, and the superfluous call was subsequently removed [5]. + +Two conclusions follow, and both are load-bearing for RFP-021. + +**Permissionlessness is a choice, not a consequence.** A team can port an +audited zk light client faithfully and still ship a design in which one named +party is the only entity able to advance the state. Nothing about using zk +proofs prevents this. RFP-021 therefore cannot treat the property as implied by +the technology and must require it explicitly. + +**Safety-trustlessness and censorship-resistance are separable.** Even in the +Across design, a rogue updater cannot forge a header; the proof verification +stops that, and safety survives. What is lost is liveness and +censorship-resistance: if Risk Labs stops submitting, or declines to submit, +nobody else can advance the light client, and every consumer stalls. Because the +updater set is immutable, there is no recovery path short of deploying a new +contract. + +That distinction is exactly what RFP-021 asks proposals to state, and this fork +demonstrates that a design can satisfy "no trusted party can forge" while +failing "no party can block". + +## Operator economics + +The pattern raises an obvious question: if nobody is required to run an +operator, why would anyone? + +The answer visible across these deployments is that the cost of advancing the +state is small and the parties who need it advanced are identifiable and +motivated. Submitting an update is a single transaction whose cost is amortised +across every consumer reading the resulting header, and any protocol whose users +depend on fresh headers has a direct incentive to keep them fresh. Succinct runs +operators for Telepathy for user-experience reasons while leaving the role open +to anyone [1]; Across runs its own because its bridge depends on it. + +This is a weaker guarantee than a slashing-backed obligation, and it should be +stated as such: no operator is contractually bound to act. What the design +guarantees is that a stalled light client can be restarted by any party willing +to spend the gas, without permission from anyone, and without any pre-existing +relationship to the deployment. The failure mode is a delay, not a loss, and +recovery does not depend on the party that stopped. + +## Bootstrap trust and deployment multiplicity + +Sync-committee tracking cannot start from nothing. It begins from a +weak-subjectivity checkpoint, a known-good committee, and follows verified +handoffs forward from there. That checkpoint is a one-off trust input at +deployment: everything after it is verified, and nothing before it is. + +Two properties of this bootstrap are worth stating plainly, because they shape +how a deployment should be treated. + +**The checkpoint is independently verifiable.** Unlike a signer set, whose +honesty cannot be checked from outside, a configured checkpoint is a claim about +public Ethereum history that anyone can confirm against public sources before +relying on the deployment. A deployment whose checkpoint is wrong or +unverifiable is detectably so, which is why RFP-021 requires a documented +verification procedure rather than only a configured value. + +**Deployment is not exclusive.** Nothing prevents a second contract being +deployed with a different checkpoint. If a deployment's bootstrap is +mis-configured, or its checkpoint falls outside the weak-subjectivity period, +the remedy is a fresh deployment rather than a governance action over the +existing one. This is a genuine safety valve and it is the reason the primitive +does not need a mutable checkpoint under privileged control. + +It carries a cost that pulls in the opposite direction, and the tension should +be acknowledged rather than resolved by assertion. Fragmenting across +deployments splits the operator incentive, duplicates gas expenditure, and +forces every consumer to decide which contract it trusts. The value of the +shared-state architecture comes precisely from many consumers reading the same +verified headers. A canonical deployment that all consumers converge on is +therefore the intended outcome, with the ability to deploy another treated as a +recovery path rather than a routine expectation. + +## What this implies for a LEZ implementation + +Three consequences carry directly into RFP-021. + +**The cost problem changes shape.** RFP-021's central open question is whether +in-zkVM BLS12-381 verification fits a LEZ transaction budget. Under the shared +state architecture, that cost sits in the operator's submission and is amortised +across every consumer, while a consumer's own transaction contains only Merkle +verification. This does not make the BLS cost disappear, and measuring it +remains a primary deliverable, but it decouples that cost from the per-consumer +budget. + +**The interface is a stored header set, not a per-transaction proof.** A +consumer reads a verified header from shared state and proves inclusion against +it. RFP-021's requirement that verification be callable as a library, so that +verification and the action it authorises are atomic, applies to the inclusion +and predicate steps against already-verified consensus state. + +**Reuse is an assessment, not an instruction.** r0vm-helios is audited, RISC +Zero based, and solves the hardest component. Whether its guest program, its +operator, or only its architecture transfers to LEZ depends on details an +applicant is better placed to evaluate than this specification is. The RFP +points at it as a candidate and requires the assessment to be made and justified +rather than assuming the answer. + +## References + +01. [Telepathy — Off-chain Actors](https://docs.telepathy.xyz/telepathy-protocol/actors); + see also + [Telepathy — Sync Committee Protocol](https://docs.telepathy.xyz/telepathy-protocol/sync-committees) + and + [Telepathy — Smart Contracts](https://docs.telepathy.xyz/telepathy-protocol/contracts) +02. [succinctlabs/sp1-helios](https://github.com/succinctlabs/sp1-helios); see + also [SP1 Helios documentation](https://succinctlabs.github.io/sp1-helios/) +03. [boundless-xyz/r0vm-helios](https://github.com/boundless-xyz/r0vm-helios) +04. [risc0/rz-security — audits](https://github.com/risc0/rz-security/tree/main/audits) + (zkSecurity audit of r0vm-helios) +05. [OpenZeppelin — SP1 Helios Audit](https://www.openzeppelin.com/news/sp1-helios-audit); + see also + [across-protocol/sp1-helios](https://github.com/across-protocol/sp1-helios) +06. [zkBridge: Trustless Cross-chain Bridges Made Practical](https://rdi.berkeley.edu/zkp/uploads/paper.pdf) + (Berkeley RDI) +07. [a16z/helios](https://github.com/a16z/helios) (the underlying Helios light + client) +08. [commonprefix/axelar-light-client](https://github.com/commonprefix/axelar-light-client) +09. [Ethereum Altair light-client specification](https://github.com/ethereum/consensus-specs/tree/master/specs/altair/light-client) +10. [Veridise — Succinct Labs Telepathy audit, 11 March 2023](https://veridise.com/audits-archive/company/succinct/succinct-labs-telepathy-2023-03-11/) +11. Zellic — SP1 Helios audit, 18 to 29 July 2025, published as + `SP1 Helios - Zellic Audit Report.pdf` in + [succinctlabs/sp1-helios](https://github.com/succinctlabs/sp1-helios) From 70c62e2cd4b274fba84a812c895582635cf72610 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Wed, 19 Aug 2026 14:30:46 +1000 Subject: [PATCH 63/69] RFP-021: rework cost framing, instance model, and demo cases Cost section now splits by execution path: BLS12-381 is needed only for headers, which are public and executed by the sequencer, while the open question is whether hash-based inclusion verification is viable in a private transaction proven on user hardware. Drops the secp256k1 ECDSA benchmark, which measured a different primitive on a different question. Replaces Ethereum-style "deployment" wording with the account model: the program is deployed once, and the checkpoint, chain binding, finality parameters, and tracked consensus state are per-instance configuration held in accounts. Adds reference consumer programs covering an ERC-20 transfer and a native ether transfer to a specific contract. Appendix records that an attestation spans two proof systems, the SSZ binding of the execution payload over SHA256 and the Merkle-Patricia path over keccak256, and that a log is proven through its receipt. Renumbers Supportability after dropping the per-item test and README items, and fixes the cross-references that pointed at the old numbering. Co-Authored-By: Claude Opus 5 --- RFPs/RFP-021-ethereum-state-attestation.md | 386 ++++++++++---------- appendix/ethereum-light-client-ecosystem.md | 21 +- 2 files changed, 217 insertions(+), 190 deletions(-) diff --git a/RFPs/RFP-021-ethereum-state-attestation.md b/RFPs/RFP-021-ethereum-state-attestation.md index d0af795e..cd2a67de 100644 --- a/RFPs/RFP-021-ethereum-state-attestation.md +++ b/RFPs/RFP-021-ethereum-state-attestation.md @@ -48,29 +48,28 @@ Build a reusable LEZ primitive that lets any LEZ program act on a fact about Ethereum state and know that fact is true, with no trusted intermediary. A LEZ execution is self-contained: a program reads inputs from LEZ accounts and -instruction data, runs in the zkVM, and produces a proof that the execution was -correct **given those inputs**. Whether an input is a true statement about the -outside world is not something that proof covers. A program that mints against -"a deposit of amount X occurred on Ethereum" proves only that it minted given -the claim; the claim itself is uncertified, and whoever controls the input can -assert a deposit that never happened. +instruction data, and its correctness is established **given those inputs**. +Whether an input is a true statement about the outside world is not something +that execution establishes. A program that mints against "a deposit of amount X +occurred on Ethereum" establishes only that it minted given the claim; the claim +itself is uncertified, and whoever controls the input can assert a deposit that +never happened. This RFP delivers the missing piece: a LEZ module that verifies Ethereum consensus and finality, verifies inclusion of a referenced piece of state under a finalised Ethereum header, evaluates a predicate over that state, and emits a **verified statement** with no application action attached. It takes an Ethereum -header, the consensus material needed to prove that header is finalised, an -inclusion proof, and a predicate to check. It returns a proven assertion that -any LEZ program can consume. +header, the consensus material needed to prove that header is finalised, the +proofs binding the referenced state to that header, and a predicate to check. It +returns a proven assertion that any LEZ program can consume. The deliverable is deliberately application-free. Minting, escrow release, settlement, and every other action belong to the consuming program. This RFP delivers only the attestation, plus the tooling and documentation a consumer needs to integrate it. -Teams will need experience with Ethereum consensus and the light-client -protocol, Merkle-Patricia proof verification, and LEZ program development inside -the RISC0 zkVM. +Teams will need experience with Ethereum consensus, the light-client and +verified proxy protocols, and LEZ program development. ## 🔥 Why This Matters @@ -129,8 +128,8 @@ is included under a **supplied** root. Whether that supplied root is the root of the real Ethereum chain stays unchecked. A party free to choose the root can fabricate a self-consistent state in which any deposit they like appears to exist, generate a valid inclusion proof against it, and pass verification. The -zkVM proof will be sound. It will be proving a statement about a fabricated -Ethereum. +verification will pass. It will have checked a real inclusion proof against a +fabricated Ethereum. The missing ingredient is an anchor to canonical Ethereum. Verification has to establish that the header it reasons about is a header the Ethereum network @@ -162,12 +161,12 @@ An attestation therefore establishes three things, in this order: "contract C holds an escrow of amount X in token T". The output is a compact, proven assertion that the predicate holds of finalised -Ethereum state, carrying no trust in whoever generated the proof. A dishonest -prover cannot forge it, since forging it would require forging sync-committee -signatures over a finalised header. A dishonest prover can only decline to -produce a proof, which is why proof generation must be a liveness role rather -than a trust role: no single party may be able to turn a refusal into a block on -an honest user. +Ethereum state, carrying no trust in whoever generated the attestation. A +dishonest submitter cannot forge it, since forging it would require forging +sync-committee signatures over a finalised header. A dishonest submitter can +only decline to produce an attestation, which is why attestation generation must +be a liveness role rather than a trust role: no single party may be able to turn +a refusal into a block on an honest user. ### Where the tracking state lives: the permissionless operator @@ -194,26 +193,29 @@ from two thirds of the committee. It can only stop, which is a liveness failure repaired by anyone else running the same software. Nobody is obliged to run an operator, and the design does not pretend otherwise. -What makes the role viable is that the cost of one submission is small, it -amortises across every consumer reading the resulting header, and the protocols -whose users depend on fresh headers are motivated to keep them fresh. The -guarantee is not that an operator will always act; it is that a stalled -deployment can be restarted by any party willing to pay, without permission and -without any prior relationship to the deployment. The failure mode is delay, not -loss. - -Trust enters once, at deployment, through the weak-subjectivity checkpoint. That -input is independently verifiable against public Ethereum history, which is why -Functionality #9 requires a documented procedure for confirming it rather than -only a configured value. And it is recoverable: nothing prevents a second -deployment with a corrected checkpoint, so a failed bootstrap is repaired by -deploying again rather than by a privileged party mutating the existing one. - -The counterweight is that fragmenting across deployments splits the operator -incentive, duplicates gas, and forces every consumer to choose which contract to +What makes the role viable is that one submission serves every consumer reading +the resulting header, so the cost is paid once per period rather than once per +attestation, and the protocols whose users depend on fresh headers are motivated +to keep them fresh. The guarantee is not that an operator will always act; it is +that a stalled instance can be advanced by any party willing to pay, without +permission and without any prior relationship to it. The failure mode is delay, +not loss. + +Trust enters once, when an instance is initialised, through the +weak-subjectivity checkpoint. That input is independently verifiable against +public Ethereum history, which is why Functionality #9 requires that +verification be exposed as an API on the Logos Ethereum core module rather than +left as a configured value. And it is recoverable: nothing prevents initialising +a second instance with a corrected checkpoint, so a failed bootstrap is repaired +by initialising again rather than by a privileged party mutating the existing +one. + +The counterweight is that fragmenting across instances splits the operator +incentive, duplicates gas, and forces every consumer to choose which instance to trust, dissolving the shared-state benefit that motivates the architecture. A -single canonical deployment that consumers converge on is the intended outcome, -and redeployment is a recovery path rather than a routine one. +single canonical instance per chain, which consumers converge on, is the +intended outcome, and a replacement instance is a recovery path rather than a +routine one. This pattern is established rather than novel, and it has been built and audited several times over: Telepathy and SP1 Helios both implement it, and @@ -243,9 +245,8 @@ rather than buried: from a trusted checkpoint, a known-good committee, following handoffs forward from there. That initial checkpoint is a trust anchor. The design is trustless after bootstrap, given a correct starting committee, so the specification must - say how a verifier confirms the checkpoint independently, and when a - deployment that has fallen outside the weak-subjectivity period must be - replaced. + say how a verifier confirms the checkpoint independently, and when an instance + that has fallen outside the weak-subjectivity period must be replaced. Applicants may propose a stronger anchor than sync-committee tracking (full validator-set verification, or a hybrid) and are encouraged to state the cost @@ -283,7 +284,7 @@ statement carries a deterministic, collision-resistant identifier derived from the attested state itself, so a consumer can key a nullifier on it without inventing its own derivation and without two consumers deriving incompatible identifiers from the same event. Guidance on doing this correctly is a -documentation deliverable (Supportability #6). +documentation deliverable (Supportability #4). ### What the attestation does not do @@ -307,10 +308,17 @@ LEZ event natively on Ethereum, is specific to the bridge and stays in On testnet and mainnet the primitive is a deployed LEZ program with a published interface, and a consumer calls it. Source-level availability matters for local -testing, review, and reproducing the cost measurements, but it is not the -deployment model: consumers do not each compile and deploy their own copy of the -verification logic, because doing so would fragment the shared consensus state -the architecture depends on and multiply the audited surface. +testing, review, and reproducing the cost measurements, but consumers do not +each compile and deploy their own copy of the verification logic, because doing +so would fragment the shared consensus state the architecture depends on and +multiply the audited surface. + +The program is deployed once and its code is immutable. Everything that varies +between chains is configuration held in accounts owned by that program: the +weak-subjectivity checkpoint, the chain binding, the finality parameters, and +the tracked consensus state. Each such namespace of accounts is an instance, +configured when it is initialised and never reconfigured after. A consumer binds +to a specific instance by address. What has to be atomic in the consumer's transaction is the part specific to that consumer. Two things are being consumed and they differ: @@ -324,7 +332,7 @@ consumer. Two things are being consumed and they differ: transaction, against a header the consumer checks for itself, so that verification and the action it authorises cannot come apart. -A deployment shape that records evaluated statements to a public account, so +A consumption path that records evaluated statements to a public account, so that cost can be amortised when many consumers care about the same Ethereum state, is a legitimate addition and is specified as a soft requirement. Where it exists it must share a single verification core with the direct path, so the @@ -333,24 +341,42 @@ established in [RFP-020](./RFP-020-redstone-oracle-adaptor.md). ### Cost is a primary deliverable -Whether sync-committee signature verification and Merkle-Patricia proof -verification fit inside a LEZ transaction budget, and at what cost, is the -central open question of this RFP. Signature verification inside RISC0 is known -to be expensive: prototype work on in-program secp256k1 ECDSA verification -([`fryorcraken/lez-signature-bench`](https://github.com/fryorcraken/lez-signature-bench)) -showed costs high enough to foreclose some designs on LEZ, and the sync -committee signs with BLS12-381 aggregate signatures, a different and heavier -primitive. Measuring and documenting the real cost, with a breakdown by -component, is therefore a first-class deliverable and not a side report, exactly -as it was for RFP-020. Consumers cannot size their own designs without those -numbers, and if the cost turns out to be unacceptable the measurement is the -input to a follow-on RFP proposing a BLS12-381 precompile for LEZ. - -The shared-state architecture changes the shape of this problem without removing -it. Consensus verification cost sits in the operator's submission and amortises -across every consumer, while a consumer's own transaction carries only inclusion -verification. The BLS cost still has to be paid and still has to be measured; -what it no longer has to do is fit inside each consumer's budget. +Where the cost lands depends on which execution path pays it, and the two are +not alike. A public transaction is executed by the sequencer, so in-program +verification cost is a throughput concern. A private transaction is proven on +the user's own device, so the same work becomes wall-clock latency in a user +flow, on whatever hardware that user has. + +The two verification steps use different primitives, and the split follows from +that. Proving a header finalised means BLS12-381 aggregate signature +verification over sync-committee signatures, which is pairing-based and heavy. +Proving state included under that header is hashing: SHA256 for the SSZ binding +of the execution payload into the beacon body, then keccak256 down a +Merkle-Patricia path. No elliptic curve operations appear in the inclusion step +at all. + +BLS12-381 verification is needed only for headers, and a finalised Ethereum +header is public: every consumer reads it and none needs to hide it. +Sync-committee tracking therefore belongs on the public path, where the +operator's submission is periodic, latency-tolerant, shared, and executed by the +sequencer rather than proven on a user device. What has to be established there +is throughput: whether in-program BLS12-381 verification fits the +per-transaction compute budget at the cadence tracking requires. If it does not, +that measurement is the input to a follow-on RFP proposing a BLS12-381 +precompile for LEZ, reachable only from public transactions, which is where this +cost sits. + +The open question is the private path. A consumer that wants to use an +attestation privately has to prove hash-based inclusion verification on its own +hardware, and no existing measurement says whether that is viable. Hashing is +cheap per operation, but inclusion verification repeats it across the SSZ +binding and a full Merkle-Patricia path, and whether the total lands inside an +interactive budget on a user's machine is unmeasured. That answer determines +whether the primitive is usable privately at all. + +Measuring and documenting both paths, separated by where the cost is paid, is +therefore a first-class deliverable and not a side report, exactly as it was for +RFP-020. Consumers cannot size their own designs without those numbers. ### Assess reuse before rewriting @@ -382,10 +408,12 @@ Use FURPS framework. Each numbered item should be a testable statement. 02. Verify that a supplied Ethereum block header is finalised, by checking sync-committee signatures over the light-client finality update, and reject any header that is not. -03. Verify Merkle-Patricia inclusion of a referenced piece of state under a - verified finalised header: at minimum an account, a contract storage slot, - and a receipt or log. Reject any inclusion proof that does not verify - against the header's state or receipts root. +03. Verify that a referenced piece of Ethereum state is included under a header + the module has verified as finalised, covering at minimum an account, a + contract storage slot, and an event log identified by its position within a + transaction receipt. The execution state reasoned about is bound to that + finalised header, so execution roots supplied by a caller are never trusted. + Reject any claim whose inclusion does not verify. 04. Evaluate a predicate over the verified state and emit a verified statement asserting that the predicate holds of finalised Ethereum state. The predicate interface must support at least equality and inequality @@ -409,49 +437,52 @@ Use FURPS framework. Each numbered item should be a testable statement. to expose, and must not reveal the identity of the consuming LEZ account or the consuming transaction. This must hold over full event and state diffs. 09. The weak-subjectivity checkpoint, the supported chain and chain ID, and the - finality parameters are set once per deployment, at deployment. Document a - procedure by which anyone can independently verify a configured checkpoint - against public Ethereum sources before relying on the deployment. -10. A deployment that has fallen outside the weak-subjectivity period is - replaced by a fresh deployment rather than refreshed in place. Document when - a deployment must be replaced, and what a consumer must do to migrate to a - replacement. + finality parameters are written into an instance's accounts when that + instance is initialised, and no later instruction changes them. The Logos + Ethereum core module exposes an API through which anyone can independently + verify an instance's checkpoint against public Ethereum sources before + relying on it. +10. An instance that has fallen outside the weak-subjectivity period is replaced + by a freshly initialised instance rather than refreshed in place. Document + when an instance must be replaced, and what a consumer must do to migrate to + a replacement. 11. Advancing the tracked consensus state is permissionless: any party may submit a valid update, and submission carries no access control, allowlist, - role, or registration. A deployment in which one party, or a fixed set fixed - at deployment, is the only entity able to advance the state does not satisfy - this requirement. An account with no prior relationship to the deployment - can advance the state. + role, or registration. An instance in which one party, or a set fixed at + initialisation, is the only entity able to advance the state does not + satisfy this requirement. An account with no prior relationship to the + instance can advance it. 12. Proof generation and submission are liveness roles, not trust roles: no specific party may be required for an attestation to be produced, and any party declining to act must not block a user. Proposals must identify every off-chain participant the design requires, state for each whether it can affect safety or only liveness, and justify that none of them, individually or as a class, can block an attestation from eventually being produced. -13. The weak-subjectivity checkpoint is fixed at deployment and is not mutable - by any party thereafter. Recovery from a mis-configured or stale checkpoint - is by fresh deployment, per Functionality #10, not by mutation of an - existing one. +13. The program exposes no instruction that rewrites an initialised instance's + checkpoint or chain configuration, whatever the caller. Recovery from a + mis-configured or stale checkpoint is by initialising a fresh instance, per + Functionality #10, not by mutating an existing one. 14. The design must not assume Ethereum mainnet is the only target. The same - module must be deployable, unmodified, against any Ethereum-consensus chain, - mainnet or testnet, with the chain binding in Functionality #5 keeping - deployments separate. -15. Multiple independent deployments of the module can coexist, each with its - own checkpoint and chain configuration, without interfering with one - another. A consumer binds to a specific deployment and a statement from one - deployment is never accepted by a consumer bound to another. + program, unmodified, must support instances configured for any + Ethereum-consensus chain, mainnet or testnet, with the chain binding in + Functionality #5 keeping instances separate. +15. Multiple independent instances coexist under the same program, each with its + own checkpoint, chain configuration, and tracked consensus state, without + interfering with one another. A consumer binds to a specific instance, and a + statement from one instance is never accepted by a consumer bound to + another. #### Usability 1. Build the attestation functionality for consumers and operators in a Logos core module, so that different Logos ui modules can be built on it: producing an attestation, verifying one, submitting a consensus-state update, and - reading the checkpoint and chain configuration of a deployment. + reading the checkpoint and chain configuration of an instance. 2. Provide a CLI that covers producing an attestation for a given `(chain, contract, storage slot or log, predicate)` tuple, verifying one - off-chain as a dry run, submitting a consensus-state update, and reading a - deployment's configuration. The dry run must report the same typed error - codes the on-chain path returns. + off-chain as a dry run, submitting a consensus-state update, and reading an + instance's configuration. The dry run must report the same typed error codes + the on-chain path returns. 3. Any long-running off-chain component the design requires (for example a process that follows sync-committee handoffs and keeps update material available) must be provided as a **Logos module accompanied by a Logos Core @@ -465,37 +496,51 @@ Use FURPS framework. Each numbered item should be a testable statement. finalised, sync-committee signature invalid, committee handoff not verified, checkpoint stale or outside the weak-subjectivity period, inclusion proof invalid, predicate not satisfied, chain-ID mismatch, and malformed input. +6. Provide **reference consumer programs** that demonstrate the recommended + consumer pattern of Supportability #4 end to end, covering at minimum two + cases: + - **ERC-20 transfer to a specific contract.** A transfer of a given ERC-20 + token to a specified Ethereum contract address, attesting the token, + recipient, sender, and amount, whether read from state or from an event, + whichever the design prefers. + - **Native ether transfer to a specific contract.** A transfer of native ETH + to a specified Ethereum contract address, attesting recipient, sender, and + amount, whether read from state or from an event, whichever the design + prefers. #### Reliability -1. Verification is deterministic: the same inputs always yield the same verdict, - independently reproducible from the test suite. -2. Verification is read-only with respect to consumer state: a rejected - attestation consumes nothing and leaves the consumer able to retry. -3. A verified statement over a finalised header remains valid indefinitely. - Later Ethereum activity, including subsequent sync-committee rotations, must - never invalidate an attestation that was valid when produced. -4. Committee handoff tracking survives interruption: a component restarted after - an outage resumes from its last verified state without re-verifying from the - original checkpoint, and without accepting a handoff it has not verified. -5. Temporary RPC or connectivity failure on the Ethereum side leaves any - off-chain component in a recoverable state, able to resume without - duplicating work already done. -6. Proposals must integrate mature, audited implementations of BLS12-381 - signature verification, Merkle-Patricia proof verification, and the - light-client protocol rather than reimplementing cryptographic primitives - from scratch. Evaluating what existing implementations offer, and stating - what is reused, what is rewritten, and the cost and audit-surface - consequences of that split, is a scoped deliverable to be budgeted in the - proposal (see Design Rationale, "Assess reuse before rewriting"). -7. A deployment left unadvanced does not lose safety: attestations against - already-verified headers continue to verify, and a stalled deployment resumes - correctly when any party submits the outstanding updates, with no manual - repair and no gap in the verified handoff chain. -8. Concurrent submission of the same update by competing operators is handled - without corrupting tracked state: a duplicate or already-applied update is - rejected cleanly rather than double-applied. -9. CI must be green on the default branch. +01. Verification is deterministic: the same inputs always yield the same + verdict, independently reproducible from the test suite. +02. Verification is read-only with respect to consumer state: a rejected + attestation consumes nothing and leaves the consumer able to retry. +03. A verified statement over a finalised header remains valid indefinitely. + Later Ethereum activity, including subsequent sync-committee rotations, must + never invalidate an attestation that was valid when produced. +04. Committee handoff tracking survives interruption: a component restarted + after an outage resumes from its last verified state without re-verifying + from the original checkpoint, and without accepting a handoff it has not + verified. +05. Temporary RPC or connectivity failure on the Ethereum side leaves any + off-chain component in a recoverable state, able to resume without + duplicating work already done. +06. Proposals must integrate mature, audited implementations of necessary + cryptographic primitives and the light-client protocol. Evaluating what + existing implementations offer, and stating what is reused, what is + rewritten, and the cost and audit-surface consequences of that split, is a + scoped deliverable to be budgeted in the proposal (see Design Rationale, + "Assess reuse before rewriting"). +07. An instance left unadvanced does not lose safety: attestations against + already-verified headers continue to verify, and a stalled instance resumes + correctly when any party submits the outstanding updates, with no manual + repair and no gap in the verified handoff chain. +08. Concurrent submission of the same update by competing operators is handled + without corrupting tracked state: a duplicate or already-applied update is + rejected cleanly rather than double-applied. +09. Statement submissions are independent of one another, so that multiple + private transactions can submit statements in the same block, and a private + transaction can compute its resulting state before inclusion. +10. CI must be green on the default branch. #### Performance @@ -505,12 +550,10 @@ Use FURPS framework. Each numbered item should be a testable statement. proves infeasible at delivery time, the measurement in Performance #2 stands as the deliverable and the shortfall must be documented with the specific component responsible. -2. Cost measurement is a primary deliverable, not a side report. Measure and - document, with a breakdown by component: BLS12-381 aggregate signature - verification over a sync-committee update, committee handoff verification, - Merkle-Patricia inclusion proof verification for an account, a storage slot - and a log, and predicate evaluation. Report compute units, proof time, and - proof size for each, extending the measurement methodology from +2. Cost measurement is a primary deliverable. Measure and document, with a + breakdown by program action: advancing the tracked Ethereum state, and + statement verification by type of statement. Report compute units, proof + time, and proof size for each, extending the measurement methodology from [RFP-020](./RFP-020-redstone-oracle-adaptor.md). Numbers must be reproducible from the test suite. 3. Document the amortised per-attestation cost of sync-committee tracking at the @@ -519,7 +562,8 @@ Use FURPS framework. Each numbered item should be a testable statement. 4. Any proving the user's own device must perform has to be practical on the desktop hardware Basecamp runs on. Measure and document wall-clock time and peak memory on a mid-range laptop and on the lowest specification the team - declares as supported, and state that minimum explicitly. + declares as supported, and state that minimum explicitly. This includes + running the attestation in a private transaction. 5. Document end-to-end attestation latency, from the Ethereum event to a verified statement usable on LEZ, broken down by finality wait, update availability, proof generation, and on-chain verification. @@ -530,7 +574,10 @@ Use FURPS framework. Each numbered item should be a testable statement. projections over one and five years of continuous operation. 8. Document the cost delta between the in-program BLS12-381 path and a hypothetical native precompile, so the measurement can inform whether a - follow-on precompile RFP is warranted. + follow-on precompile RFP is warranted. A precompile is reachable only from + public transactions, which the comparison must state. +9. No action's gas cost scales with accumulated on-chain storage. Where a design + cannot avoid it, the proposal justifies why and documents the mitigations. #### Supportability @@ -539,42 +586,37 @@ Use FURPS framework. Each numbered item should be a testable statement. 02. End-to-end integration tests exercise attestation production and consumption against a LEZ sequencer (standalone mode) and an Ethereum test network or local fork, and are included in CI. -03. Every hard requirement in Functionality, Usability, Reliability, and - Performance has at least one corresponding test. -04. A README documents end-to-end usage: module addresses, deployment steps, - configuration of the checkpoint and chain, and step-by-step instructions for - producing and consuming an attestation via the CLI. -05. Submit a +03. Submit a [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) for the core module, covering the developer integration journey for a consuming LEZ program. -06. The consumer documentation must include a **"Recommended Consumer Pattern"** +04. The consumer documentation must include a **"Recommended Consumer Pattern"** section covering: enforcing uniqueness with a nullifier keyed on the statement identifier from Functionality #6, verifying the chain binding matches the consumer's expectation, handling each typed error code, and the recommended behaviour when an attestation cannot be produced (refuse the action, never fall back to an unverified input). -07. Submit a +05. Submit a [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) for the CLI and any operator-facing components, covering the core user and operator journeys respectively. -08. Provide a **trust assumptions document** covering: the honest sync-committee +06. Provide a **trust assumptions document** covering: the honest sync-committee supermajority assumption and the cost of the attack it admits; the weak-subjectivity checkpoint, who supplies it and how a verifier confirms it independently; what an attestation does and does not prove; what every off-chain participant in the design can observe; whether each can affect safety or only liveness; and the conditions under which the guarantees degrade or fail. -09. Document the operator role for the deployment: what running an operator - costs, at what cadence updates should be submitted, how anyone can start one - without permission, and how to detect that a deployment has stalled. State +07. Document the operator role for an instance: what running an operator costs, + at what cadence updates should be submitted, how anyone can start one + without permission, and how to detect that an instance has stalled. State plainly that no party is obliged to operate and that liveness rests on interested parties choosing to spend the gas. -10. The module undergoes an independent third-party security audit of the +08. The module undergoes an independent third-party security audit of the consensus and inclusion verification logic before any mainnet-facing deployment; the audit report must be published. -11. The deliverable must be published on the module catalog. -12. The repository must use the standard Logos GitHub Actions. +09. The deliverable must be published on the module catalog. +10. The repository must use the standard Logos GitHub Actions. #### + Verification Security @@ -582,34 +624,27 @@ Use FURPS framework. Each numbered item should be a testable statement. and inclusion proof over state that was never finalised on the canonical chain, verification must fail. This is the central adversarial test of the RFP and must be exercised explicitly, not implied by other tests. - 2. Verification must reject: a header signed by a committee that was never validly handed off from the configured checkpoint; a sync-committee signature below the required participation threshold; a valid inclusion proof against a header that is not finalised; a valid finalised header with a tampered state or receipts root; a proof replayed against a different chain ID; and a predicate asserted over state the inclusion proof does not cover. - 3. **The verification logic cannot be swapped.** No consensus or inclusion verification may be reached through a `ProgramId` held in mutable account state. Change requires deploying a new version and having consumers move to - it; document the migration mechanism and what consumers must do. - - The consumer documentation (Supportability #6) must state that the same rule - applies to consumers: a program holding this module's `ProgramId` in mutable - state lets whoever controls that pointer substitute a module that attests to - anything. - + it; document the migration mechanism and what consumers must do. The consumer + documentation (Supportability #4) must state that the same rule applies to + consumers: a program holding this module's `ProgramId` in mutable state lets + whoever controls that pointer substitute a module that attests to anything. 4. Document the failure modes that follow from a compromised or colluding sync committee, and what a consuming application can do to bound its exposure (for example, caps and freeze authorities on the consumer side, as [RFP-022](./RFP-022-wrapped-erc20.md) specifies). - 5. User-facing and developer-facing documentation must state the trustless verification model and the liveness-only role of any off-chain participant (see Design Rationale, "The anchor: Ethereum finality via the sync committee"). - 6. An update is accepted on proof validity alone and never on the submitter's identity: any account submitting a valid proof advances the state, and any account submitting an invalid proof is rejected. @@ -617,37 +652,25 @@ Use FURPS framework. Each numbered item should be a testable statement. ### Soft Requirements 1. **Recorded-statement account.** In addition to the direct path (Functionality - #7), provide a deployment shape that evaluates a predicate and records the + #7), provide a consumption path that evaluates a predicate and records the resulting verified statement to a public account, so cost can be amortised when many consumers care about the same Ethereum state. It must share a single verification core with the direct path, following the pattern in [RFP-020](./RFP-020-redstone-oracle-adaptor.md), so that the audit surface and the cost profile stay common. Document that a consumer reading such an account trusts whoever wrote it, which the direct path does not require. - 2. **Batching.** Amortise verification cost across multiple attestations over the same finalised header in a single transaction, analogous to the multi-feed batching soft requirement in RFP-020. - 3. **Historical state.** Attest to state under a header older than the currently-tracked finalised head, for example via historical summaries in the beacon state, so a consumer can prove a fact about Ethereum's past rather than only its recent finalised present. - 4. **Richer predicates.** Support predicates over multiple attested values in a single statement (for example, an account balance and a storage slot under the same header), so a consumer can express a compound condition without producing and correlating several attestations. - -5. **Pluggable proof components.** Design the proof-system components so that - future zkVM improvements, proof compression, or hardware acceleration can be - adopted without restructuring the module or its consumer interface. - -6. **Additional chains.** Extend the attestation to other chains with a - light-client-verifiable consensus, each served by its own configuration per - Functionality #14. - -7. **Operator incentive.** Propose a mechanism that rewards whoever advances the +5. **Operator incentive.** Propose a mechanism that rewards whoever advances the consensus state, so that liveness does not rest solely on interested parties choosing to spend the gas. Any such mechanism must preserve the permissionless property in Functionality #11: it may make operating @@ -663,7 +686,7 @@ The following are explicitly excluded from this RFP: other action belong to the consuming program. This RFP emits a verified statement and stops there. - **Uniqueness enforcement.** The primitive supplies the statement identifier - (Functionality #6) and the guidance (Supportability #6); the nullifier or + (Functionality #6) and the guidance (Supportability #4); the nullifier or spent-marker itself belongs to the consumer (see Design Rationale, "Uniqueness is the consumer's job, not the primitive's"). - **Hiding Ethereum-side activity.** Ethereum state is public by construction. @@ -689,14 +712,6 @@ handoffs and attestation submissions without polling every account. [LP-0012](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) is **closed** (delivered). -#### RISC0 zkVM - -The module verifies Ethereum consensus and state in-program on LEZ. Because LEZ -itself runs on RISC0, a production-ready zkVM, this is a LEZ-runtime dependency -rather than a choice the proposal makes; proposals must leverage mature RISC0 -implementations (e.g. [Zisk](https://github.com/risc0/zisk)) for LEZ-side -proving rather than building custom circuits. - #### Logos Ethereum core module Any Ethereum-side interaction, including fetching headers, update material, and @@ -712,9 +727,6 @@ Team experienced with: - BLS12-381 signature verification and aggregate signature schemes - Merkle-Patricia trie proof verification against Ethereum state and receipts roots -- Zero-knowledge proof systems and the RISC0 zkVM (guest program development, - proof generation and verification, public/private input handling, and cost - characterisation, since cost measurement is a primary deliverable) - LEZ program development and on-chain proof verification - Security auditing of consensus verification logic (fabricated-chain attacks, replay, committee-handoff attacks, checkpoint staleness) @@ -724,10 +736,10 @@ Team experienced with: ## ⏱ Timeline Expectations Estimated software delivery duration: **8–12 weeks**. The scope is a single -primitive with no application logic, but sync-committee tracking, in-zkVM +primitive with no application logic, but sync-committee tracking, in-program BLS12-381 verification, and the cost measurement deliverable are each substantial. This excludes the third-party audit lead time required before any -mainnet-facing deployment (Supportability #10), which is typically procured and +mainnet-facing deployment (Supportability #8), which is typically procured and scheduled separately. ## 🌍 Open Source Requirement @@ -759,8 +771,6 @@ All code must be released under the **MIT+Apache2.0 dual License**. (upstream implementation of the same pattern) - [RISC0 — Zero-Knowledge VM](https://github.com/risc0/risc0) - [Zisk — RISC0 Proof Generation](https://github.com/risc0/zisk) -- [`fryorcraken/lez-signature-bench`](https://github.com/fryorcraken/lez-signature-bench) - (prototype measurements of in-program signature verification cost on RISC0) ## ✏️ How to Apply diff --git a/appendix/ethereum-light-client-ecosystem.md b/appendix/ethereum-light-client-ecosystem.md index 31846a6a..3438563b 100644 --- a/appendix/ethereum-light-client-ecosystem.md +++ b/appendix/ethereum-light-client-ecosystem.md @@ -119,14 +119,31 @@ finalized source-chain consensus updates and submitting them to the destination-chain SP1 Helios contract" [2]. Two commitment modes are relevant to RFP-021's Functionality #3, which requires -inclusion proofs for accounts, storage slots, and receipts or logs. The default -mode commits the finalised light-client state and the execution state root. An +inclusion proofs for accounts, storage slots, and event logs. The default mode +commits the finalised light-client state and the execution state root. An execution-header mode additionally commits the finalised execution block hash and the finalised execution receipts root [2]. A design that needs receipt and log proofs requires the receipts root to be committed, which is a concrete interface decision an applicant will face; the documentation puts the cost of that mode at approximately 45k additional gas per successful update [2]. +An end to end attestation spans two proof systems, which is easy to miss when +scoping the work. The sync-committee protocol finalises consensus-layer beacon +headers, whereas the state and receipts roots are execution-layer fields, so the +execution payload header has to be bound into the beacon block body by an SSZ +generalised-index proof over SHA256 before any Merkle-Patricia proof over +keccak256 against those roots carries meaning. The consensus specifications +carry this as `execution_branch` on `LightClientHeader`, checked by +`is_valid_light_client_header` [9]. Implementations that commit already-verified +execution roots on chain, as SP1 Helios does, perform the SSZ half inside the +prover so that a consumer does only the Merkle-Patricia half. + +Event logs are worth a further note. A log is not a trie leaf: the receipts trie +commits whole receipts keyed by transaction index, and there is no logs root in +the block header, only a bloom filter that is a probabilistic hint rather than a +proof. Proving a log therefore means proving its receipt and reading the log out +of it by position. + ### r0vm-helios r0vm-helios is the implementation most directly relevant to LEZ, because LEZ From 559863b59bb64e1cb935b8cb0f4b6d54478fc191 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Wed, 19 Aug 2026 14:34:26 +1000 Subject: [PATCH 64/69] RFP-021: drop RISC0 and Zisk from Resources Co-Authored-By: Claude Opus 5 --- RFPs/RFP-021-ethereum-state-attestation.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/RFPs/RFP-021-ethereum-state-attestation.md b/RFPs/RFP-021-ethereum-state-attestation.md index cd2a67de..c2ccfeda 100644 --- a/RFPs/RFP-021-ethereum-state-attestation.md +++ b/RFPs/RFP-021-ethereum-state-attestation.md @@ -769,8 +769,6 @@ All code must be released under the **MIT+Apache2.0 dual License**. (Boundless Ethereum light client, audited by zkSecurity; reuse candidate) - [`succinctlabs/sp1-helios`](https://github.com/succinctlabs/sp1-helios) (upstream implementation of the same pattern) -- [RISC0 — Zero-Knowledge VM](https://github.com/risc0/risc0) -- [Zisk — RISC0 Proof Generation](https://github.com/risc0/zisk) ## ✏️ How to Apply From 2bbdd1adeffe48f85bede2a2d01d3ef6288fd694 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Wed, 19 Aug 2026 14:34:40 +1000 Subject: [PATCH 65/69] RFP-023: move to its own branch and PR Extracted so the gas token bridge can be reviewed separately from RFP-021 and RFP-022. The cross-links from RFP-021 and RFP-022 stay, and resolve once the RFP-023 branch merges back into this one. Co-Authored-By: Claude Opus 5 --- RFPs/RFP-023-gas-token-bridge.md | 915 ------------------------------- 1 file changed, 915 deletions(-) delete mode 100644 RFPs/RFP-023-gas-token-bridge.md diff --git a/RFPs/RFP-023-gas-token-bridge.md b/RFPs/RFP-023-gas-token-bridge.md deleted file mode 100644 index 51eefc71..00000000 --- a/RFPs/RFP-023-gas-token-bridge.md +++ /dev/null @@ -1,915 +0,0 @@ ---- -id: RFP-023 -title: Native Gas Token Bridge for LEZ -tier: M -status: open -category: Developer Tooling & Infrastructure -dependencies: - - id: RFP-022 - reason: Delivers the vault, mint, registry, caps and privacy construction this RFP inverts; the two bridges share their patterns and their proof-verification approach. - - id: RFP-021 - reason: The trustless Ethereum state attestation primitive is what the LEZ vault program uses to verify an ERC-20 burn really happened on Ethereum, as specified in Functionality. - - id: RFP-001 - reason: Admin authority governs the caps, the finality depth, and the chain and zone pairing, as specified in Functionality. - - id: RFP-002 - reason: Freeze authority provides the circuit breaker to halt minting and/or release if a proof-system or vault vulnerability is suspected. - - id: LP-0013 - reason: Token authority primitives are required for the LEZ vault program to escrow and release native gas token under program control. ---- - - - -# RFP-023 — Native Gas Token Bridge for LEZ - -> **Note.** This specification describes an outcome that may benefit the Logos -> ecosystem. It is a proposal rather than an instruction. Its requirements -> reflect the technical compatibility with the Logos technology stack and are -> the criteria against which proposals and milestones are evaluated. Logos makes -> no representation as to the legal or regulatory treatment of this -> specification or any implementation of it in any jurisdiction. -> -> Teams implementing it are solely responsible for (i) assessing the risks and -> implications of what they build; (ii) obtaining their own professional advice; -> and (iii) for complying with any legal and regulatory requirements that apply -> to them. Software developed under the Program is published and maintained by -> its developers, not by Logos. -> -> Anyone who chooses to deploy, host, operate or use software developed under -> the Program, whether or not they were awarded a grant under the Program, does -> so at their own risk and is solely responsible for complying with any legal or -> regulatory requirements that apply to them. See the -> [Terms & Conditions](../TERMS_AND_CONDITIONS.md). -> -> Deploying the software described in this RFP, operating any service based on -> it, or carrying on business through it may amount to regulated activity in -> some jurisdictions, including where it involves holding or managing users' -> assets or providing services to others. Whoever conducts any such activity -> does so as principal, in their own name, and is solely responsible for -> assessing its regulatory treatment, including any licensing, registration, -> sanctions or anti-money laundering obligations that may apply to them. Logos -> does not make any representation, provides any advice or assumes any -> responsibility in respect of any such determination or compliance. - -## 🧭 Overview - -Build the reverse-direction counterpart to -[RFP-022](./RFP-022-wrapped-erc20.md): a trustless, privacy-preserving bridge in -which **LEZ is the vault** and Ethereum is the minter, so a zone's native gas -token can be represented as an ERC-20 on Ethereum and acquired by someone who -holds nothing on the zone yet. - -A LEZ-side vault program escrows native gas token. Locking gas token in that -vault entitles the holder to mint the corresponding ERC-20 on Ethereum, on -cryptographic proof of the lock. Burning that ERC-20 on Ethereum entitles the -holder to release native gas token from the LEZ vault, on cryptographic proof of -the burn, verified in-program on LEZ via the attestation primitive from -[RFP-021](./RFP-021-ethereum-state-attestation.md). - -This is RFP-022's construction with the chains swapped, and it inherits that -RFP's requirements accordingly: the same trustless verification model, the same -unlinkability guarantees, the same caps and freeze authority, the same immutable -verifier preference. It is a separate deliverable because the roles invert. The -vault logic and the mint logic move to opposite chains, which makes the LEZ -program the thing holding value and the Ethereum contract the thing issuing a -representation, with a correspondingly different audit target. - -One problem is genuinely new and has no analogue in RFP-022: releasing native -gas token to a recipient who, by construction, has no gas with which to pay for -the release. This RFP resolves it with an **off-chain paymaster service**, the -third component of a deployment alongside the vault and the Ethereum contract. A -user who has burned the ERC-20 drafts the release transaction locally and -contacts the paymaster over Logos Delivery or Tor; the paymaster checks the -attestation, submits the transaction, and pays the gas. It sponsors only burns -of its own deployment's ERC-20, never learns the requester's network address, -and can decline without blocking anyone. - -Teams will need experience with zero-knowledge proof systems, privacy-preserving -protocol design, Solidity smart-contract development, and LEZ program -development. - -## 🔥 Why This Matters - -Every other LEZ application RFP assumes the user already holds gas. The -privacy-preserving DEX ([RFP-004](./RFP-004-privacy-preserving-dex.md)), the -lending protocol ([RFP-008](./RFP-008-lending-borrowing-protocol.md)), the -curated vaults ([RFP-012](./RFP-012-curated-lending-vaults.md)), the reflexive -stablecoin ([RFP-013](./RFP-013-reflexive-stablecoin-protocol.md)), the -liquidation engine ([RFP-014](./RFP-014-liquidation-auction-engine.md)), both -launchpads ([RFP-015](./RFP-015-bonding-curve-launchpad.md), -[RFP-016](./RFP-016-lbp-launchpad.md)) and token vesting -([RFP-017](./RFP-017-token-vesting.md)) all converge on the same pattern: gas is -funded by an atomic deshield from the user's own shielded balance, in a single -indivisible action, precisely so that no external funding source links the -ephemeral account to an existing identity. RFP-004 states the constraint -directly: funding the operation account from any external source, such as a CEX -withdrawal or a known wallet, creates an on-chain link and breaks the privacy -guarantee. - -That pattern is correct, and it presupposes the user already has funds on LEZ. -It says nothing about how they got there. A user arriving with nothing cannot -deshield, cannot pay for a first transaction, and cannot use any of the above. -The conventional answers, a faucet or a centralised on-ramp, are either unsuited -to production or reintroduce exactly the identity link the atomic-deshield -pattern exists to avoid. - -This RFP is the trustless entry path. Someone who holds ETH and an Ethereum -wallet can acquire native gas token by burning an ERC-20 representation, with no -custodian, no faucet operator, and no funding source that links their new LEZ -account to their Ethereum identity. It closes the loop that RFP-022 opens: -RFP-022 brings external *value* onto LEZ as wrapped assets, but a user still -needs gas to do anything with it, and wrapped USDC does not pay for a -transaction. Together the two bridges make a user's first interaction with a -zone possible without trusting anyone. - -The same mechanism serves an operational need beyond onboarding. A zone's native -gas token becomes transferable and tradeable on Ethereum, where liquidity and -tooling already exist, which gives the token a market that does not depend on -the zone having bootstrapped its own DEX first. - -## 🏗 Design Rationale - -### Inverted roles - -In RFP-022, the Ethereum contract is the vault and the LEZ program is the -minter. Here the roles swap: - -- **Outbound (LEZ to Ethereum).** A user locks native gas token in the LEZ vault - program. Proof of that lock entitles the holder to mint the corresponding - ERC-20 on Ethereum. The proof is verified natively on Ethereum, the same - problem RFP-022 solves for its burn-to-release leg. -- **Inbound (Ethereum to LEZ).** A user burns the ERC-20 on Ethereum. Proof of - that burn entitles the holder to release native gas token from the LEZ vault. - The proof is verified in-program on LEZ, consuming the attestation primitive - from [RFP-021](./RFP-021-ethereum-state-attestation.md) rather than rebuilding - Ethereum consensus and inclusion verification. - -Everything else follows RFP-022. The requirements below mirror it item for item -wherever the mirroring is exact, and say so rather than restating the reasoning. - -### Supply is demand-driven, and the ERC-20 has no privileged minter - -The ERC-20 is not a float that anyone stocks in advance. It comes into existence -only when someone locks native gas token in the LEZ vault, and it leaves -existence only when someone burns it to release that gas token. Supply tracks -demand by construction, exactly as the wrapped-token supply does in RFP-022, and -no seeding, replenishment, or market-making mechanism is required to make the -mechanism work. - -The invariant that makes this sound is that the ERC-20 has **no privileged -minter and no pre-issued supply**. Every unit in existence is backed by gas -token locked on LEZ; burning is the only way to unlock it. An admin authority, a -deployer, or any other party must have no path to mint a single unit without a -corresponding lock. This is stated as a testable requirement in Bridge Security -#5. - -That invariant is not a theoretical concern. Meter Passport's auto-wrap and -unwrap convenience feature for native gas tokens did not properly restrict -direct interaction with the wrapped ERC-20 contracts, nor verify that a matching -real value transfer had occurred, which let an attacker mint WETH and WBNB -without depositing collateral, for a direct loss of roughly $4.3M and a further -~$3.3M cascading into a dependent lending protocol (see -[Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md)). -It is the one documented cross-chain bridge hack specifically about wrapping -native gas tokens, and it is the exact failure this RFP's invariant and its -associated tests exist to foreclose. - -One consequence is worth documenting for users rather than designing against: a -newcomer can only obtain the ERC-20 if someone has already moved gas token -outward to Ethereum and made it available. That is an ordinary liquidity -property of any two-way bridge, not a protocol requirement, and the -documentation must set the expectation plainly rather than implying the bridge -manufactures gas from nothing. - -### The gas circularity - -Releasing native gas token from the LEZ vault requires a LEZ transaction, and -the recipient of that release is, in the motivating case, someone who holds no -gas token at all. If claiming the release requires the claimant to already hold -gas, the bridge does not solve the problem it exists to solve. - -The mechanism this RFP specifies is an **off-chain paymaster service**, deployed -alongside the vault and the Ethereum contract as the third component of a -deployment. A user who has burned the ERC-20 on Ethereum drafts the LEZ release -transaction locally, contacts the paymaster over an anonymising transport, and -the paymaster submits it and pays the gas. The complete deployer journey is -therefore: deploy the LEZ vault program, deploy the EVM mint and burn contract -with its dedicated ERC-20, and run the paymaster. - -The eligibility rule is what keeps this from being an open faucet, and it is -expressed entirely in terms of the proof rather than the requester. The -paymaster sponsors a transaction if and only if that transaction carries a valid -attestation of a burn of **its own deployment's** ERC-20, at or above a -configured minimum amount, whose statement identifier has not already been -sponsored. Nothing about the requester enters the decision: no account, no -allowlist, no registration, no payment relationship. Someone who has not burned -the ERC-20 cannot obtain sponsorship, and someone who has burned it once cannot -obtain it twice, because the nullifier that already exists for double-spend -protection (Functionality #14) doubles as the anti-abuse budget. The cost of -abusing the paymaster is the cost of acquiring and burning real ERC-20, which is -the same barrier that protects the vault itself. - -The paymaster is a liveness convenience, never a trust dependency. It cannot -redirect the release, because the destination is bound into the proof (Bridge -Security #2); it cannot forge or censor selectively without simply declining, -which any other paymaster instance can cover; and it holds nothing of the -user's. A deployment may run several, a user may try them in any order, and a -user who already holds gas can always submit the transaction themselves and skip -the paymaster entirely. Nothing in the protocol privileges a particular -paymaster or requires one to exist. - -#### Transport, and why it needs care - -The paymaster is contacted over **Logos Delivery**, the ecosystem-native -transport, with **Tor as a required alternative**. The alternative is not -redundancy for its own sake: Delivery's spam protection may itself require LEZ -gas for RLN, which the user by definition does not have, so a deployment that -offered only Delivery could reintroduce the very circularity this component -exists to break. Proposals must establish whether that dependency applies at -delivery time and document the finding either way; the Tor path must work -regardless, so the user always has a route that assumes nothing on LEZ. - -Transport is where the privacy of this whole construction is most easily lost. -The paymaster necessarily learns the release transaction it is asked to submit, -which names the destination account. If it also learns the requester's IP, it -can link that account to a network identity, and the unlinkability the rest of -the design works to preserve is gone at the last step, in the one place where -the user has no choice but to talk to somebody. **The paymaster must therefore -never observe or record requester IP addresses.** Both transports are chosen for -this reason (Delivery and Tor each conceal the origin), and the requirement is -not satisfied by a promise not to log: the service must be built so that the -address is not available to it in the first place, and any deployment -configuration that would expose it, such as a plain HTTP fallback or a reverse -proxy passing an originating-address header, must be absent rather than merely -discouraged. - -What the paymaster does learn is the destination account and the amount, at the -moment of submission. That is unavoidable for any party that submits on a user's -behalf, and it is why the operator's knowledge is an explicit documentation -deliverable (Supportability #9) rather than something to gloss over. It does not -link back to the Ethereum burn unless the transport leaks the requester, which -is what the IP requirement forecloses. - -#### Griefing the paymaster - -Eligibility is checked against the attestation, but *checking* it costs the -paymaster something, and on LEZ that cost may land before the check completes. -Fee reservation precedes execution and failed transactions are still charged, so -a paymaster that commits to paying before the proof is verified can be drained -by an attacker submitting well-formed garbage: each submission costs the -attacker nothing and costs the paymaster a reserved fee. This is not a -hypothetical concern about the design; it is the concrete blocker identified in -[`fryorcraken/lez-proof-vault`](https://github.com/fryorcraken/lez-proof-vault), -whose README works through why naive program-sponsored gas is unsafe under a fee -market and suggests deposit-and-reimburse as the alternative shape. - -Proposals must therefore specify how the paymaster bounds this cost, and the -choice is theirs: verifying the attestation off-chain before submitting anything -on-chain, so the paymaster spends nothing on an invalid request; a cheap -reservation-time check that rejects the bulk of garbage before the expensive -path; a deposit-and-reimburse construction where the submitter fronts the fee -and is repaid out of the release; or per-transport rate limiting that does not -require identifying the requester. Whatever is chosen must not reintroduce a -requester identity, since that would defeat the transport privacy above, and -must be measured rather than asserted (Performance #7). - -That repository is the closest prior art for the LEZ-side vault and its -proof-submission shape, and is useful reading for the ownership-versus- -authorization framing of a program-owned vault and for the claimant, submitter -and payer role split it sets out. It is prior art and not a specification: it -implements no paymaster, no transport, and no burn or mint flow, its proof is a -SHA-256 preimage standing in for a real proof system, and it documents its own -gaps (no recipient binding, no authority binding on initialisation). Proposals -should not treat it as a pattern to conform to. - -### Privacy mirrors RFP-022 exactly - -The privacy construction carries over with the chains swapped, and it carries -over in full. Each leg of each bridge has exactly one public endpoint, and it is -the Ethereum endpoint in both: - -- RFP-022 inbound: public Ethereum deposit, hidden LEZ mint destination. -- RFP-023 inbound: public Ethereum burn, hidden LEZ release destination. -- RFP-022 outbound: hidden LEZ burn, public Ethereum release recipient. -- RFP-023 outbound: hidden LEZ lock, public Ethereum mint recipient. - -Minting an ERC-20 to a public Ethereum address reveals neither more nor less -than releasing one from escrow to a public Ethereum address. The hard -requirement is therefore identical to RFP-022's, with the terms substituted: -**no information other than amount, token, and timing may enable an adversary -who observes all public state on both chains, indefinitely, and who may -themselves use the bridge, to link an Ethereum burn to the LEZ release it -funded, or a LEZ lock to the Ethereum mint it triggered.** - -The three correlation points from RFP-022, "The privacy requirement, stated -precisely," apply unchanged and proposals must address each: amounts correlate -unless transfers are restricted to fixed per-token denominations; timing -correlates unless the protocol permits and the UI encourages delay; and fee -payers correlate, which here is sharpened by the gas circularity, since the -party paying for a release is structurally more visible than a user paying their -own way. - -### Finality, caps, freeze, and pairing - -These follow RFP-022 without modification in substance: a configured finality -condition on the source chain in each direction, admin-configurable per -deployment; global and per-deployment caps as a rate limiter independent of the -freeze authority; a freeze authority exercisable independently on each half; and -a strict pairing between a specific LEZ zone and program and a specific Ethereum -contract and chain ID, so a proof valid for one pairing is never accepted for -another. A claim once valid remains valid indefinitely, since users are expected -to delay their own submissions for privacy reasons. - -## ✅ Scope of Work - -### Hard Requirements - -Use FURPS framework. Each numbered item should be a testable statement. - -#### Functionality - -01. Implement a LEZ vault program that escrows native gas token. Locking must - support the gas token being held in, and locked from, either a private or a - public LEZ account, at the holder's choice. -02. A lock must not publish, store, or otherwise reveal its Ethereum - destination. No LEZ transaction argument, event, or account-state change may - identify the address that will receive the minted ERC-20. -03. Implement an Ethereum contract that mints the ERC-20 representation on - cryptographic verification of a valid LEZ lock, verified natively on - Ethereum. Verification must require no trusted party. -04. The LEZ vault releases native gas token on cryptographic verification of a - valid ERC-20 burn on Ethereum, consuming the attestation primitive from - [RFP-021](./RFP-021-ethereum-state-attestation.md) rather than implementing - its own Ethereum consensus and inclusion verification. **Claiming that - release must not require the recipient to already hold native gas token**, - and no specific paymaster or other off-chain party may be a required - counterparty (see Design Rationale, "The gas circularity"). This must hold - end to end for a recipient account holding a zero balance. -05. **Paymaster service.** Provide an off-chain paymaster that accepts a drafted - LEZ release transaction, submits it, and pays the gas, so that a user with a - zero balance can complete a release. It must be implemented as a **Logos - module accompanied by a Logos Core headless CLI/daemon**, runnable - standalone by the deployer of a vault and contract pair. -06. The paymaster sponsors a request if and only if the transaction carries a - valid attestation of a burn of its own deployment's ERC-20, at or above a - configured minimum amount, whose statement identifier it has not already - sponsored. Eligibility must depend on no property of the requester: no - account, allowlist, registration, or payment relationship. A request - carrying no burn, a burn of a different token or deployment, a burn below - the minimum, or an already-sponsored burn is refused; a request carrying a - valid unsponsored burn is accepted regardless of who sends it. -07. The paymaster is reachable over **Logos Delivery** and over **Tor**, and a - user must be able to complete a release using either transport alone. - Proposals must establish whether Logos Delivery's spam protection requires - LEZ gas for RLN at delivery time and document the finding; the Tor path must - function regardless, so that a user holding nothing on LEZ always has a - working route. -08. **The paymaster must not observe or record requester IP addresses.** This - must hold by construction rather than by logging policy: the service must - have no configuration, deployment shape, or transport fallback through which - an originating address becomes available to it. No requester address may be - present in any log, metric, persisted record, or in-memory request context. - Document the deployment constraints that preserve this (see Privacy - Preservation #7). -09. Sponsorship is refused without revealing why in a way that identifies the - burn: refusal responses for an ineligible request, an already-sponsored - burn, and a paymaster out of funds must be indistinguishable in that - respect. -10. Nothing in the protocol may privilege a particular paymaster. A deployment - must support running several, a user must be able to select or switch - between them per operation, and a user who holds gas must be able to submit - the release themselves with no paymaster involved, including when no - paymaster is running at all. -11. The paymaster's exposure to invalid or repeated requests must be bounded, so - that an attacker submitting well-formed but ineligible requests cannot drain - it (see Design Rationale, "Griefing the paymaster"). Proposals must state - the chosen mechanism, which must not require identifying the requester. - Under a flood of ineligible requests, cost per request stays bounded and a - valid request is still served. -12. A burn on Ethereum must not publish, store, or otherwise reveal its LEZ - destination. -13. Releasing must support both a private LEZ account and a public LEZ account - as the destination, at the burner's choice. -14. Uniqueness is enforced in both directions: no lock can be minted against - twice and no burn released against twice, deterministically and under - adversarial retry. On the LEZ side this is keyed on the statement identifier - the RFP-021 attestation carries. -15. The amounts visible on Ethereum must not identify which lock or release they - correspond to. Proposals must state the mechanism chosen (fixed - denominations are the expected baseline) and its effect on anonymity-set - size. -16. A user must be able to recover every one of their own unclaimed locks and - unreleased burns from credentials they already hold, with no dependence on - any server-side index and no separately-backed-up secret generated during - the flow, on the same terms as RFP-022, "Loss of access." -17. An admin authority (per [RFP-001](./RFP-001-admin-authority-lib.md), - integrated via the [SPEL framework](https://github.com/logos-co/spel) where - applicable to the LEZ side) can configure the caps, the finality depth, and - the fee parameters per deployment. -18. Global caps, configurable by the admin authority, bound the maximum value - that can be minted or released within a rolling window, as a rate limiter - independent of the freeze authority. Cap enforcement must not require - identifying individual users. -19. The finality depth required before a lock may be minted against, and before - a burn may be released against, is configurable by the admin authority per - deployment. A change to the configured depth must not invalidate a claim - that was already valid under the previous depth. -20. A freeze authority (per [RFP-002](./RFP-002-freeze-authority-lib.md)) can - pause minting and/or release, on the Ethereum contract and the LEZ vault - program independently. -21. Each LEZ vault program deployment refers to a specific Ethereum contract - deployment on a specific chain (contract address plus chain ID), and - reciprocally each Ethereum contract deployment refers to a specific zone - instance (LEZ blockchain ID, zone ID, and program ID), with each pairing - checked as part of proof verification so a lock or burn valid for one - pairing is never accepted as valid for another. The same program and - contract design must be deployable, unmodified, against any EVM chain, - mainnet or testnet. -22. The design must let multiple entities each operate under their own - independent configuration (caps, fees, admin authority, finality depth), on - the same or different pairs of blockchain programs, with strict separation - between them: one entity's configuration must have no privileged access over - another's configuration or funds. Document how a client identifies and - switches between configurations. -23. A protocol fee may be charged on minting and on release, at a rate - configurable by the admin authority per deployment, including zero. The fee - value must not distinguish a user's transaction from others, consistent with - Functionality #15. Where the release-path mechanism reimburses a paymaster - out of the released amount, document how that reimbursement interacts with - the fixed-denomination requirement. - -#### Usability - -01. Build core functionalities for both users and admin in a Logos core module, - enabling the delivery of different Logos ui modules: locking gas token, - claiming the Ethereum mint, burning the ERC-20, claiming the LEZ release, - recovering a position from user credentials, and reading and administering - the configuration. -02. Provide a Logos mini-app, aka Logos ui module, covering both flows end to - end, position recovery, and a view showing permitted amounts, caps and - current utilisation. Also provide a UI for the admin functionality; whether - this is combined into one UI or delivered as two separate ones is left to - the applicant's choice. -03. The onboarding flow must be usable by someone who holds nothing on the zone. - The mini-app must not require a funded LEZ account to complete a release, - and must not present a step that silently assumes one. -04. Any long-running off-chain component the design requires, including the - paymaster, must be provided as a **Logos module accompanied by a Logos Core - headless CLI/daemon**, runnable standalone, supporting configurable RPC - endpoints for both chains, configurable finality depth, structured logging, - and a clean shutdown path. Document the operator journey end-to-end: - install, configure, run, monitor. -05. The client must let the user select which paymaster to contact and over - which transport, retry against another on refusal or timeout, and fall back - to self-submission when the user holds gas. A paymaster refusing or being - unreachable must produce a clear, actionable state rather than a stalled - flow. -06. Provide an IDL for the LEZ vault program using the - [SPEL framework](https://github.com/logos-co/spel). -07. The mitigations to the three correlation points in Design Rationale, - "Privacy mirrors RFP-022 exactly" (amount, timing, fee payer) must be - enabled by default. The mini-app and CLI must show a clear indicator of what - data would be leaked by the user's current choices, and default to the - recommended parameters rather than requiring the user to select them. -08. The mini-app and CLI must default to inviting the user to release into, and - lock from, a private account: the private path is the pre-selected option, - and choosing the public path requires an explicit action, consistent with - Privacy Preservation #8. -09. Documentation and UI must clearly explain what is public and what is private - at each step on both chains, and must set the expectation described in - Design Rationale, "Supply is demand-driven", that the ERC-20 is available - only to the extent someone has moved gas token outward. -10. Return clear, actionable error messages for all failure modes: invalid - amount, cap exceeded, verification failure, insufficient finality, already - claimed, and program frozen. Error messages must not reveal which lock or - burn a failed attempt referred to. - -#### Reliability - -01. Minting is atomic: a failed or rejected mint claim leaves the lock claimable - on retry and consumes nothing. -02. Release is atomic: a failed burn does not destroy the ERC-20 without - preserving the holder's entitlement to release, and a failed release leaves - that entitlement intact. -03. No lock can be minted against twice and no burn released against twice, - deterministically and under adversarial retry. -04. A valid claim remains valid indefinitely; later chain activity must never - invalidate a user's outstanding entitlement. -05. Position recovery is complete: a client restored from user credentials alone - must rediscover every claimable lock and unreleased burn, after all local - state is wiped. -06. Temporary RPC or connectivity failure on either chain leaves any off-chain - component in a recoverable state, able to resume without duplicating work - already done. -07. An interrupted user-side operation does not consume, corrupt, or expose the - user's entitlement. A paymaster that accepts a request and then fails, - crashes, or never submits must leave the user's entitlement intact and - re-submittable, to the same or another paymaster, with no state stranded on - the failed one. -08. No paymaster is required for correctness. With every paymaster offline, a - user holding gas must still be able to complete a release themselves, and a - user without gas must be left in a recoverable state rather than losing the - entitlement. Test with no paymaster reachable over either transport. -09. Proposals must integrate mature, audited proof-system implementations rather - than reimplementing zero-knowledge primitives from scratch. -10. CI must be green on the default branch. - -#### Performance - -1. Verifying a burn and releasing gas token must complete within a single LEZ - transaction at the per-transaction compute budget in force at delivery time. - Document the compute-unit cost with a breakdown by component, separating the - RFP-021 attestation verification cost from this RFP's own logic, and - extending the measurement methodology from - [RFP-020](./RFP-020-redstone-oracle-adaptor.md). -2. Document the Ethereum-side gas cost of a mint, of a burn, and of the LEZ-lock - proof verification the mint requires. -3. Any proving the user's own device must perform has to be practical on the - desktop hardware Basecamp runs on. Measure and document wall-clock time and - peak memory on a mid-range laptop and on the lowest specification the team - declares as supported, and state that minimum explicitly. -4. Document end-to-end latency in both directions, each broken down by - source-chain finality wait, proof generation, any privacy-motivated delay, - on-chain verification, and the paymaster round trip over each supported - transport, since Delivery and Tor differ materially in latency. -5. Document the compute resources (CPU, RAM, time) required to run any off-chain - component the design requires, including the paymaster. -6. Document the growth rate and on-chain storage cost of all bridge state that - accumulates with usage, with projections at 1M and 10M operations. -7. **Measure the paymaster's cost per request**, separately for an eligible - request and for each class of rejected request, and state the resulting bound - on what an attacker can force the paymaster to spend per unit of their own - cost (see Design Rationale, "Griefing the paymaster"). Document the operating - budget a paymaster needs at a stated request volume, and the behaviour when - its funds are exhausted. - -#### Supportability - -01. The LEZ vault program and the Ethereum contract are deployed and tested on a - LEZ testnet and a public Ethereum testnet respectively. -02. End-to-end integration tests exercise the full round trip in both directions - against a LEZ sequencer (standalone mode) and an Ethereum test network or - local fork, and are included in CI. One test must cover the motivating - journey end to end: a user with no LEZ account and no gas token acquires gas - and completes a first unrelated LEZ transaction. -03. Every hard requirement in Functionality, Usability, Reliability, - Performance, and Privacy Preservation has at least one corresponding test. -04. A README documents end-to-end usage: contract and program addresses, - deployment steps for both chains, and step-by-step instructions for both - directions via CLI and mini-app. -05. Submit a - [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for the core module, covering the developer integration journey for both - flows including position recovery. -06. Submit a - [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for the CLI and any operator-facing components, covering the core user and - operator journeys respectively. -07. Submit a - [doc packet](https://github.com/logos-co/logos-docs/issues/new?template=doc-packet.yml) - for the deployer journey, covering how an entity stands up its own - independently configured deployment (Functionality #22) as a complete set: - deploying the LEZ vault program, deploying the EVM mint and burn contract - with its dedicated ERC-20, and running the paymaster. The paymaster section - must cover funding it, configuring the minimum sponsored amount, exposing it - over Logos Delivery and Tor, and the deployment constraints that keep - requester addresses out of reach (Functionality #8). -08. The Ethereum contract undergoes an independent third-party smart-contract - security audit before mainnet deployment; the audit report must be - published. The audit scope must explicitly include the mint authorisation - path, given the Meter Passport precedent in Design Rationale. -09. Provide a **privacy properties document** covering: a formal statement of - Privacy Preservation #1 and #2 and the anonymity set each is measured - against; exactly what is visible on-chain at every step on both chains; what - an adversary observing all public state can and cannot infer; what every - off-chain participant can observe, with a specific section on the paymaster - stating exactly what it learns (the destination account and amount at - submission time), what it cannot learn (the requester's network address, and - the link back to the Ethereum burn), and what a malicious or compromised - paymaster could and could not do; residual leakage from timing, amount - selection, fee payment, network metadata and usage patterns, including what - each supported transport exposes; and the conditions under which the - guarantees degrade. -10. Document the anonymity-set growth model: expected set size over time at - projected volumes, the minimum below which the guarantees are considered not - to hold, and guidance for users bridging before the pool has matured. -11. The UI must let users change the targeted Ethereum RPC address and the - targeted LEZ sequencer or zone. -12. The deliverable must be published on the module catalog. -13. The repository must use the standard Logos GitHub Actions. - -#### + Bridge Security - -1. Proof verification must be independently verifiable. Both the LEZ vault - program and the Ethereum contract must reject invalid proofs, including those - with incorrect public inputs, proofs for incorrect chain state, tampered - headers, and replayed proofs. -2. A malicious party submitting on a user's behalf must not be able to redirect - funds, inflate their fee, or replay the user's submission to a different - destination: a lock and a burn must each secretly commit to the destination - on the other chain, so that the claim can only be completed by whoever holds - the seed or credentials that produced the commitment. An adversary who - observes everything public about a lock or burn, but does not hold the - originating seed, cannot construct a valid claim for a different destination. - This applies with particular force to the release path, where a paymaster is - submitting on behalf of a user who cannot submit for themselves. -3. Caps (Functionality #18) bound the maximum value at risk in any rolling - window; proposals must document recommended defaults and the reasoning. -4. The freeze authority (Functionality #20) must be exercisable independently on - each half, so either can be paused without the other being operational or - reachable. -5. **Soundness of supply.** Total supply of the ERC-20 on Ethereum must never - exceed the native gas token locked in the LEZ vault. The ERC-20 must have no - privileged minter and no pre-issued supply: every unit in existence is backed - by gas token locked on LEZ, and burning it is the only way to unlock that gas - token. Minting without a valid lock, minting twice from one lock, releasing - without a valid burn, and releasing twice from one burn must all fail, as - must any attempt to mint via an admin, deployer, or owner path, or by - interacting with the ERC-20 contract directly rather than through the bridge - entry point, since that is the documented Meter Passport failure mode (see - Design Rationale, "Supply is demand-driven, and the ERC-20 has no privileged - minter"). -6. User-facing documentation must state the trustless verification model and the - liveness-only role of any off-chain participant, including whoever submits a - release on a user's behalf. -7. **The verification logic cannot be swapped**, on the same terms as RFP-022, - Security #8: on LEZ the verifying program's image ID is fixed in the vault - program's code and never read from mutable account state; on Ethereum there - is no substitutable proxy and no admin-replaceable verifier address. A - swapped verifier here would mint the gas-token ERC-20 against a lock that - never happened, breaking the supply invariant in #5. Change requires - deploying a new version and migrating; document the mechanism and how - in-flight locks and burns are honoured across it. -8. The freeze authority stops new activity but does not by itself recover funds - already at risk or resolve locks and burns left in-flight once a - vulnerability in the verification logic is found. Proposals must specify a - failsafe strategy, constrained as in RFP-022, Security #9: any recovery must - still be claimed by the locker or burner proving their own entitlement, not - by an admin authority identifying who owns what; it must not be able to mint, - redirect, or release to any destination other than the one the proof - specifies; and it must not act on funds beyond what a specific, proven - vulnerability put at risk. If no mechanism satisfying these constraints is - achievable, the proposal must document why and what happens to affected funds - in its absence. - -#### + Privacy Preservation - -1. **Inbound unlinkability.** No signal other than amount and timing may narrow - down which LEZ release an Ethereum burn funded. Across the anonymity set - those signals leave unresolved, no correlation derivable from public state - identifies the true burn-to-release pairing better than chance. -2. **Outbound unlinkability.** No signal other than amount and timing may narrow - down which Ethereum mint a LEZ lock triggered. Across the anonymity set those - signals leave unresolved, no correlation derivable from public state - identifies the true lock-to-mint pairing better than chance. -3. No transaction argument, event, log, or account-state change on either chain - may reveal a lock's Ethereum destination or a burn's LEZ destination. This - must hold over full event and state diffs for a complete round trip. -4. Information that would connect the two legs must never leave the user's - control. Document every component that handles user data; such information - must be absent from all submitted transaction data. -5. Failure and error paths must not reveal which lock or burn was involved: a - rejected claim, a repeat claim, and a cap rejection must be indistinguishable - in that respect. -6. The client must not make any network request that reveals which lock or burn - it is acting on. Document every network call made during a privacy-sensitive - operation and justify each. -7. **The paymaster must not become a correlation signal.** Whoever pays for a - release must not thereby link the Ethereum burn to the LEZ account receiving - the gas. Concretely: the paymaster must not observe or record requester IP - addresses (Functionality #8), must not require or accept any requester - identifier, and its own on-chain footprint as fee payer must not distinguish - one sponsored release from another. Document precisely what it learns, ensure - the user can switch between paymasters and transports per operation, and - ensure that neither the paymaster's identity nor its payment narrows the - anonymity set. This is the requirement most at risk from the gas circularity, - since it is the one point where the user must talk to somebody, and must be - treated as a primary design constraint rather than a late mitigation. -8. The default configuration must be the private one. No user action may be - required to obtain the privacy guarantees, and any override that weakens them - must require explicit confirmation. - -### Soft Requirements - -1. **Hidden amounts.** Remove the amount-visibility constraint entirely by - concealing transferred values on the LEZ side, rather than relying on a fixed - set of permitted amounts. Whatever is delivered under the hard requirements - should be designed so this can be adopted later without redeploying the - Ethereum contract or resetting accumulated anonymity; document the intended - migration path even if it is not implemented. - -2. **Batching.** Amortise verification cost across multiple operations in a - single transaction, analogous to the batching soft requirement in - [RFP-020](./RFP-020-redstone-oracle-adaptor.md). - -3. **Shared components with RFP-022.** Where the two bridges genuinely share - logic (fixed-denomination handling, position recovery, submission paths, the - privacy test harness), factor it so both can consume one implementation - rather than maintaining two divergent copies. Document what is shared and - what is necessarily distinct. - -4. **Optional viewing keys** allowing a user to *voluntarily* disclose their own - bridge activity to a chosen third party, without weakening privacy for anyone - else and without any protocol-level disclosure capability. - -5. **Additional EVM chains**, each served by its own deployment per - Functionality #21 (one program per chain ID, not one program juggling several - chains internally). - -6. **Generalisation beyond the gas token.** If the design generalises at no - material cost to other LEZ-native assets, so that a LEZ-native token other - than the gas token can be represented on Ethereum by the same mechanism, - deliver or document that generalisation. This is explicitly not required: the - gas token is the motivating case and a design specialised to it is - acceptable. - -7. **Pluggable proof components**, so that future zkVM improvements, proof - compression, or hardware acceleration can be adopted without restructuring - the vault or the contract. - -### Out of Scope - -The following are explicitly excluded from this RFP: - -- **Wrapping external ERC-20s and ETH into LEZ.** That is the primary flow, - owned by [RFP-022](./RFP-022-wrapped-erc20.md). This RFP inverts the - direction, it does not duplicate the primary flow. -- **The Ethereum state attestation primitive.** Verifying Ethereum consensus, - finality, and state inclusion is owned by - [RFP-021](./RFP-021-ethereum-state-attestation.md). This RFP consumes that - primitive, it does not define or rebuild it. -- **Seeding, replenishment, or market-making for the ERC-20.** Supply is - demand-driven by construction (see Design Rationale); there is no float to - stock and no incentive mechanism to design. -- **Fiat on-ramps, faucets, and centralised distribution** of the gas token. - This RFP delivers a trustless path for a user who already holds assets on - Ethereum; it does not address a user who holds nothing anywhere. -- **Building new anonymising network infrastructure.** The paymaster must be - reachable over Logos Delivery and Tor and must not observe requester addresses - (Functionality #7, #8), but this RFP integrates existing transports rather - than designing a mixnet or hardening the transports themselves. Residual - network-level leakage outside the paymaster path, such as which Ethereum RPC - or LEZ sequencer a user's client contacts, stays an implementation concern and - must be disclosed under Supportability #9 rather than solved here. -- **Protocol-level compliance, disclosure, or selective-deanonymisation - mechanisms.** Voluntary user-held viewing keys are Soft Requirement #4; any - capability allowing a third party to deanonymise a user without their consent - is contrary to the design and out of scope. -- **Circuit optimisation or custom zkVM accelerators for the LEZ side.** LEZ - runs on RISC0, so proposals should leverage mature existing implementations - rather than implementing novel circuits. - -## ⚠ Platform Dependencies - -### Hard dependencies - -#### Wrapped ERC-20 and Ether bridge (RFP-022) - -This RFP is the reverse-direction counterpart of -[RFP-022](./RFP-022-wrapped-erc20.md) and inherits its vault and mint patterns, -its trust model, its privacy construction, and its approach to caps, freeze -authority, finality and position recovery. RFP-022 establishes those patterns -and carries the reasoning behind them; this RFP applies them with the chains -swapped and does not restate them. Delivering this RFP against a materially -different set of patterns would fragment the two bridges for no benefit, so -RFP-022 is treated as a hard dependency rather than a reference. - -#### Ethereum state attestation (RFP-021) - -The inbound leg releases gas token only against an ERC-20 burn proven to have -been finalised on Ethereum, with no signer or federation trusted to attest to it -(Functionality #4). That verification is delivered as a shared primitive by -[RFP-021](./RFP-021-ethereum-state-attestation.md). This RFP consumes it and -does not rebuild it. The outbound leg, verifying a LEZ lock natively on -Ethereum, is specific to this bridge and remains in scope here. - -#### Admin authority (RFP-001) - -The Functionality requirements specify that an admin authority configures caps, -finality depth, and fee parameters. These admin-gated functions require the -standardised admin authority library from -[RFP-001](./RFP-001-admin-authority-lib.md). - -#### Freeze authority (RFP-002) - -The Bridge Security requirements specify a freeze authority able to pause -minting and/or release as a circuit breaker independent of the caps. This -requires the standardised freeze authority library from -[RFP-002](./RFP-002-freeze-authority-lib.md). - -#### Token authorities (LP-0013) - -The LEZ vault program escrows and releases native gas token under program -control. This requires the token authority primitives in -[LP-0013](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md), -which is **closed** (delivered). - -#### Logos Delivery - -The paymaster is reachable over Logos Delivery as its ecosystem-native transport -(Functionality #7). Tor is a required alternative and the release path must work -over Tor alone, so Delivery being unavailable never blocks a user. Proposals -must establish whether Delivery's RLN spam protection requires LEZ gas at -delivery time, since a user in the motivating case has none, and document the -finding either way. Following [RFP-003](./RFP-003-atomic-swaps.md), the -application must handle Delivery being temporarily unreachable gracefully and -must not depend on it to complete an operation already in progress. - -#### Logos Ethereum core module - -The Ethereum side must use the Logos Ethereum core module, including its -verified proxy features. - -#### Wallet SDK - -The UI must use the wallet SDK from the Lambda Prize wallet-SDK work. - -#### RISC0 zkVM - -The bridge verifies proofs in-program on LEZ. Because LEZ itself runs on RISC0, -this is a LEZ-runtime dependency rather than a choice the proposal makes; -proposals must leverage mature RISC0 implementations (e.g. -[Zisk](https://github.com/risc0/zisk)) rather than building custom circuits. - -#### Event emission (LP-0012) - -Structured on-chain events allow clients and off-chain components to react -without polling every account. -[LP-0012](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) -is **closed** (delivered). - -## 👤 Recommended Team Profile - -Team experienced with: - -- Zero-knowledge proof systems and RISC0 zkVM (guest program development, proof - generation and verification, public/private input handling) -- Privacy-preserving protocol design, including anonymity-set analysis and the - ability to reason rigorously about what public state does and does not reveal -- Solidity smart-contract development, including experience preparing a contract - for third-party security audit, and particular care around mint authorisation - paths -- Cryptographic primitives (Merkle proofs, consensus verification, state root - inclusion proofs) -- LEZ program development, private-state programs, and on-chain proof - verification -- Fee abstraction, paymaster or relayer design, or account-abstraction style - sponsored transactions, given the gas circularity this RFP has to solve -- Anonymising transports (Tor hidden services, mixnets, Logos Delivery) and - building services that are structurally unable to observe client network - addresses -- Smart-contract security auditing (proof validation, replay attacks, reorg - handling, cap bypass, unauthorised mint paths, privacy-leak analysis) -- Cross-chain system design and integration testing - -## ⏱ Timeline Expectations - -Estimated software delivery duration: **10–14 weeks**. The construction mirrors -[RFP-022](./RFP-022-wrapped-erc20.md) and consumes -[RFP-021](./RFP-021-ethereum-state-attestation.md) for the Ethereum-reading -half, so the patterns and much of the tooling are established rather than -invented here. The new work is the LEZ-side vault, the Ethereum-side mintable -ERC-20 with its authorisation path, and the gasless release mechanism, which is -the largest unknown. This excludes the third-party audit lead time required -before mainnet deployment (Supportability #8), which is typically procured and -scheduled separately. - -## 🌍 Open Source Requirement - -All code must be released under the **MIT+Apache2.0 dual License**. - -## Resources - -- [RFP-001 — Admin Authority Library](./RFP-001-admin-authority-lib.md) -- [RFP-002 — Freeze Authority Library](./RFP-002-freeze-authority-lib.md) -- [RFP-004 — Privacy-Preserving DEX](./RFP-004-privacy-preserving-dex.md) - (states the atomic-deshield gas pattern that presupposes an already-funded - user) -- [RFP-008 — Lending & Borrowing Protocol](./RFP-008-lending-borrowing-protocol.md) - (same atomic-deshield assumption) -- [RFP-020 — RedStone Off-Chain Oracle Adaptor for LEZ](./RFP-020-redstone-oracle-adaptor.md) - (reference for in-program proof verification cost measurement) -- [RFP-022 — Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ](./RFP-022-wrapped-erc20.md) - (the primary flow this RFP inverts) -- [RFP-021 — Trustless Ethereum State Attestation for LEZ](./RFP-021-ethereum-state-attestation.md) - (delivers the verification of finalised Ethereum state the release path - consumes) -- [RFP-003 — Atomic Swaps](./RFP-003-atomic-swaps.md) (precedent for using Logos - Delivery for coordination without depending on it for completion) -- [Appendix: Bridges and Wrapped Tokens](../appendix/bridges-and-wrapped-tokens.md) - (bridge failure taxonomy, including the Meter Passport native-gas-token mint) -- [`fryorcraken/lez-proof-vault`](https://github.com/fryorcraken/lez-proof-vault) - (prior art for a program-owned LEZ vault releasing on proof; documents the - reserve-before-verify griefing problem for sponsored gas) -- [LP-0012: Event/Log mechanism for LEZ](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0012.md) -- [LP-0013: Token program improvements: authorities](https://github.com/logos-co/lambda-prize/blob/main/prizes/LP-0013.md) -- [RISC0 — Zero-Knowledge VM](https://github.com/risc0/risc0) -- [Zisk — RISC0 Proof Generation](https://github.com/risc0/zisk) - -## ✏️ How to Apply - -👉 Submit a proposal using the Issue form: - -**[Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml)** - -We typically respond within **14 days**. For clarification questions, please use -**Discussions**. From 9cd45210378c2f4e5f263d2ee3b53c7ba5ff87b0 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Wed, 19 Aug 2026 14:35:36 +1000 Subject: [PATCH 66/69] RFP-023: drop from the proposal template dropdown Moves with the RFP to its own branch. Co-Authored-By: Claude Opus 5 --- .github/ISSUE_TEMPLATE/proposal.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/proposal.yml b/.github/ISSUE_TEMPLATE/proposal.yml index c1d3fa28..02306ca4 100644 --- a/.github/ISSUE_TEMPLATE/proposal.yml +++ b/.github/ISSUE_TEMPLATE/proposal.yml @@ -16,7 +16,6 @@ body: - "RFP-017 — Privacy-Preserving Token Vesting" - "RFP-021 — Trustless Ethereum State Attestation for LEZ" - "RFP-022 — Wrapped ERC-20 Bridge for LEZ" - - "RFP-023 — Native Gas Token Bridge for LEZ" validations: required: true From 29770847b023c73f8a330671eb89733ef9235e8a Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Thu, 27 Aug 2026 13:53:31 +1000 Subject: [PATCH 67/69] RFP-021: verify the light client on-chain, drop the off-chain prover LEZ execution is already proven, so wrapping the sync-committee check in a second proof for LEZ to verify adds a translation step and its own audit surface without strengthening the guarantee. Verify the aggregate in the program instead, and reframe the operator as a submitter that supplies update material rather than one that proves anything. Merge the light-client requirements into one item and leave the verification path to the applicant. Switch performance terminology to cycle count, and report gas alongside it for 0.3. Specify the update-submitting component as a deliverable, with lazy push so the fastest party does not pay for every update. Co-Authored-By: Claude Opus 5 (1M context) --- RFPs/RFP-021-ethereum-state-attestation.md | 225 ++++++++++++--------- 1 file changed, 130 insertions(+), 95 deletions(-) diff --git a/RFPs/RFP-021-ethereum-state-attestation.md b/RFPs/RFP-021-ethereum-state-attestation.md index c2ccfeda..92300322 100644 --- a/RFPs/RFP-021-ethereum-state-attestation.md +++ b/RFPs/RFP-021-ethereum-state-attestation.md @@ -161,42 +161,62 @@ An attestation therefore establishes three things, in this order: "contract C holds an escrow of amount X in token T". The output is a compact, proven assertion that the predicate holds of finalised -Ethereum state, carrying no trust in whoever generated the attestation. A -dishonest submitter cannot forge it, since forging it would require forging -sync-committee signatures over a finalised header. A dishonest submitter can -only decline to produce an attestation, which is why attestation generation must -be a liveness role rather than a trust role: no single party may be able to turn -a refusal into a block on an honest user. +Ethereum state, carrying no trust in whoever supplied the inputs. A dishonest +submitter cannot forge it, since the module checks the sync-committee signature +itself and forging one would require signatures from two thirds of the +committee. A dishonest submitter can only decline to supply update material, +which is why supplying it must be a liveness role rather than a trust role: no +single party may be able to turn a refusal into a block on an honest user. -### Where the tracking state lives: the permissionless operator +### Where the tracking state lives: the permissionless submitter -Two costs sit inside an attestation and they are not alike. Proving a header is -finalised requires BLS12-381 aggregate signature verification over +Two costs sit inside an attestation and they are not alike. Establishing that a +header is finalised requires BLS12-381 aggregate signature verification over sync-committee signatures plus verification of committee handoffs, and it is -expensive. Proving a piece of state is included under that header is +expensive. Establishing that a piece of state is included under that header is Merkle-Patricia path verification, and it is cheap. Header finality is also a fact every consumer needs and no consumer needs privately, whereas inclusion is specific to the consumer's own transaction. -The expected design follows that asymmetry. An **operator** runs off-chain, -follows sync-committee handoffs, generates a proof that a light-client finality -update is validly signed, and submits it to LEZ, where a module account -accumulates the verified committee and finalised header roots. A **consumer** -then submits only an inclusion proof against a header already verified in that -shared state, performing no signature verification of its own. - -**The operator must be permissionless.** Anyone can spend the gas and advance -the state; no party is designated, and none can be excluded. The operator is -untrusted because submission is proof-checked: it cannot insert a header the +The expected design follows that asymmetry. A **light client runs inside the LEZ +program itself**: the module verifies the sync-committee signature and the +committee handoff on-chain, and a module account accumulates the verified +committee and finalised header roots. A **consumer** then submits only an +inclusion proof against a header already verified in that shared state, +performing no signature verification of its own. + +Verification happens in the program, not off-chain. A submitter supplies the +light-client update material fetched from an Ethereum consensus endpoint, and +the module checks it. This RFP does not ask for a separate off-chain proving +system that wraps the signature check in a proof for LEZ to verify: LEZ +execution is already proven, so a second proof layer over the same check would +add a translation step and its own audit surface without strengthening the +guarantee. The sync-committee aggregate is used as it is. + +**Submission must be permissionless.** Anyone can spend the gas and advance the +state; no party is designated, and none can be excluded. The submitter is +untrusted because the module verifies the update: it cannot insert a header the sync committee did not sign, since doing so would require forging signatures from two thirds of the committee. It can only stop, which is a liveness failure -repaired by anyone else running the same software. +repaired by anyone else running the same software. Nothing about the role +requires the submitter to be an Ethereum validator or to have any standing on +Ethereum; it needs only access to a consensus endpoint and LEZ gas. + +Permissionless submission creates a coordination problem worth designing for. If +every operator submits the moment an update becomes available, the party with +the lowest latency wins every race and pays for every update, while the others +pay for rejected transactions and get the result for free. The rational response +is to stop running one, and the role collapses precisely because it is contested +and unrewarded. The submitting component therefore has to check whether an +update is still needed before spending gas on it, and vary its timing so the +cost lands on different operators across updates rather than always the same +one. -Nobody is obliged to run an operator, and the design does not pretend otherwise. +Nobody is obliged to submit updates, and the design does not pretend otherwise. What makes the role viable is that one submission serves every consumer reading the resulting header, so the cost is paid once per period rather than once per attestation, and the protocols whose users depend on fresh headers are motivated -to keep them fresh. The guarantee is not that an operator will always act; it is +to keep them fresh. The guarantee is not that a submitter will always act; it is that a stalled instance can be advanced by any party willing to pay, without permission and without any prior relationship to it. The failure mode is delay, not loss. @@ -217,17 +237,19 @@ single canonical instance per chain, which consumers converge on, is the intended outcome, and a replacement instance is a recovery path rather than a routine one. -This pattern is established rather than novel, and it has been built and audited -several times over: Telepathy and SP1 Helios both implement it, and -`r0vm-helios` implements it on the RISC Zero zkVM. Telepathy was audited by -Veridise, SP1 Helios by Zellic, and `r0vm-helios` by zkSecurity. Applicants -should assess reuse rather than assume a rewrite, per the Design Rationale note -below. The +Sync-committee tracking itself is established rather than novel, and has been +built and audited several times over: Telepathy, SP1 Helios, and `r0vm-helios` +all implement it, audited by Veridise, Zellic, and zkSecurity respectively. +Those systems target destination chains that cannot verify a sync-committee +signature affordably, so they prove the check off-chain and verify a succinct +proof on the destination. LEZ does not have that constraint, so what transfers +here is the light-client logic rather than the outer proving layer. Applicants +should assess reuse on that basis, per the Design Rationale note below. The [Ethereum Light Client Ecosystem appendix](../appendix/ethereum-light-client-ecosystem.md) surveys these implementations, their trust models, and a production fork that deliberately made submission permissioned, which is direct evidence that -permissionlessness is a design choice rather than a property zk proofs confer -automatically. +permissionlessness is a design choice rather than a property these systems +confer automatically. ### Trust assumptions the design carries @@ -324,10 +346,10 @@ What has to be atomic in the consumer's transaction is the part specific to that consumer. Two things are being consumed and they differ: - **Verified consensus state**, the tracked committee and the finalised header - roots, is necessarily shared and necessarily written by an operator. That is - the point of the architecture, and it is safe because submission is - proof-checked: the consumer's trust rests on the verification the module - performed on submission, not on the operator's honesty. + roots, is necessarily shared and necessarily written by an earlier + transaction. That is the point of the architecture, and it is safe because the + module verified the update when it was submitted: the consumer's trust rests + on that verification, not on the submitter's honesty. - **Inclusion and predicate evaluation** must occur inside the consumer's own transaction, against a header the consumer checks for itself, so that verification and the action it authorises cannot come apart. @@ -348,30 +370,27 @@ the user's own device, so the same work becomes wall-clock latency in a user flow, on whatever hardware that user has. The two verification steps use different primitives, and the split follows from -that. Proving a header finalised means BLS12-381 aggregate signature -verification over sync-committee signatures, which is pairing-based and heavy. -Proving state included under that header is hashing: SHA256 for the SSZ binding -of the execution payload into the beacon body, then keccak256 down a -Merkle-Patricia path. No elliptic curve operations appear in the inclusion step -at all. +that. Establishing that a header is finalised means BLS12-381 aggregate +signature verification, which is pairing-based and heavy. Establishing that +state is included under that header is hashing down an SSZ and Merkle-Patricia +path, with no elliptic curve operations at all. BLS12-381 verification is needed only for headers, and a finalised Ethereum header is public: every consumer reads it and none needs to hide it. -Sync-committee tracking therefore belongs on the public path, where the -operator's submission is periodic, latency-tolerant, shared, and executed by the -sequencer rather than proven on a user device. What has to be established there -is throughput: whether in-program BLS12-381 verification fits the -per-transaction compute budget at the cadence tracking requires. If it does not, -that measurement is the input to a follow-on RFP proposing a BLS12-381 -precompile for LEZ, reachable only from public transactions, which is where this -cost sits. +Sync-committee tracking therefore belongs on the public path, where submission +is periodic, latency-tolerant, shared, and executed by the sequencer rather than +proven on a user device. What has to be established there is throughput: whether +in-program BLS12-381 verification fits the per-transaction cycle budget at the +cadence tracking requires. This is the central feasibility question of the RFP. +If it does not fit, that measurement is the input to a follow-on RFP proposing a +BLS12-381 precompile for LEZ, reachable only from public transactions, which is +where this cost sits. The open question is the private path. A consumer that wants to use an -attestation privately has to prove hash-based inclusion verification on its own -hardware, and no existing measurement says whether that is viable. Hashing is -cheap per operation, but inclusion verification repeats it across the SSZ -binding and a full Merkle-Patricia path, and whether the total lands inside an -interactive budget on a user's machine is unmeasured. That answer determines +attestation privately has to prove inclusion verification on its own hardware, +and no existing measurement says whether that is viable. Hashing is cheap per +operation but repeats across the whole path, and whether the total lands inside +an interactive budget on a user's machine is unmeasured. That answer determines whether the primitive is usable privately at all. Measuring and documenting both paths, separated by where the cost is paid, is @@ -382,16 +401,17 @@ RFP-020. Consumers cannot size their own designs without those numbers. [`r0vm-helios`](https://github.com/boundless-xyz/r0vm-helios) is an Ethereum light client built on the RISC Zero zkVM, forked from SP1 Helios and -independently audited by zkSecurity. It solves the hardest and most -security-critical component of this RFP on the same zkVM LEZ runs on, which -makes it a materially different starting point from a blank sheet. +independently audited by zkSecurity. It implements the light-client logic this +RFP needs on the same zkVM LEZ runs on, which makes it a materially different +starting point from a blank sheet, as does Helios itself upstream. It is not a drop-in. It targets EVM destination chains with Solidity contracts, -and LEZ is neither. How much transfers, whether the guest program, the operator, -or only the architecture, is a judgement the applicant is better placed to make -than this specification. That evaluation is itself work, and Reliability #6 -scopes it as a deliverable. Reuse is expected to be assessed seriously; it is -not mandated. +and LEZ is neither, and its off-chain proving layer is not needed here. How much +transfers, and whether the better base is one of these zkVM forks or the +upstream light-client implementations they derive from, is a judgement the +applicant is better placed to make than this specification. That evaluation is +itself work, and Reliability #6 scopes it as a deliverable. Reuse is expected to +be assessed seriously; it is not mandated. ## ✅ Scope of Work @@ -401,13 +421,13 @@ Use FURPS framework. Each numbered item should be a testable statement. #### Functionality -01. Implement sync-committee tracking: given a trusted starting checkpoint, - verify light-client updates and committee handoffs so the module can follow - the canonical finalised chain forward across sync-committee periods without - running a full node. -02. Verify that a supplied Ethereum block header is finalised, by checking - sync-committee signatures over the light-client finality update, and reject - any header that is not. +01. Run the Ethereum light client inside the LEZ program: given a trusted + starting checkpoint, the module verifies light-client updates and committee + handoffs against material supplied by the submitter, and follows the + canonical finalised chain forward without running a full node. No off-chain + proving system stands between the sync committee and the module. +02. Verify that a supplied Ethereum block header is finalised, and reject any + header that is not. 03. Verify that a referenced piece of Ethereum state is included under a header the module has verified as finalised, covering at minimum an account, a contract storage slot, and an event log identified by its position within a @@ -452,12 +472,13 @@ Use FURPS framework. Each numbered item should be a testable statement. initialisation, is the only entity able to advance the state does not satisfy this requirement. An account with no prior relationship to the instance can advance it. -12. Proof generation and submission are liveness roles, not trust roles: no - specific party may be required for an attestation to be produced, and any - party declining to act must not block a user. Proposals must identify every - off-chain participant the design requires, state for each whether it can - affect safety or only liveness, and justify that none of them, individually - or as a class, can block an attestation from eventually being produced. +12. Supplying update material and submitting it are liveness roles, not trust + roles: no specific party may be required for an attestation to be produced, + and any party declining to act must not block a user. Proposals must + identify every off-chain participant the design requires, state for each + whether it can affect safety or only liveness, and justify that none of + them, individually or as a class, can block an attestation from eventually + being produced. 13. The program exposes no instruction that rewrites an initialised instance's checkpoint or chain configuration, whatever the caller. Recovery from a mis-configured or stale checkpoint is by initialising a fresh instance, per @@ -483,13 +504,13 @@ Use FURPS framework. Each numbered item should be a testable statement. off-chain as a dry run, submitting a consensus-state update, and reading an instance's configuration. The dry run must report the same typed error codes the on-chain path returns. -3. Any long-running off-chain component the design requires (for example a - process that follows sync-committee handoffs and keeps update material - available) must be provided as a **Logos module accompanied by a Logos Core - headless CLI/daemon**, runnable standalone, supporting configurable Ethereum - consensus and execution RPC endpoints, structured logging, and a clean - shutdown path. Document the operator journey end-to-end: install, configure, - run, monitor. +3. Deliver the **update-submitting component**: a process that follows Ethereum + through the Logos Ethereum core module, detects when the tracked instance is + behind, and submits the outstanding light-client updates to LEZ. It must be + provided as a **Logos module accompanied by a Logos Core headless + CLI/daemon**, runnable standalone, supporting configurable Ethereum consensus + and execution RPC endpoints, structured logging, and a clean shutdown path. + Document the operator journey end-to-end: install, configure, run, monitor. 4. Provide an IDL for the LEZ-side module using the [SPEL framework](https://github.com/logos-co/spel). 5. Return clear, actionable error messages for all failure modes: header not @@ -537,25 +558,36 @@ Use FURPS framework. Each numbered item should be a testable statement. 08. Concurrent submission of the same update by competing operators is handled without corrupting tracked state: a duplicate or already-applied update is rejected cleanly rather than double-applied. -09. Statement submissions are independent of one another, so that multiple +09. The update-submitting component checks whether an update is still needed + immediately before submitting, and does not submit one another party has + already applied. Running several instances against the same LEZ instance + must not multiply the gas spent on a given update beyond what contention + makes unavoidable. +10. Submission timing must not systematically concentrate cost on whichever + party reacts fastest. The component defers submission by an interval it + varies per instance, so that over many updates the gas cost is spread across + the operators running it rather than always falling on the same one, while + still submitting promptly once the deferral elapses and no other party has + acted. Document the deferral strategy and its effect on update latency. +11. Statement submissions are independent of one another, so that multiple private transactions can submit statements in the same block, and a private transaction can compute its resulting state before inclusion. -10. CI must be green on the default branch. +12. CI must be green on the default branch. #### Performance 1. Verifying an attestation and evaluating its predicate must complete within a - single LEZ transaction at the per-transaction compute budget in force at + single LEZ transaction at the per-transaction cycle budget in force at delivery time, in the direct consumption path of Functionality #7. If this proves infeasible at delivery time, the measurement in Performance #2 stands as the deliverable and the shortfall must be documented with the specific component responsible. 2. Cost measurement is a primary deliverable. Measure and document, with a breakdown by program action: advancing the tracked Ethereum state, and - statement verification by type of statement. Report compute units, proof - time, and proof size for each, extending the measurement methodology from - [RFP-020](./RFP-020-redstone-oracle-adaptor.md). Numbers must be reproducible - from the test suite. + statement verification by type of statement. Report cycle count, gas cost, + proof time, and proof size for each, extending the measurement methodology + from [RFP-020](./RFP-020-redstone-oracle-adaptor.md). Numbers must be + reproducible from the test suite. 3. Document the amortised per-attestation cost of sync-committee tracking at the recommended operating cadence, separately from the per-attestation verification cost, since the two amortise differently across consumers. @@ -566,18 +598,19 @@ Use FURPS framework. Each numbered item should be a testable statement. running the attestation in a private transaction. 5. Document end-to-end attestation latency, from the Ethereum event to a verified statement usable on LEZ, broken down by finality wait, update - availability, proof generation, and on-chain verification. + availability, and on-chain verification. 6. Document the compute resources (CPU, RAM, time) required to run any off-chain component the design requires. 7. Document the growth rate and on-chain storage cost of any module state that accumulates with usage, in particular committee-tracking state, with projections over one and five years of continuous operation. -8. Document the cost delta between the in-program BLS12-381 path and a +8. Document the cycle-count delta between the in-program BLS12-381 path and a hypothetical native precompile, so the measurement can inform whether a follow-on precompile RFP is warranted. A precompile is reachable only from public transactions, which the comparison must state. -9. No action's gas cost scales with accumulated on-chain storage. Where a design - cannot avoid it, the proposal justifies why and documents the mitigations. +9. No action's cycle count or gas cost scales with accumulated on-chain storage. + Where a design cannot avoid it, the proposal justifies why and documents the + mitigations. #### Supportability @@ -609,8 +642,10 @@ Use FURPS framework. Each numbered item should be a testable statement. degrade or fail. 07. Document the operator role for an instance: what running an operator costs, at what cadence updates should be submitted, how anyone can start one - without permission, and how to detect that an instance has stalled. State - plainly that no party is obliged to operate and that liveness rests on + without permission, what it requires (a consensus endpoint and LEZ gas, and + no standing on Ethereum), what an operator should expect when others are + running one concurrently, and how to detect that an instance has stalled. + State plainly that no party is obliged to operate and that liveness rests on interested parties choosing to spend the gas. 08. The module undergoes an independent third-party security audit of the consensus and inclusion verification logic before any mainnet-facing From 86c1d1d7b5aec7a86f0bb31f204cf3f689f5cf32 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Thu, 27 Aug 2026 13:55:53 +1000 Subject: [PATCH 68/69] Rebase onto master: adopt the submission-deadline column Master added a Submission Deadline column to the RFP table and closed RFP-012 and RFP-014. Carry the RFP-021 and RFP-022 rows into the new seven-column shape with no deadline set, and correct both titles to match the RFP frontmatter. Co-Authored-By: Claude Opus 5 (1M context) --- .github/ISSUE_TEMPLATE/proposal.yml | 2 +- README.md | 35 ++++++++++++++--------------- 2 files changed, 18 insertions(+), 19 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/proposal.yml b/.github/ISSUE_TEMPLATE/proposal.yml index 02306ca4..eb59bedb 100644 --- a/.github/ISSUE_TEMPLATE/proposal.yml +++ b/.github/ISSUE_TEMPLATE/proposal.yml @@ -15,7 +15,7 @@ body: - "RFP-016 — Token Launchpad: LBP" - "RFP-017 — Privacy-Preserving Token Vesting" - "RFP-021 — Trustless Ethereum State Attestation for LEZ" - - "RFP-022 — Wrapped ERC-20 Bridge for LEZ" + - "RFP-022 — Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ" validations: required: true diff --git a/README.md b/README.md index c2798408..ffb81f0e 100644 --- a/README.md +++ b/README.md @@ -74,24 +74,23 @@ Click an RFP to view details. Use the Submit Proposal button to apply. -| ID | Title | Tier | Status | Submission Deadline | Category | Submit Proposal | -| ------- | ------------------------------------------------------------------------------------ | ---- | ------ | ------------------- | ---------------------------------- | ----------------------------------------------------------------------------------- | -| RFP-001 | [Admin Authority Library](RFPs/RFP-001-admin-authority-lib.md) | XS | closed | - | Developer Tooling & Infrastructure | Closed | -| RFP-002 | [Freeze Authority Library](RFPs/RFP-002-freeze-authority-lib.md) | XS | closed | - | Developer Tooling & Infrastructure | Closed | -| RFP-003 | [Atomic Swaps with LEZ](RFPs/RFP-003-atomic-swaps.md) | XL | closed | - | Applications & Integrations | Closed | -| RFP-004 | [Privacy-Preserving DEX](RFPs/RFP-004-privacy-preserving-dex.md) | XL | closed | - | Applications & Integrations | Closed | -| RFP-008 | [Lending & Borrowing Protocol](RFPs/RFP-008-lending-borrowing-protocol.md) | XL | closed | - | Applications & Integrations | Closed | -| RFP-012 | [Curated Lending Vaults](RFPs/RFP-012-curated-lending-vaults.md) | L | closed | - | Applications & Integrations | Reopening soon | -| RFP-013 | [Reflexive Stablecoin Protocol](RFPs/RFP-013-reflexive-stablecoin-protocol.md) | XL | closed | - | Applications & Integrations | Closed | -| RFP-014 | [Liquidation & Auction Engine](RFPs/RFP-014-liquidation-auction-engine.md) | L | closed | - | Applications & Integrations | Reopening soon | -| RFP-015 | [Token Launchpad: Bonding Curve](RFPs/RFP-015-bonding-curve-launchpad.md) | L | open | 01/09/26 | Applications & Integrations | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | -| RFP-016 | [Token Launchpad: LBP](RFPs/RFP-016-lbp-launchpad.md) | XL | open | 01/09/26 | Applications & Integrations | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | -| RFP-017 | [Privacy-Preserving Token Vesting](RFPs/RFP-017-token-vesting.md) | L | open | 09/09/26 | Applications & Integrations | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | -| RFP-019 | [On-Chain TWAP Oracle](RFPs/RFP-019-twap-oracle.md) | L | closed | - | Developer Tooling & Infrastructure | Closed | -| RFP-020 | [RedStone Off-Chain Oracle Adaptor for LEZ](RFPs/RFP-020-redstone-oracle-adaptor.md) | M | closed | - | Developer Tooling & Infrastructure | Closed | -| RFP-021 | [Wrapped ERC-20 Bridge for LEZ](RFPs/RFP-021-wrapped-erc20.md) | L | open | - | Developer Tooling & Infrastructure | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | -| RFP-022 | [Trustless Ethereum State Attestation for LEZ](RFPs/RFP-022-ethereum-state-attestation.md) | M | open | - | Developer Tooling & Infrastructure | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | -| RFP-023 | [Native Gas Token Bridge for LEZ](RFPs/RFP-023-gas-token-bridge.md) | M | open | - | Developer Tooling & Infrastructure | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | +| ID | Title | Tier | Status | Submission Deadline | Category | Submit Proposal | +| ------- | ------------------------------------------------------------------------------------------- | ---- | ------ | ------------------- | ---------------------------------- | ----------------------------------------------------------------------------------- | +| RFP-001 | [Admin Authority Library](RFPs/RFP-001-admin-authority-lib.md) | XS | closed | - | Developer Tooling & Infrastructure | Closed | +| RFP-002 | [Freeze Authority Library](RFPs/RFP-002-freeze-authority-lib.md) | XS | closed | - | Developer Tooling & Infrastructure | Closed | +| RFP-003 | [Atomic Swaps with LEZ](RFPs/RFP-003-atomic-swaps.md) | XL | closed | - | Applications & Integrations | Closed | +| RFP-004 | [Privacy-Preserving DEX](RFPs/RFP-004-privacy-preserving-dex.md) | XL | closed | - | Applications & Integrations | Closed | +| RFP-008 | [Lending & Borrowing Protocol](RFPs/RFP-008-lending-borrowing-protocol.md) | XL | closed | - | Applications & Integrations | Closed | +| RFP-012 | [Curated Lending Vaults](RFPs/RFP-012-curated-lending-vaults.md) | L | closed | - | Applications & Integrations | Reopening soon | +| RFP-013 | [Reflexive Stablecoin Protocol](RFPs/RFP-013-reflexive-stablecoin-protocol.md) | XL | closed | - | Applications & Integrations | Closed | +| RFP-014 | [Liquidation & Auction Engine](RFPs/RFP-014-liquidation-auction-engine.md) | L | closed | - | Applications & Integrations | Reopening soon | +| RFP-015 | [Token Launchpad: Bonding Curve](RFPs/RFP-015-bonding-curve-launchpad.md) | L | open | 01/09/26 | Applications & Integrations | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | +| RFP-016 | [Token Launchpad: LBP](RFPs/RFP-016-lbp-launchpad.md) | XL | open | 01/09/26 | Applications & Integrations | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | +| RFP-017 | [Privacy-Preserving Token Vesting](RFPs/RFP-017-token-vesting.md) | L | open | 09/09/26 | Applications & Integrations | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | +| RFP-019 | [On-Chain TWAP Oracle](RFPs/RFP-019-twap-oracle.md) | L | closed | - | Developer Tooling & Infrastructure | Closed | +| RFP-020 | [RedStone Off-Chain Oracle Adaptor for LEZ](RFPs/RFP-020-redstone-oracle-adaptor.md) | M | closed | - | Developer Tooling & Infrastructure | Closed | +| RFP-021 | [Trustless Ethereum State Attestation for LEZ](RFPs/RFP-021-ethereum-state-attestation.md) | M | open | - | Developer Tooling & Infrastructure | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | +| RFP-022 | [Privacy-Preserving Wrapped ERC-20 and Ether Bridge for LEZ](RFPs/RFP-022-wrapped-erc20.md) | L | open | - | Developer Tooling & Infrastructure | [Submit Proposal](https://github.com/logos-co/rfp/issues/new?template=proposal.yml) | From ceac7e4d162dc9fa1774b3de505a3eef0174e8a8 Mon Sep 17 00:00:00 2001 From: fryorcraken Date: Thu, 27 Aug 2026 13:59:47 +1000 Subject: [PATCH 69/69] RFP-021: state the design directly, without arguing against the old draft Drop the paragraph and clauses whose only job was to reject the previous off-chain proving framing. A first-time reader never saw it. Fold the one new fact, where the submitter fetches update material, into the design paragraph and state the rest positively. Co-Authored-By: Claude Opus 5 (1M context) --- RFPs/RFP-021-ethereum-state-attestation.md | 33 ++++++++-------------- 1 file changed, 12 insertions(+), 21 deletions(-) diff --git a/RFPs/RFP-021-ethereum-state-attestation.md b/RFPs/RFP-021-ethereum-state-attestation.md index 92300322..4bc48a1b 100644 --- a/RFPs/RFP-021-ethereum-state-attestation.md +++ b/RFPs/RFP-021-ethereum-state-attestation.md @@ -179,20 +179,13 @@ fact every consumer needs and no consumer needs privately, whereas inclusion is specific to the consumer's own transaction. The expected design follows that asymmetry. A **light client runs inside the LEZ -program itself**: the module verifies the sync-committee signature and the -committee handoff on-chain, and a module account accumulates the verified +program itself**: a submitter supplies light-client update material fetched from +an Ethereum consensus endpoint, the module verifies the sync-committee signature +and the committee handoff, and a module account accumulates the verified committee and finalised header roots. A **consumer** then submits only an inclusion proof against a header already verified in that shared state, performing no signature verification of its own. -Verification happens in the program, not off-chain. A submitter supplies the -light-client update material fetched from an Ethereum consensus endpoint, and -the module checks it. This RFP does not ask for a separate off-chain proving -system that wraps the signature check in a proof for LEZ to verify: LEZ -execution is already proven, so a second proof layer over the same check would -add a translation step and its own audit surface without strengthening the -guarantee. The sync-committee aggregate is used as it is. - **Submission must be permissionless.** Anyone can spend the gas and advance the state; no party is designated, and none can be excluded. The submitter is untrusted because the module verifies the update: it cannot insert a header the @@ -242,9 +235,8 @@ built and audited several times over: Telepathy, SP1 Helios, and `r0vm-helios` all implement it, audited by Veridise, Zellic, and zkSecurity respectively. Those systems target destination chains that cannot verify a sync-committee signature affordably, so they prove the check off-chain and verify a succinct -proof on the destination. LEZ does not have that constraint, so what transfers -here is the light-client logic rather than the outer proving layer. Applicants -should assess reuse on that basis, per the Design Rationale note below. The +proof on the destination. What transfers here is their light-client logic, which +an applicant should assess for reuse per the Design Rationale note below. The [Ethereum Light Client Ecosystem appendix](../appendix/ethereum-light-client-ecosystem.md) surveys these implementations, their trust models, and a production fork that deliberately made submission permissioned, which is direct evidence that @@ -406,12 +398,11 @@ RFP needs on the same zkVM LEZ runs on, which makes it a materially different starting point from a blank sheet, as does Helios itself upstream. It is not a drop-in. It targets EVM destination chains with Solidity contracts, -and LEZ is neither, and its off-chain proving layer is not needed here. How much -transfers, and whether the better base is one of these zkVM forks or the -upstream light-client implementations they derive from, is a judgement the -applicant is better placed to make than this specification. That evaluation is -itself work, and Reliability #6 scopes it as a deliverable. Reuse is expected to -be assessed seriously; it is not mandated. +and LEZ is neither. How much transfers, and whether the better base is one of +these zkVM forks or the upstream light-client implementations they derive from, +is a judgement the applicant is better placed to make than this specification. +That evaluation is itself work, and Reliability #6 scopes it as a deliverable. +Reuse is expected to be assessed seriously; it is not mandated. ## ✅ Scope of Work @@ -424,8 +415,8 @@ Use FURPS framework. Each numbered item should be a testable statement. 01. Run the Ethereum light client inside the LEZ program: given a trusted starting checkpoint, the module verifies light-client updates and committee handoffs against material supplied by the submitter, and follows the - canonical finalised chain forward without running a full node. No off-chain - proving system stands between the sync committee and the module. + canonical finalised chain forward without running a full node. The module + checks the sync-committee aggregate itself. 02. Verify that a supplied Ethereum block header is finalised, and reject any header that is not. 03. Verify that a referenced piece of Ethereum state is included under a header