feat: ethereum protocol

patterns/pattern-eil.md

@@ -0,0 +1,66 @@
+---
+title: "Pattern: EIL (Ethereum Interoperability Layer)"
+status: draft
+maturity: PoC
+works-best-when:
+  - User needs to execute calls on multiple L2s with one signature
+  - Assets scattered across chains need to be used without bridging friction
+  - No gas on destination chain but funds available on source chain
+avoid-when:
+  - Contract-to-contract composability required (use crosschain messaging instead)
+  - High-level intent without knowing specific contract calls (solvers better suited)
+  - Institutional-scale transfers requiring immediate economic finality
+dependencies: [ERC-4337, EIP-7701, RIP-7859]
+---
+
+## Intent
+
+Account-based cross-L2 interoperability where users sign once and execute transactions directly on multiple chains. XLPs (Crosschain Liquidity Providers) supply gas and liquidity via atomic swaps, but never execute calls on the user's behalf. This enables the optimistic design that's much faster and more efficient than HTLC's pessimistic hash-secret approach.
+
+## Ingredients
+
+- ERC-4337 accounts with multichain validation modules (Merkle root over UserOps)
+- CrossChainPaymaster contracts on each L2
+- L1CrossChainStakeManager for XLP registration
+- XLPs staking on L1 (8-day unstake delay, O(networks) not O(funds))
+- P2P mempool for UserOp propagation
+- L1 canonical bridge for dispute resolution
+
+## Protocol
+
+1. Alice finds registered XLPs operating on both source and destination chains
+2. Alice signs multichain UserOp. On source chain she locks funds in `CrossChainPaymaster`, requests voucher specifying XLP list and fee schedule (reverse Dutch auction). Request is short-lived; funds unlock if no voucher provided promptly
+3. XLP claims Alice's source funds by providing signed voucher (commitment for destination). Same voucher that claims source funds releases XLP funds on destination. Source funds remain locked 1 hour before crediting XLP deposit
+4. Alice appends XLP voucher to destination `UserOp` signature, submits to destination chain
+5. Destination `CrossChainPaymaster` verifies voucher, checks XLP has sufficient deposits, pays gas and gives Alice the funds
+6. Alice's calls execute. Flow can traverse any number of L2s using same signature
+7. If XLP misbehaves: L1-based dispute mechanism ensures funds cannot be lost or stolen, penalizes violating XLPs, incentivizes other XLPs to prove violations
+
+## Guarantees
+
+- No privacy improvements (token amounts and gas limits revealed pre-execution; call targets visible on-chain)
+- Censorship resistance via permissionless mempool (single honest node sufficient)
+- No trusted intermediaries (users execute directly, disputes resolved via L1)
+- Same security as underlying chains (XLPs cannot steal funds, only face slashing risk)
+- One signature per operation across all chains
+- Minimum latency (as fast as underlying chains)
+
+## Trade-offs
+
+- Requires same account implementation or validation module on all chains
+- Requires same key on all chains (mitigated long-term via L1 keystore with L1SLOAD)
+- 1-hour fund lock on source chain after voucher issuance (capital efficiency cost)
+- XLP reorg risk on chains with frequent reorganizations
+- Not suitable for contract-to-contract composability (only account-based)
+- ERC-4337 overhead until EIP-7701 (Native AA) adoption
+- Dispute mechanism adds complexity vs simple bridges
+
+## Example
+
+Arbitrum Alice wants to mint 1 ETH NFT on Linea. She has 0.8 ETH on Arbitrum and 0.5 ETH on Scroll. Wallet generates 3 UserOps (Arbitrum transfer, Scroll transfer, Linea mint), signs Merkle root once. XLPs provide vouchers on Arbitrum and Scroll, Alice's funds atomic-swapped to Linea, NFT minted, all verified within 2-3 seconds total.
+
+## See also
+
+- [Ethrearch post](https://ethresear.ch/t/eil-trust-minimized-cross-l2-interop/23437)
+- [Typescritpt SDK](https://github.com/eth-infinitism/eil-sdk)
+- [Yoav Weiss - Trust-Minimized Interop with EIL](https://www.youtube.com/watch?v=kFKvZuXUmQY)

patterns/pattern-focil-eip7805.md

@@ -0,0 +1,64 @@
+---
+title: "Pattern: FOCIL - Fork-Choice Enforced Inclusion Lists"
+status: draft
+maturity: PoC
+works-best-when:
+  - Censorship resistance is critical
+  - Block builders concentrate power and may censor transactions
+  - Same-slot transaction inclusion guarantees needed
+avoid-when:
+  - Mempool visibility of transaction details is unacceptableh
+dependencies: [EIP-7805]
+---
+
+## Intent
+
+FOCIL (Fork-Choice Enforced Inclusion Lists) is a standard that enables a committee of 16 validators to force-include transactions in blocks, preventing censorship by sophisticated block builders. FOCIL itself does not provide privacy, transactions remain fully visible in the public mempool and on-chain. It only guarantees that transactions cannot be censored once submitted to the mempool.
+
+## Protocol (concise)
+
+1. Committee Selection (Slot N), a committee of 16 validators is selected for slot N to build ILs for slot N+1
+2. IL Construction (t=0-8s), committee members monitor the public mempool and construct ILs (max 8 KiB) containing transactions they want force-included
+3. IL Broadcasting (t=8s), Committee members gossip their signed ILs over the P2P network after processing slot N's block
+4. View Freeze (t=9s), All validators freeze their view of ILs; no new ILs accepted after this deadline; equivocation detection active
+5. Block Building (t=11s), Builder for slot N+1 collects all ILs and updates execution payload to include IL transactions (anywhere in block)
+6. Block Proposal (Slot N+1, t=0s), Proposer broadcasts block with IL transactions included
+7. Attestation (t=4s), Attesters verify all non-equivocated IL transactions are included (or invalid); only attest if satisfied
+8. Fork-Choice Enforcement, Blocks failing to satisfy ILs receive no attestations and cannot become canonical
+
+## Guarantees
+
+- **Censorship Resistance Under Builder Centralization:** 1-out-of-16 honesty assumption—single honest IL committee member prevents transaction censorship by decoupling block building from validation
+- **Same-Slot:** No delay—constraints for slot N+1 include transactions from slot N (vs 1-slot delay in forward ILs)
+- **Anywhere-in-Block:** Builder chooses transaction placement, reducing incentive for side channels
+- **Fork-Choice Enforced:** Non-compliant blocks cannot achieve finality; attesters reject blocks not satisfying ILs
+- **No Privacy:** Transaction details remain fully visible in mempool and on-chain
+
+## Trade-offs
+
+- **Performance:** Additional bandwidth for IL gossip (up to 16 × 8 KiB per slot); potential O(n²) validity checks if naively implemented
+- **Liveness Risk:** Builder must be well-connected to IL committee; insufficient time between view freeze (t=9s) and block broadcast risks missed ILs
+- **Equivocation Handling:** P2P rule allows forwarding up to 2 ILs per committee member; equivocators ignored but bandwidth can double in worst case
+- **No Direct Incentives:** Relies on altruistic behavior—no explicit rewards for IL committee members
+- **Complexity:** Requires consensus layer fork-choice changes, execution layer validation, and coordinated P2P network updates
+
+## Example
+
+**Institutional Payment Censorship Resistance (No Privacy):**
+
+1. Bank A submits stablecoin payment transaction (€5M EURC transfer) to public mempool at t=0s of slot N, transaction details fully visible to all observers
+2. IL committee member (validator 42) sees Bank A's public transaction and includes it in their IL, broadcasts at t=8s
+3. View freezes at t=9s—all validators store validator 42's IL containing Bank A's payment
+4. Builder for slot N+1 collects IL at t=11s, verifies Bank A has sufficient balance/correct nonce, includes payment in block
+5. Attesters at t=4s verify Bank A's payment is in block (or invalid); all attest to block
+6. Result: Even if builder wants to censor Bank A (OFAC compliance, MEV extraction, competitive intelligence), fork-choice enforcement prevents censorship
+7. Privacy impact: NONE, amount (€5M), counterparty, and timing remain publicly visible throughout the process
+
+**Note:** For privacy-preserving institutional payments, FOCIL must be combined with other patterns like [Private Stablecoin Shielded Payments](./pattern-private-stablecoin-shielded-payments.md) or [Privacy L2s](./pattern-privacy-l2s.md).
+
+## See also
+
+- [Pre-trade Privacy (Shutter/SUAVE)](./pattern-pretrade-privacy-shutter-suave.md) — complementary pattern for hiding transaction content before inclusion
+- [EIP-7547](https://eips.ethereum.org/EIPS/eip-7547) — forward inclusion lists (1-slot delay vs same-slot in FOCIL)
+- [Private Payments Approach](../approaches/approach-private-payments.md) — FOCIL ensures inclusion; private payments hide content
+- [Verifiable Attestation](./pattern-verifiable-attestation.md) — attesters validate IL satisfaction before attesting

patterns/pattern-lean-ethereum.md

@@ -0,0 +1,94 @@
+---
+title: Lean Ethereum
+status: draft
+maturity: research
+works-best-when:
+  - Long-term Ethereum consensus redesign needed
+  - Solo validation accessibility matters
+avoid-when:
+  - Near-term deployment required (4–5 year horizon)
+dependencies: [Post-quantum signatures, minimal zkVMs, P2P networking upgrades]
+---
+
+## Intent
+
+A long-range redesign of Ethereum’s consensus layer aiming to enter in action around 2030. Lean consolidates multiple research tracks into a single major fork, reducing hardware requirements, improving validator accessibility, enabling fully verifying light clients on minimal devices, and preparing for a post-quantum world.
+
+## Ingredients
+
+- Specifications (in development)
+
+  - Post-quantum hash-based multisignatures
+  - Minimal zkVMs for signature aggregation & proof compression
+  - Networking upgrades: Gossipsub v2, rateless set reconciliation
+  - Finality research (e.g., low-slot-count fast finality variants)
+  - Validator set expansion & economics (lower thresholds under discussion)
+
+- Infrastructure
+
+  - ~15 client teams prototyping implementations across Rust, Zig, C, C++, Go, Java, .NET, TypeScript, Nim, Elixir
+  - Formal verification tooling (Lean 4)
+  - Cryptanalysis and protocol correctness research (Poseidon, hash-based schemes)
+
+- Research tracks
+
+  - Post-quantum signature design & aggregation
+  - Minimal zkVM architecture
+  - Formal methods & proof automation
+  - Set reconciliation & P2P efficiency
+
+## Protocol (concise)
+
+1. Introduce post-quantum multisignatures
+
+   - Hash-based multisig schemes explored (e.g., XMSS/Winternitz variants).
+
+2. Use minimal zkVMs for signature aggregation
+
+   - Off-chain aggregation verified via succinct proofs.
+   - Exact workflow under active research.
+
+3. Expand validator participation
+
+   - Lower hardware & bandwidth requirements.
+   - Reduced stake requirements to 1 ETH.
+   - Tiered validator responsibilities under exploration.
+
+4. Shorter slot times & faster finality
+
+   - Targeting ~4s slot times (as explored in roadmap).
+   - Fast-finality schemes (e.g., 3-slot variants) under evaluation; parameters TBD.
+
+5. Deploy upgraded networking
+
+   - Gossipsub v2 for throughput and DOS-resilience.
+   - Rateless set reconciliation to support large validator sets.
+
+6. Enable full light-client verification on minimal devices
+
+   - Small-footprint consensus proofs verifiable on mobile/IoT class hardware.
+
+## Guarantees (intended outcomes)
+
+- Protocol ossification, after the Lean fork, consensus enters long-term stability / minimal changes.
+- Post-quantum resilience, core signatures hardened against quantum adversaries.
+- Validator decentralization, vastly increased solo staking due to lower hardware & stake requirements.
+- Universal light clients, full consensus verification without trust assumptions.
+  DOUBT
+- Clear boundaries, lean modifies consensus _only_, execution-layer scaling & privacy handled by separate tracks.
+
+## Trade-offs
+
+- Timeline risk: 4–5 year horizon with heavy reliance on open research questions
+- Single large fork: Failure at any component delays entire bundle
+- Research coupling: PQ signatures, zkVMs, and P2P upgrades must all reach production readiness
+- Consensus-only scope: Does not address L1 execution scaling or transaction privacy
+
+## Example (illustrative)
+
+A consumer-grade laptop runs a solo validator at a much lower stake threshold. A minimal zkVM compresses committee signatures off-chain into a single proof verifiable in milliseconds. The network operates at ~4-second slots with low-slot-count fast finality. A mobile phone verifies the full consensus rules independently. After rollout, Ethereum’s consensus remains stable for decades.
+
+## See also
+
+- [Lean Roadmap](https://leanroadmap.org/)
+- [Lean Specification repository](https://github.com/leanEthereum/leanSpec)

patterns/pattern-oif.md

@@ -0,0 +1,60 @@
+---
+title: "Pattern: Open Intent Framework (OIF)"
+status: draft
+maturity: PoC
+works-best-when:
+  - Cross-chain settlement needed
+  - Intent-based execution preferred
+  - Permissionless solver participation desired
+avoid-when:
+  - Single-chain operations sufficient
+  - Transaction privacy required (intents visible to solvers)
+---
+
+## Intent
+
+OIF enables cross-chain intent-based settlement where users express desired outcomes and solvers compete to execute them across chains permissionlessly.
+
+## Ingredients
+
+- [OIF contracts](https://github.com/openintentsframework/oif-contracts) for input collection, output delivery, oracle/messaging/settlement
+- [OIF solver](https://github.com/openintentsframework/oif-solver) for intent discovery, execution path optimization, cross-chain settlement
+- Infrastructure: Cross-chain messaging layer, price oracles
+
+## Protocol (concise)
+
+1. User signs/submits an intent to the smart contract (e.g., “sell X on chain A, deliver Y on chain B”).
+2. Solver network monitors the contract(s), indexes new intents and identifies candidate fulfilment opportunities.
+3. Solvers compute optimal execution route(s) across chains/bridges/liquidity pools given the intent.
+4. The selected solver executes the required cross-chain operations (swaps, messaging, transfers) and uses the settlement layer to ensure final delivery.
+5. An oracle or proof mechanism confirms that the output asset has been delivered per intent; the contract (or settlement module) marks the intent complete and releases locked input assets (or refunds if non-fulfilled).
+6. If the solver fails or deadline is missed, the system supports cancellation or refund flows (depending on governance/implementation).
+
+## Guarantees
+
+- **Permissionless execution**: any solver that meets the protocol can participate; the framework does not enforce a centralized solver set.
+- **Modularity and composability**: developers can swap in different settlement, oracle or messaging layers while still using the intent-based front-end.
+- **Higher-level intent abstraction**: users focus on what they want, not how to achieve it; solvers deal with routing/bridging complexity.
+- **Transparency (and trade-off)**: intent details (assets, chains, amounts) are visible to solvers during discovery, exposing some MEV/visibility risk.
+
+- _Note_: Cross-chain atomicity is a goal but depends on the settlement layer’s guarantees. Developers should design flows (escrows, resource locking) appropriately to approximate atomic delivery.
+
+## Trade-offs
+
+- Solver network must be active and sufficiently liquid for intents to be fulfilled in a timely way.
+- Cross-chain operations inherently carry higher latency and complexity vs. single-chain flows.
+- Multi-step cross-chain settlement increases attack surface (messaging proofs, oracle delays).
+- Intent visibility
+
+## Example: Cross-Chain Stablecoin Settlement
+
+1. Bank A submits intent: “Transfer 5 M USDC on Ethereum, receive 5 M USDT on Arbitrum”.
+2. Solver network discovers the intent and computes execution path (e.g., USDC bridge to Arbitrum → swap to USDT).
+3. Winning solver executes the required steps: USDC moved, USDT delivered.
+4. Settlement layer verifies delivery and marks the intent complete; Bank A receives 5 M USDT on Arbitrum.
+5. If execution fails or misses deadline, the fallback mechanism refunds or cancels the intent.
+
+## See also
+
+- ERC‑7683 — the intent standard supported by OIF and enabling cross-protocol intent interoperability.
+- Privacy-preserving intent approaches (for situations where you need intent confidentiality and cannot expose details to solvers).