EIP-8141 - Frame Transaction

Abstract

Add a new transaction whose validity and gas payment can be defined abstractly. Instead of relying solely on a single ECDSA signature, accounts may freely define and interpret their signature scheme using any cryptographic system.

Motivation

This new transaction provides a native off-ramp from the elliptic curve based cryptographic system used to authenticate transactions today, to post-quantum (PQ) secure systems.

In doing so, it realizes the original vision of account abstraction: unlinking accounts from a prescribed ECDSA key and support alternative fee payment schemes. The assumption of an account simply becomes an address with code. It leverages the EVM to support arbitrary user-defined definitions of validation and gas payment.

Specification

Constants

Opcodes

New Transaction Type

A new EIP-2718 transaction with type FRAME_TX_TYPE is introduced. Transactions of this type are referred to as "Frame transactions".

The payload is defined as the RLP serialization of the following:

[chain_id, nonce, sender, frames, max_priority_fee_per_gas, max_fee_per_gas, max_fee_per_blob_gas, blob_versioned_hashes]

frames = [[mode, target, gas_limit, data], ...]

If no blobs are included, blob_versioned_hashes must be an empty list and max_fee_per_blob_gas must be 0.

Frame Modes

The mode of each frame sets the context of execution. It allows the protocol to identify the purpose of the frame within the execution loop.

The execution mode of a frame is identified by the lower bits (<= 8) of the mode field. The modes are explained in detail below.

DEFAULT Mode

Frame executes as regular call where the caller address is ENTRY_POINT.

VERIFY Mode

Identifies the frame as a validation frame. Its purpose is to verify that a sender and/or payer authorized the transaction. It must call APPROVE during execution. Failure to do so will result in the whole transaction being invalid.

The execution behaves the same as STATICCALL, state cannot be modified.

Frames in this mode will have their data elided from signature hash calculation and from introspection by other frames.

SENDER Mode

Frame executes as regular call where the caller address is sender. This mode effectively acts on behalf of the transaction sender and can only be used after explicitly approved.

Approval Bits

The upper bits (> 8) of mode configure the execution environment.

Constraints

Some validity constraints can be determined statically. They are outlined below:

assert tx.chain_id < 2**256
assert tx.nonce < 2**64
assert len(tx.frames) > 0 and len(tx.frames) <= MAX_FRAMES
assert len(tx.sender) == 20
assert tx.frames[n].mode < 3
assert len(tx.frames[n].target) == 20 or tx.frames[n].target is None

Receipt

The ReceiptPayload is defined as:

[cumulative_gas_used, payer, [frame_receipt, ...]]
frame_receipt = [status, gas_used, logs]

payer is the address of the account that paid the fees for the transaction. status is the return code of the top-level call.

Signature Hash

With the frame transaction, the signature may be at an arbitrary location in the frame list. In the canonical signature hash any frame with mode VERIFY will have its data elided:

def compute_sig_hash(tx: FrameTx) -> Hash:
    for i, frame in enumerate(tx.frames):
        if frame.mode == VERIFY:
            tx.frames[i].data = Bytes()
    return keccak(rlp(tx))

New Opcodes

APPROVE opcode (0xaa)

The APPROVE opcode is like RETURN (0xf3). It exits the current context successfully and updates the transaction-scoped approval context based on the scope operand.

If the currently executing account is not frame.target (i.e. if ADDRESS != frame.target), APPROVE reverts.

Stack

Scope Operand

The scope operand must be one of the following values:

1. 0x0: Approval of execution - the sender contract approves future frames calling on its behalf.
2. Note this is only valid when frame.target equals tx.sender.
3. 0x1: Approval of payment - the contract approves paying the total gas cost for the transaction.
4. 0x2: Approval of execution and payment - combines both 0x0 and 0x1.

Any other value results in an exceptional halt.

Usabe scope operands are constrained by bits 9 and 10 of the frame.mode, and using a non-allowed scope also results in an exceptional halt.

• If (frame.mode>>8) & 3 == 1, only scope 0x0 can be used.
• If (frame.mode>>8) & 3 == 2, only scope 0x1 can be used.
• If (frame.mode>>8) & 3 == 3, scope 0x0, 0x1 or 0x2 can be used.

Behavior

The behavior of APPROVE is defined as follows:

