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

---

Comprehensive PR Review: Typed Sponsorship Transactions ADR

This PR introduces a draft Architectural Decision Record (ADR) for implementing typed sponsorship transactions in ev-reth using EIP-2718. I've thoroughly reviewed the proposal and identified several critical areas that need attention.

✅ Strengths

1. Well-structured ADR format - Follows proper ADR structure with clear sections and rationale
2. Good technical foundation - Leverages EIP-2718 typed transactions appropriately
3. Detailed implementation plan - Comprehensive breakdown of required changes across crates
4. Preserves execution semantics - Correctly maintains that executor remains from/nonce owner
5. Clear separation of concerns - Sponsor only pays fees, executor handles execution

⚠️ Critical Issues Requiring Attention

1. Incomplete Transaction Structure (HIGH PRIORITY)

The proposed EvNodeTransaction struct in the specification section is missing critical fields compared to the implementation section:

Specification (lines 64-80): Missing user_signature field and access list

pub struct EvNodeTransaction {
    // EIP-1559-like fields
    chain_id: u64,
    // ... other fields
    // Missing: executor/user signature!
}

Implementation (lines 194-208): More complete but inconsistent naming

pub struct EvNodeTransaction {
    // ... standard fields
    pub fee_payer: Option<Address>,
    pub fee_payer_signature: Option<Signature>,
    // Still missing: executor signature field
}

Recommendation: The struct needs an executor/user signature field. Something like:

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,
    
    // Sponsorship fields  
    pub fee_payer: Option<Address>,
    pub fee_payer_signature: Option<Signature>,
}

2. Security: Undefined Signature Domains (HIGH PRIORITY)

The ADR mentions two signature domains (0x76 and 0x78) but doesn't specify:

• What data the sponsor signature covers - critical for preventing replay attacks
• How sponsor address is derived - presumably from signature recovery
• Binding between sponsor signature and user transaction - preventing signature reuse

Recommendation: Add detailed specification of what each signature covers:

// Executor signs: keccak256(0x76 || rlp([chain_id, nonce, ...data, access_list]))  
// Sponsor signs: keccak256(0x78 || rlp([user_tx_hash, fee_token, sponsor_constraints]))

3. Fee Token Payment Mechanism Undefined (MEDIUM PRIORITY)

The implementation section references fee_token: Address but this field is missing from both struct definitions. If fees can be paid in tokens other than native currency:

• How are exchange rates determined?
• Who provides price oracles?
• Is there a DEX integration or dedicated contract?

4. Missing Alternatives Section (MEDIUM PRIORITY)

The "Alternatives" section is marked as TODO. For a complete ADR, this should document other approaches considered (e.g., account abstraction, meta-transactions, off-chain bundling) and why this approach was chosen.

5. Integration Concerns with Current Architecture

Based on the current ev-reth architecture:

crates/node/src/attributes.rs:84: Currently uses TransactionSigned::network_decode

TransactionSigned::network_decode(&mut tx_bytes.as_ref())

This needs to be updated to support the new EvTxEnvelope for 0x76 transactions.

Integration Point: The ADR correctly identifies that attributes.rs needs modification, but the scope of changes to support custom NodeTypes::Primitives throughout the codebase is significant.

🔧 Technical Concerns

Type System Changes

The ADR proposes extensive type system changes that will affect:

• Storage layer (custom DB codecs)
• RPC layer (custom transaction types in responses)
• Pool layer (validation and propagation)
• Execution layer (fee accounting)

This is a substantial architectural change that should be phased carefully.

Performance Impact

Two signature verifications per sponsored transaction could impact performance. Consider:

• Batching signature verification
• Caching sponsor authorizations
• Optimizing the sponsor signature format

Gas Accounting Complexity

The EVM handler modifications for sponsor fee accounting (mentioned in implementation) need careful design to ensure state root consistency and avoid edge cases in execution.

📋 Recommendations for Next Steps

1. Complete the transaction structure with all required fields
2. Define signature domains precisely with detailed security specifications
3. Clarify fee token mechanism or remove references if not implemented
4. Fill in alternatives section to justify design choices
5. Create implementation phases to reduce risk of such a large change
6. Add security analysis section covering replay protection and economic attacks
7. Include test strategy for the new transaction type

🎯 Verdict

This is a solid foundation for sponsorship transactions in ev-reth, but the ADR needs completion before implementation. The core design is sound, but critical details around signatures, fee payment, and transaction structure must be resolved.

The proposal aligns well with ev-reth's architecture of accepting transactions via Engine API, making this a natural evolution of the current system.

---

[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.