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

---

Code Review for ADR-0003: Typed Sponsorship Transactions

• Read and analyze the ADR document
• Review architectural design decisions
• Check for security considerations
• Evaluate implementation completeness
• Provide feedback on best practices
• Assess test coverage implications

Review Summary

This ADR proposes implementing EIP-2718 typed sponsorship transactions (0x76) in ev-reth to enable gas sponsorship where a separate entity pays transaction fees while preserving executor identity and EVM semantics. The proposal is well-structured but has several critical gaps that need addressing before implementation.

Critical Issues

1. Incomplete Transaction Structure ⚠️ HIGH PRIORITY

The proposed EvNodeTransaction struct at line 61-76 is fundamentally incomplete:

pub struct EvNodeTransaction {
    // EIP-1559-like fields
    chain_id: u64,
    nonce: u64,
    max_priority_fee_per_gas: u128,
    max_fee_per_gas: u128,
    gas_limit: u64,
    to: TxKind,
    value: U256,
    data: Bytes,
    access_list: AccessList,
    // Missing user signature!
    // Sponsorship (optional)
    fee_payer: Option<Address>,
    fee_payer_signature: Option<Signature>,
}

Missing critical field: The structure lacks the executor's signature (user_signature or executor_signature). Without this, there's no way to authenticate the transaction's actual executor or verify they authorized the transaction.

Recommended fix:

pub struct EvNodeTransaction {
    // ... existing fields ...
    pub executor_signature: Signature,  // User's signature over transaction data
    pub fee_payer: Option<Address>,
    pub fee_payer_signature: Option<Signature>,
}

2. Undefined Signature Security Model 🔒 HIGH PRIORITY

The ADR specifies two signature domains (0x76 for executor, 0x78 for sponsor) but fails to define what the sponsor signature actually covers, creating serious security vulnerabilities:

• No replay protection: Sponsor signatures could be reused across different transactions
• No binding: No guarantee the sponsor authorized this specific transaction
• No nonce protection: Sponsor signatures lack nonce-based ordering

Security requirements missing:

• What data does fee_payer_signature sign over?
• How is the sponsor's address derived and verified?
• How are replay attacks prevented?
• What prevents sponsor signature front-running?

3. Fee Token Payment Mechanism Undefined 💰 HIGH PRIORITY

Line 192 introduces fee_token: Address but the ADR provides no implementation details for non-native token payments:

• How are exchange rates determined?
• What oracle system provides pricing?
• How is the token → gas conversion handled?
• Where does the actual token transfer occur?
• What happens if token transfer fails?

Architecture & Integration Concerns

4. Missing Integration with Existing ev-reth Architecture

The ADR doesn't address how this integrates with ev-reth's current transaction handling:

• Engine API path: How do 0x76 transactions flow through EvolvePayloadAttributes (currently uses TransactionSigned)?
• Txpool integration: The txpoolExt_getTxs RPC returns RLP bytes - how does this work with custom signing?
• Validation pipeline: How does this integrate with ev-reth's existing validation in crates/node/src/validator.rs?

5. Consensus and State Transition Gaps

• Receipt format: No specification for how sponsorship is reflected in receipts
• State transitions: Missing details on balance checks and transfers
• Failure modes: Undefined behavior when sponsor balance insufficient
• Gas estimation: No guidance for RPC methods like eth_estimateGas

Implementation Completeness Issues

6. Missing Test Strategy

The ADR lacks any testing considerations:

• Unit tests for signature verification
• Integration tests with Engine API
• Security tests for replay attacks
• Performance benchmarks for signature overhead

7. Incomplete Error Handling

The current PayloadAttributesError enum in crates/evolve/src/types.rs:65-88 doesn't cover sponsorship-related failures:

• Invalid sponsor signature
• Insufficient sponsor balance
• Sponsor authorization failures
• Fee token transfer errors

Security Recommendations

8. Recommended Security Model

// Sponsor should sign hash of:
// keccak256(domain_separator || executor_tx_hash || sponsor_nonce || fee_token || max_sponsor_fee)

pub struct SponsorAuthorization {
    pub sponsor: Address,
    pub sponsor_nonce: u64,        // Prevents replay
    pub max_sponsor_fee: U256,     // Prevents overpayment
    pub fee_token: Address,        // Token to pay with
    pub signature: Signature,      // Over above fields + executor tx
}

Performance Considerations

• Signature overhead: Two signature verifications per transaction
• Storage impact: Additional fields increase transaction size by ~100 bytes
• RPC compatibility: Breaking change to transaction JSON representation

Positive Aspects

✅ Strong architectural foundation: Leverages EIP-2718 properly
✅ Good separation of concerns: Executor vs sponsor roles clearly defined
✅ Backward compatibility: Optional sponsorship preserves existing behavior
✅ Implementation planning: Detailed 8-step implementation plan

Recommendations

1. Complete the transaction structure with executor signature
2. Define comprehensive security model for sponsor authorization
3. Specify fee token mechanics or remove until later ADR
4. Add integration details with existing ev-reth components
5. Include test coverage requirements in implementation plan
6. Define error handling for all failure modes
7. Consider alternatives section as noted by Gemini Code Assist

Conclusion

While this ADR addresses an important use case and shows solid architectural thinking, the current specification is insufficient for secure implementation. The missing executor signature and undefined security model represent critical vulnerabilities that must be addressed before proceeding.

Recommendation: Mark as draft requiring significant revision before implementation.

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