• If ADDRESS != frame.target, revert.
• For scopes 0,1, and 2, execute the following:
  • 0x0: Set sender_approved = true.
    • If sender_approved was already set, revert the frame.
    • If frame.target != tx.sender, revert the frame.
  • 0x1: Increment the sender's nonce, collect the total gas cost of the transaction from the account, and set payer_approved = true.
    • If payer_approved was already set, revert the frame.
    • If frame.target has insufficient balance, revert the frame.
    • If sender_approved == false, revert the frame.
  • 0x2: Set sender_approved = true, increment the sender's nonce, collect the total gas cost of the transaction from frame.target, and set payer_approved = true.
    • If sender_approved or payer_approved was already set, revert the frame.
    • If frame.target != tx.sender, revert the frame.
    • If frame.target has insufficient balance, revert the frame.

TXPARAM opcode

This opcode gives access to information from the transaction header and/or frames. The gas cost of this operation is 2.

It takes two values from the stack, param and in2 (in this order). The param is the field to be extracted from the transaction. in2 names a frame index.

Notes:

• 0x01 has a possible future extension to allow indices for multidimensional nonces.
• 0x03 and 0x04 have a possible future extension to allow indices for multidimensional gas.
• The status field (0x15) returns 0 for failure or 1 for success.
• Invalid param values (not defined in the table above) result in an exceptional halt.
• Out-of-bounds access for frame index (>= len(frames)) results in an exceptional halt.
• Attempting to access the return status of the current frame or a subsequent frame results in an exceptional halt.
• len(data) field (0x14) returns size 0 value when called on a frame with VERIFY set.

FRAMEDATALOAD opcode

This opcode loads one 32-byte word of data from frame input. Gas cost: 3 (matches CALLDATALOAD).

It takes two values from the stack, an offset and frameIndex. It places the retrieved data on the stack.

When the frameIndex is out-of-bounds, an exceptional halt occurs.

The operation sematics match CALLDATALOAD, returning a word of data from the chosen frame's data, starting at the given byte offset. When targeting a frame in VERIFY mode, the returned data is always zero.

FRAMEDATACOPY opcode

This opcode copies data frame input into the contract's memory.The gas cost matches CALLDATACOPY, i.e. the operation has a fixed cost of 3 and a variable cost that accounts for the memory expansion and copying.

It takes four values from the stack: memOffset, dataOffset, length and frameIndex. No stack output value is produced.

When the frameIndex is out-of-bounds, an exceptional halt occurs.

The operation sematics match CALLDATACOPY, copying length bytes from the chosen frame's data, starting at the given byte dataOffset, into a memory region starting at memOffset. When targeting a frame in VERIFY mode, no data is copied.

Behavior

When processing a frame transaction, perform the following steps.

Perform stateful validation check:

• Ensure tx.nonce == state[tx.sender].nonce

Initialize with transaction-scoped variables:

• payer_approved = false
• sender_approved = false

Then for each call frame:

1. Execute a call with the specified mode, target, gas_limit, and data.
2. If target is null, set the call target to tx.sender.
3. If mode is SENDER:
   • sender_approved must be true. If not, the transaction is invalid.
   • Set caller as tx.sender.
4. If mode is DEFAULT or VERIFY:
   • Set the caller to ENTRY_POINT.
5. If frame.target has no code, execute the logic described in default code.
6. The ORIGIN opcode returns frame caller throughout all call depths.
7. If a frame's execution reverts, its state changes are discarded and execution proceeds to the next frame.
8. If frame has mode VERIFY and the frame did not successfully call APPROVE, the transaction is invalid.

After executing all frames, verify that payer_approved == true. If it is, refund any unpaid gas to the gas payer. If it is not, the whole transaction is invalid.

Note:

• It is implied by the handling that the sender must approve the transaction before the payer and that once sender_approved or payer_approved become true they cannot be re-approved or reverted.

Default code

When using frame transactions with EOAs (accounts with no code), they are treated as if they have a "default code." This spec describes only the behavior of the default code; clients are free to implement the default code however they want, so long as they correspond to the behavior specified here.

• Retrieve the mode with TXPARAMLOAD.
• If mode is VERIFY:
• If frame.target != tx.sender, revert.
• Read the first byte of frame.data as two nibbles:
  • Read the first nibble as scope.
  • Read the second nibble as signature_type.
