ADR: typed sponsorship transactions WIP

[randygrok]

Draft ADR describing typed transactions for sponsorship (EIP-2718) with ev-reth-specific envelope and fields.

[claude]

Claude finished @randygrok's task —— View job

---

Reviewing ADR: Typed Sponsorship Transactions

Todo List:

• Read and analyze the ADR document structure and content
• Evaluate technical design completeness and correctness
• Review security implications and potential vulnerabilities
• Check alignment with ev-reth architecture
• Assess implementation feasibility
• Provide comprehensive feedback on code quality and best practices

---

🔍 Code Review Summary

This ADR proposes a well-structured approach to implementing gas sponsorship via EIP-2718 typed transactions. While the overall design is sound, there are several critical areas that need attention before implementation.

🔴 Critical Issues

1. Incomplete Transaction Structure (docs/adr/ADR-0003-typed-transactions-sponsorship.md:116-130)

The EvNodeTransaction struct is missing essential EIP-1559 transaction fields. The current struct doesn't include a user signature, making it impossible to validate the actual transaction executor.

Recommended structure:

pub struct EvNodeTransaction {
    // Standard EIP-1559 fields
    pub chain_id: u64,
    pub nonce: u64,
    pub max_priority_fee_per_gas: u128,
    pub max_fee_per_gas: u128,
    pub gas_limit: u64,
    pub to: TxKind,
    pub value: U256,
    pub data: Bytes,
    pub access_list: AccessList,
    // User signature over transaction data
    pub user_signature: Signature,
    // Optional sponsorship fields
    pub fee_payer: Option<Address>,
    pub fee_payer_signature: Option<Signature>,
}

2. Security: Undefined Signature Domains (docs/adr/ADR-0003-typed-transactions-sponsorship.md:142-156)

Critical security vulnerability: The ADR doesn't specify what data the fee_payer_signature covers. This creates risk for:

• Replay attacks across different chains
• Transaction malleability
• Sponsor authorization scope confusion

Required: Define explicit signing domains with:

• User domain: keccak256(0x76 || rlp(tx_without_sponsor_fields))
• Sponsor domain: keccak256(0x78 || rlp(tx_hash) || sponsor_address || chain_id)

3. Fee Token Payment Mechanism Undefined (docs/adr/ADR-0003-typed-transactions-sponsorship.md:128)

The struct includes fee_payer but no fee_token field, yet the text mentions token-based fee payment. This is inconsistent and incomplete.

Needs clarification:

• How are exchange rates determined?
• Who provides price oracles?
• What's the conversion mechanism?
• How are different tokens validated?

🟡 Major Concerns

4. Architecture Compatibility Gap

Current ev-reth uses reth_ethereum::EthPrimitives and TransactionSigned (see crates/node/src/node.rs:78 and crates/node/src/attributes.rs:84). The proposed design requires custom primitives but doesn't address:

• Migration path from current transaction handling
• Backward compatibility with existing Engine API
• Impact on existing test infrastructure

5. Missing State Validation Logic (docs/adr/ADR-0003-typed-transactions-sponsorship.md:272-285)

The proposed sponsor balance validation is incomplete:

// Current proposal - insufficient
if balance < max_cost.into() {
    return Err(ValidationError::InsufficientSponsorBalance);
}

Missing considerations:

• Concurrent transaction handling from same sponsor
• Nonce management for sponsors vs executors
• Gas price fluctuation during execution
• Priority fee handling with sponsored transactions

6. RLP Encoding Determinism (docs/adr/ADR-0003-typed-transactions-sponsorship.md:134-141)

While field ordering is specified, the encoding of Option<Address> and Option<Signature> as 0x80 may cause issues:

• Inconsistent with standard Ethereum RLP conventions
• Potential compatibility problems with tooling
• May complicate debugging and transaction parsing

🟢 Strengths

1. Solid EIP-2718 Foundation: Correctly leverages typed transactions standard
2. Clear Separation of Concerns: Maintains executor vs sponsor roles properly
3. Engine API Integration: Aligns well with existing ev-reth transaction submission pattern
4. No Pool Complexity: Smart decision to scope out mempool integration initially

📋 Required Actions

1. Complete the transaction structure with all required fields including user signature
2. Define explicit cryptographic signature domains with clear security properties
3. Specify fee token mechanism or remove references to token-based payments
4. Add comprehensive state validation including concurrent transaction scenarios
5. Define migration strategy from current EthPrimitives to custom primitives
6. Complete alternatives section documenting other considered approaches

🔧 Implementation Recommendations

1. Start with ETH-only sponsorship - defer token payments to future ADR
2. Add integration tests covering signature validation and state transitions
3. Consider backwards compatibility - ensure existing transaction types continue working
4. Define clear error handling for all failure modes (insufficient balance, invalid signatures, etc.)

📊 Test Coverage Assessment

The ADR lacks test strategy. Recommend adding:

• Unit tests for signature validation and RLP encoding/decoding
• Integration tests for Engine API transaction submission
• End-to-end tests covering sponsor balance validation
• Negative test cases for all identified failure modes

Overall Assessment: Promising design requiring significant refinement before implementation. The core concept is sound, but critical security and completeness gaps must be addressed.

---

[gemini-code-assist]

Summary of Changes

Hello @randygrok, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a draft Architectural Decision Record (ADR) proposing a standardized mechanism for gas sponsorship within the ev-reth project. By leveraging EIP-2718's typed transactions, this ADR aims to define a new transaction type that explicitly separates the fee payer from the transaction initiator. This approach seeks to simplify user onboarding and product integrations by allowing a designated sponsor to cover transaction costs, thereby removing the requirement for end-users to hold native funds, all while maintaining compatibility with existing Ethereum tooling and execution semantics.

Highlights

• Proposal for typed sponsorship transactions: Introduces a new Architectural Decision Record (ADR) to implement gas sponsorship using EIP-2718 typed transactions in ev-reth.
• New transaction type (0x76): Defines a specific transaction type (0x76) within ev-reth that separates the gas payer (sponsor) from the transaction executor, allowing a sponsor to cover fees without altering the user's call origin.
• EvRethTxEnvelope extension: Outlines the extension of the EvRethTxEnvelope enum to include the new SponsorTransaction type, detailing its structure with user call fields and separate sponsorship fields.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces an Architecture Decision Record (ADR) for implementing typed sponsorship transactions in ev-reth. The proposal leverages EIP-2718 to create a new transaction type that separates the gas payer (sponsor) from the transaction executor.

The ADR is well-structured and provides a good overview of the context and decision. However, the proposed implementation details have some significant gaps. The SponsorTransaction struct is missing key fields from the user's transaction, making the design incomplete. Additionally, critical security aspects, such as what the sponsor's signature covers, are not defined. The mechanism for paying fees with tokens also needs further clarification. My review includes suggestions to address these points to make the design more robust and secure.