• If signature_type is:
  • 0x0:
  • Read the rest of frame.data as (v, r, s).
  • If frame.target != ecrecover(hash, v, r, s), where hash = keccak(sighash, data_with_out_signature), revert.
  • 0x1:
  • Read the rest of frame.data as (r, s, qx, qy).
  • If frame.target != keccak(qx|qy)[12:], revert.
  • If P256VERIFY(hash, r, s, qx, qy) != true, where hash = keccak(sighash, data_with_out_signature), revert.
  • Otherwise revert.
• Call APPROVE(scope).
• If mode is SENDER:
• If the first nibble of the first byte is not 0x0, revert.
• If frame.target != tx.sender, revert.
• Read the rest of frame.data as RLP encoding of calls = [[target, value, data]].
• For each call in calls, execute the call with msg.sender = tx.sender.
  • If any call reverts, revert the frame.
• If mode is DEFAULT:
• Revert the frame.

Notes:

• data_without_signature means the portion of frame.data without the signature. Note that since signature is always at the very end of frame.data, data_without_signature is always a prefix of frame.data.
• It's implied that for the P256 (r1) signature type, the sender address must be keccak(qx|qy)[12:].

Here's the logic above implemented in Python:

DEFAULT   = 0
VERIFY    = 1
SENDER    = 2

SECP256K1 = 0x0
P256      = 0x1

def default_code(frame, tx):
    mode = frame.mode                     # equivalent to TXPARAMLOAD(0x14, TXPARAMLOAD(0x10))

    if mode == VERIFY:
        if frame.target != tx.sender:
            revert()

        first_byte     = frame.data[0]
        scope          = (first_byte >> 4) & 0xF   # high nibble: APPROVE scope
        signature_type = first_byte & 0xF          # low nibble: signature type
        sig_hash       = compute_sig_hash(tx)      # equivalent to TXPARAMLOAD(0x08)

        if signature_type == SECP256K1:
            # frame.data layout: [byte0, v (1 byte), r (32 bytes), s (32 bytes)]
            if len(frame.data) != 66:             # 1 header + 65 signature bytes
                revert()
            v                = frame.data[1]
            r                = frame.data[2:34]
            s                = frame.data[34:66]
            data_without_sig = frame.data[:-65]   # prefix before (v, r, s)
            h                = keccak256(sig_hash + data_without_sig)
            if frame.target != ecrecover(h, v, r, s):
                revert()

        elif signature_type == P256:
            # frame.data layout: [byte0, r (32 bytes), s (32 bytes), qx (32 bytes), qy (32 bytes)]
            if len(frame.data) != 129:            # 1 header + 128 signature bytes
                revert()
            r                = frame.data[1:33]
            s                = frame.data[33:65]
            qx               = frame.data[65:97]
            qy               = frame.data[97:129]
            data_without_sig = frame.data[:-128]  # prefix before (r, s, qx, qy)
            h                = keccak256(sig_hash + data_without_sig)
            if frame.target != keccak256(qx + qy)[12:]:
                revert()
            if not P256VERIFY(h, r, s, qx, qy):
                revert()

        else:
            revert()

        APPROVE(scope)

    elif mode == SENDER:
        if frame.target != tx.sender:
            revert()

        # frame.data layout: [byte0, RLP-encoded [[target, value, data], ...]]
        calls = rlp_decode(frame.data[1:])
        for call_target, call_value, call_data in calls:
            result = evm_call(caller=tx.sender, to=call_target, value=call_value, data=call_data)
            if result.reverted:
                revert()

    elif mode == DEFAULT:
        revert()

    else:
        revert()

Frame interactions

A few cross-frame interactions to note:

• For the purposes of gas accounting of warm / cold state status, the journal of such touches is shared across frames.
• Discard the TSTORE and TLOAD transient storage between frames.

Gas Accounting

The total gas limit of the transaction is:

tx_gas_limit = FRAME_TX_INTRINSIC_COST + calldata_cost(rlp(tx.frames)) + sum(frame.gas_limit for all frames)

Where calldata_cost is calculated per standard EVM rules (4 gas per zero byte, 16 gas per non-zero byte).

The total fee is defined as:

tx_fee = tx_gas_limit * effective_gas_price + blob_fees
blob_fees = len(blob_versioned_hashes) * GAS_PER_BLOB * blob_base_fee

The effective_gas_price is calculated per EIP-1559 and blob_fees is calculated as per EIP-4844.

Each frame has its own gas_limit allocation. Unused gas from a frame is not available to subsequent frames. After all frames execute, the gas refund is calculated as:

refund = sum(frame.gas_limit for all frames) - total_gas_used

This refund is returned to the gas payer (the target that called APPROVE(0x1) or APPROVE(0x2)) and added back to the block gas pool. Note: This refund mechanism is separate from EIP-3529 storage refunds.

Rationale

Canonical signature hash

The canonical signature hash is provided in TXPARAMLOAD to simplify the development of smart accounts.

Computing the signature hash in EVM is complicated and expensive. While using the canonical signature hash is not mandatory, it is strongly recommended. Creating a bespoke signature requires precise commitment to the underlying transaction data. Without this, it's possible that some elements can be manipulated in-the-air while the transaction is pending and have unexpected effects. This is known as transaction malleability. Using the canonical signature hash avoids malleability of the frames other than VERIFY.

The frame.data of VERIFY frames is elided from the signature hash. This is done for two reasons:

1. It contains the signature so by definition it cannot be part of the signature hash.
2. In the future it may be desired to aggregate the cryptographic operations for data and compute efficiency reasons. If the data was introspectable, it would not be possible to aggregate the verify frames in the future.
3. For gas sponsoring workflows, we also recommend using a VERIFY frame to approve the gas payment. Here, the input data to the sponsor is intentionally left malleable so it can be added onto the transaction after the sender has made its signature. Notably, the frame.target of VERIFY frames is covered by the signature hash, i.e. the sender chooses the sponsor address explicitly.

APPROVE calling convention

Originally APPROVE was meant to extend the space of return statuses from 0 and 1 today to 0 to 4. However, this would mean smart accounts deployed today would not be able to modify their contract code to return with a different value at the top level. For this reason, we've chosen behavior above: APPROVE terminates the executing frame successfully like RETURN, but it actually updates the transaction scoped values sender_approved and payer_approved during execution. It is still required that only the sender can toggle the sender_approved to true. Only the frame.target can call APPROVE generally, because it can allow the transaction pool and other frames to better reason about VERIFY mode frames.

Payer in receipt

The payer cannot be determined statically from a frame transaction and is relevant to users. The only way to provide this information safely and efficiently over the JSON-RPC is to record this data in the receipt object.

No authorization list

The EIP-7702 authorization list heavily relies on ECDSA cryptography to determine the authority of accounts to delegate code. While delegations could be used in other manners later, it does not satisfy the PQ goals of the frame transaction.

No access list

The access list was introduced to address a particular backwards compatibility issue that was caused by EIP-2929. The risk-reward of using an access list successfully is high. A single miss, paying to warm a storage slot that does not end up getting used, causes the overall transaction cost to be greater than had it not been included at all.

Future optimizations based on pre-announcing state elements a transaction will touch will be covered by block level access lists.

No value in frame

It is not required because the account code can send value.

EOA support

While we expect EOA users to migrate to smart accounts eventually, we recognize that most Ethereum users today are using EOAs, so we want to improve UX for them where we can.

With frame transactions, EOA wallets today can reap the key benefit of AA -- gas abstraction, including sending sponsored transactions, paying gas in ERC-20 tokens, and more.

Examples

Example 1: Simple Transaction

Frame 0 verifies the signature and calls APPROVE(0x2) to approve both execution and payment. Frame 1 executes and exits normally via RETURN.

The mempool can process this transaction with the following static validation and call:

• Verify that the first frame is a VERIFY frame.
• Verify that the call of frame 0 succeeds, and does not violate the mempool rules (similar to ERC-7562).

Example 1a: Simple ETH transfer

A simple transfer is performed by instructing the account to send ETH to the destination account. This requires two frames for mempool compatibility, since the validation phase of the transaction has to be static.

This is listed here to illustrate why the transaction type has no built-in value field.

Example 1b: Simple account deployment

This example illustrates the initial deployment flow for a smart account at the sender address. Since the address needs to have code in order to validate the transaction, the transaction must deploy the code before verification.

The first frame would call a deployer contract, like EIP-7997. The deployer determines the address in a deterministic way, such as by hashing the initcode and salt. However, since the transaction sender is not authenticated at this point, the user must choose an initcode which is safe to deploy by anyone.

Example 2: Sponsored Transaction (Fee Payment in ERC-20)

• Frame 0: Verifies signature and calls APPROVE(0x0) to authorize execution from sender.
• Frame 1: Checks that the user has enough ERC-20 tokens, and that the next frame is an ERC-20 send of the right size to the sponsor. Calls APPROVE(0x1) to authorize payment.
• Frame 2: Sends tokens to sponsor.
• Frame 3: User's intended call.
• Frame 4 (optional): Check unpaid gas, refund tokens, possibly convert tokens to ETH on an AMM.

Example 3: EOA paying gas in ERC-20s

• Frame 0: Verify the sender with a EOA signature. Upon verification, the frame calls APPROVE(0x0) to authorize execution.
• Frame 1: Checks that the user has enough ERC-20 tokens, and that the next frame is an ERC-20 send of the right size to the sponsor. Calls APPROVE(0x1) to authorize payment.
• Frame 2: Sends tokens to sponsor.
• Frame 3: User's intended call.

Data Efficiency

Basic transaction sending ETH from a smart account:

Notes: Nonce assumes < 65536 prior sends. Fees assume < 1099 gwei. Validation frame target is 1 byte because target is tx.sender. Validation gas assumes <= 65,536 gas. Calldata is 65 bytes for ECDSA signature. Blob fields assume no blobs (empty list, zero max fee).

This is not much larger than an EIP-1559 transaction; the extra overhead is the need to specify the sender and amount in calldata explicitly.

First transaction from an account (add deployment frame):

Notes: Gas assumes cost < 2^24. Calldata assumes small proxy.

Trustless pay-with-ERC-20 sponsor (add these frames):

Notes: Sponsor can read info from other fields. ERC-20 transfer call is 68 bytes.

There is some inefficiency in the sponsor case, because the same sponsor address must appear in three places (sponsor validation, send to sponsor inside ERC-20 calldata, post op frame), and the ABI is inefficient (~12 + 24 bytes wasted on zeroes). This is difficult to mitigate in a "clean" way, because one of the duplicates is inside the ERC-20 call, "opaque" to the protocol. However, it is much less inefficient than ERC-4337, because not all of the data takes the hit of the 32-byte-per-field ABI overhead.

Backwards Compatibility

The ORIGIN opcode behavior changes for frame transactions, returning the frame's caller rather than the traditional transaction origin. This is consistent with the precedent set by EIP-7702, which already modified ORIGIN semantics. Contracts that rely on ORIGIN = CALLER for security checks (a discouraged pattern) may behave differently under frame transactions.

Security Considerations

Transaction Propagation

Frame transactions introduce new denial-of-service vectors for transaction pools that node operators must mitigate. Because validation logic is arbitrary EVM code, attackers can craft transactions that appear valid during initial validation but become invalid later. Without any additional policies, an attacker could submit many transactions whose validity depends on some shared state, then submit one transaction that modifies that state, and cause all other transactions to become invalid simultaneously. This wastes the computational resources nodes spent validating and storing these transactions.

Example Attack

A simple example is transactions that check block.timestamp:

function validateTransaction() external {
    require(block.timestamp < SOME_DEADLINE, "expired");
    // ... rest of validation
    APPROVE(0x2);
}

Such transactions are valid when submitted but become invalid once the deadline passes, without any on-chain action required from the attacker.

Mitigations

Node implementations should consider restricting which opcodes and storage slots validation frames can access, similar to ERC-7562. This isolates transactions from each other and limits mass invalidation vectors.

It's recommended that to validate the transaction, a specific frame structure is enforced and the amount of gas that is expended executing the validation phase must be limited. Once the frame calls APPROVE(0x2), it can be included in the mempool and propagated to peers safely.

For deployment of the sender account in the first frame, the mempool must only allow specific and known deployer factory contracts to be used as frame.target, to ensure deployment is deterministic and independent of chain state.

In general, it can be assumed that handling of frame transactions imposes similar restrictions as EIP-7702 on mempool relay, i.e. only a single transaction can be pending for an account that uses frame transactions.

Copyright

Copyright and related rights waived via CC0.