Ethereum Execution Specs

https://steel.ethereum.foundation/docs/execution-specs/
Admin
This project provides the formal specifications for the Ethereum execution layer, detailing EIPs,...
Tokens:1,485,021
Snippets:16,091
Trust Score:9.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Transaction Environment Setup

Source: https://steel.ethereum.foundation/docs/execution-specs/specs/reference/diffs/bpo4/bpo5/fork.py.html

Creates the transaction environment for execution.

```python
tx_env = vm.TransactionEnvironment(
    origin=sender,
    gas_price=effective_gas_price,
    gas=gas,
    access_list_addresses=access_list_addresses,
    access_list_storage_keys=access_list_storage_keys,
    state=tx_state,
    blob_versioned_hashes=blob_versioned_hashes,
    authorizations=authorizations,
    index_in_block=index,
    tx_hash=get_transaction_hash(encode_transaction(tx)),
)
```

--------------------------------

### Start interactive ipython session

Source: https://steel.ethereum.foundation/docs/execution-specs/dev/interactive_usage

Launches an ipython shell with EEST packages installed in editable mode.

```bash
uvx  --with-editable . ipython
```

--------------------------------

### Consume with Release Specifications

Source: https://steel.ethereum.foundation/docs/execution-specs/running_tests/consume/cache

Examples of using release names and versions to specify test fixtures.

```bash
# Latest mainnet (tests) release
uv run consume engine --input latest
uv run consume rlp --input tests@latest

# Mainnet release by version
uv run consume engine --input v20.0.0
uv run consume rlp --input tests@v20.0.0

# Feature releases, with or without the tests- tag prefix
uv run consume cache --input bal-devnet@v7.0.0
uv run consume cache --input glamsterdam-devnet@latest
uv run consume direct --input tests-bal@v7.3.2 --bin ../go-ethereum/build/bin/evm
```

--------------------------------

### Test specific network clients

Source: https://steel.ethereum.foundation/docs/execution-specs/running_tests/execute/eth_config

Examples for testing Mainnet and Sepolia clients.

```bash
uv run execute eth-config --network Mainnet --rpc-endpoint http://localhost:8545
```

```bash
uv run execute eth-config --network Sepolia --rpc-endpoint http://localhost:8545
```

--------------------------------

### Consume with URL Fixtures

Source: https://steel.ethereum.foundation/docs/execution-specs/running_tests/consume/cache

Examples of using direct URLs to .tar.gz archives for test fixtures.

```bash
# GitHub release URL
uv run consume engine --input https://github.com/ethereum/execution-specs/releases/download/tests%40v20.0.0/fixtures.tar.gz

# Direct archive URL
uv run consume rlp --input https://example.com/custom-fixtures.tar.gz
```

--------------------------------

### Serve Documentation Locally

Source: https://steel.ethereum.foundation/docs/execution-specs/dev/docs

Starts a local development server with live reloading. Use the fast variant to skip the Test Case Reference generation.

```bash
just docs-serve        # full build
just docs-serve-fast   # skips the Test Case Reference, faster iteration
```

--------------------------------

### Extracting Configurations from Fixtures

Source: https://steel.ethereum.foundation/docs/execution-specs/library/cli/extract_config

Examples demonstrating how to target specific fixtures, individual clients, or entire directories.

```bash
uv run extract_config --fixture fixtures/blockchain_tests/paris/security/test_selfdestruct_balance_bug.json
```

```bash
uv run extract_config --fixture fixtures/blockchain_tests/paris/security/test_selfdestruct_balance_bug.json --client besu
```

```bash
uv run extract_config --fixture fixtures/blockchain_tests/paris/security/
```

```bash
uv run extract_config --fixture my_fixture.json --output ./my_configs --list-files
```

--------------------------------

### Example Block Structure

Source: https://steel.ethereum.foundation/docs/execution-specs/writing_tests/tutorials/blockchain

An example of the resulting block list structure.

```python
blocks = [
    Blocks(txs=[]),
    Blocks(txs=[next(tx_generator), next(tx_generator)]),
    Blocks(txs=[next(tx_generator), next(tx_generator), next(tx_generator), next(tx_generator)])        
]
```

--------------------------------

### Test with custom configuration

Source: https://steel.ethereum.foundation/docs/execution-specs/running_tests/execute/eth_config

Use a custom network configuration file or genesis source.

```bash
uv run execute eth-config --network MyCustomNet --rpc-endpoint http://localhost:8545 --network-config-file ./my-networks.yml
```

```bash
uv run execute eth-config --genesis-config-file ./genesis.json --rpc-endpoint http://localhost:8545
```

```bash
uv run execute eth-config --genesis-config-url https://example.com/genesis.json --rpc-endpoint http://localhost:8545
```

--------------------------------

### Install act extension

Source: https://steel.ethereum.foundation/docs/execution-specs/dev/test_actions_locally

Installs the nektos/act tool as a Github CLI extension.

```bash
gh extension install https://github.com/nektos/gh-act
```

--------------------------------

### Define memory input start position

Source: https://steel.ethereum.foundation/docs/execution-specs/specs/reference/diffs/paris/shanghai/vm/instructions/system.py.html

Represents the starting memory address for input data.

```python
memory_input_start_position: U256
```

--------------------------------

### Define memory output start position

Source: https://steel.ethereum.foundation/docs/execution-specs/specs/reference/diffs/arrow_glacier/gray_glacier/vm/instructions/system.py.html

Represents the starting position in memory for output data.

```python
memory_output_start_position: U256
```

--------------------------------

### Initialize environment configuration

Source: https://steel.ethereum.foundation/docs/execution-specs/dev/configurations

Use the CLI tool to generate the local env.yaml file.

```bash
uv run eest make env
🎉 Success! Config file created at: <path>/env.yaml
```

--------------------------------

### Install uv package manager

Source: https://steel.ethereum.foundation/docs/execution-specs/running_tests/consume/cache

Installs the uv Python package manager via a shell script.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Checklist Output Format Example

Source: https://steel.ethereum.foundation/docs/execution-specs/writing_tests/eip_checklist

An example of the generated markdown output showing progress tracking and item status.

```markdown
# EIP-7702 Test Checklist

## Checklist Progress Tracker

| Total Checklist Items | Covered Checklist Items | Percentage |
| --------------------- | ----------------------- | ---------- |
| 45 | 32 | 🟡 71.11% |

## General

#### Code coverage

| ID | Description | Status | Tests |
| -- | ----------- | ------ | ----- |
| `general/code_coverage/eels` | Run produced tests against EELS... | ✅ | Covered by EELS test suite |
| `general/code_coverage/test_coverage` | Run coverage on the test code itself... | ✅ | `tests/prague/eip7702_set_code_tx/test_set_code_txs.py::test_set_code_txs` |

## Transaction Type

| ID | Description | Status | Tests |
| -- | ----------- | ------ | ----- |
| `transaction_type/test/intrinsic_validity/gas_limit/exact` | Provide the exact intrinsic gas... | ✅ | `tests/prague/eip7702_set_code_tx/test_checklist_example.py::test_exact_intrinsic_gas` |
| `transaction_type/test/intrinsic_validity/gas_limit/insufficient` | Provide the exact intrinsic gas minus one... |  |  |

## System Contract

| ID | Description | Status | Tests |
| -- | ----------- | ------ | ----- |
| `system_contract/test/deployment/missing` | Verify block execution behavior... | N/A | EIP-7702 does not introduce a system contract |
```

--------------------------------

### Example env.yaml structure

Source: https://steel.ethereum.foundation/docs/execution-specs/dev/configurations

The environment configuration file supports remote node definitions and RPC headers.

```yaml
remote_nodes:
  - name: mainnet_archive
    # Replace with your Ethereum RPC node URL
    node_url: http://example.com
    # Optional: Headers for RPC requests
    rpc_headers:
      client-secret: <secret>
```

--------------------------------

### Transaction Delegation Installation Test Case

Source: https://steel.ethereum.foundation/docs/execution-specs/tests/amsterdam/eip2780_reduce_intrinsic_tx_gas/test_value_moving_with_tx_delegation/test_tx_installs_delegation_on_funded_recipient

Defines the post-state expectations for a transaction that installs a delegation designation on a funded recipient account.

```python
    post = {
        sender: Account(nonce=1, balance=sender_final_balance),
        target: Account(
            nonce=1,
            balance=target_initial_balance + value,
            code=Spec7702.delegation_designation(delegated_to),
        ),
    }

    state_test(pre=pre, tx=tx, post=post)
```

--------------------------------

### Expected output for fixture download

Source: https://steel.ethereum.foundation/docs/execution-specs/running_tests/consume/cache

Example output showing the cached path and source URL for a fixture release.

```text
Path: /home/dtopz/.cache/ethereum-execution-spec-tests/cached_downloads/ethereum/execution-specs/tests%40v20.0.0/fixtures/fixtures
Input: https://github.com/ethereum/execution-specs/releases/download/tests%40v20.0.0/fixtures.tar.gz
Release page: https://github.com/ethereum/execution-specs/releases/tag/tests%40v20.0.0
```

--------------------------------

### Verify Delegation Installation on Empty Recipient

Source: https://steel.ethereum.foundation/docs/execution-specs/tests/amsterdam/eip2780_reduce_intrinsic_tx_gas/test_value_moving_with_tx_delegation/test_tx_installs_delegation_on_empty_recipient

Defines the post-state expectation for a transaction that installs a delegation designation on an empty recipient account.

```python
    post = {
        sender: Account(nonce=1, balance=sender_final_balance),
        target: Account(
            nonce=1,
            balance=value,
            code=Spec7702.delegation_designation(delegated_to),
        ),
    }

    state_test(pre=pre, tx=tx, post=post)
```

--------------------------------

### Sync Project Dependencies

Source: https://steel.ethereum.foundation/docs/execution-specs/dev/docs

Initializes the project environment by syncing dependencies.

```bash
uv sync
```

--------------------------------

### Test implementation for delegation installation

Source: https://steel.ethereum.foundation/docs/execution-specs/tests/amsterdam/eip2780_reduce_intrinsic_tx_gas/test_value_moving_with_tx_delegation/test_tx_installs_delegation_on_funded_recipient

The test function sets up a funded EOA recipient and verifies gas costs for installing delegation via a type-4 transaction.

```python
@pytest.mark.parametrize(
    "value",
    [
        pytest.param(0, id="zero_value"),
        pytest.param(1, id="non-zero_value"),
    ],
)
def test_tx_installs_delegation_on_funded_recipient(
    fork: Fork,
    pre: Alloc,
    state_test: StateTestFiller,
    value: int,
) -> None:
    """
    Scenario 1: ``tx.to`` is a funded EOA with no prior delegation.
    The type-4 transaction's authorization installs delegation on
    ``tx.to``.

    The authority (``tx.to``) already exists, so it pays no
    ``NEW_ACCOUNT``; it has no prior code, so writing the delegation
    indicator pays ``AUTH_BASE``. Whether it pays ``ACCOUNT_WRITE``
    depends on the value transfer: with ``zero_value`` the delegation
    write is the transaction's first write to ``tx.to`` and
    ``ACCOUNT_WRITE`` is charged; with ``non-zero_value`` the
    transaction already pays to write ``tx.to`` when it transfers value
    to it, so no ``ACCOUNT_WRITE`` accrues. The top-frame
    ``COLD_ACCOUNT_ACCESS`` charge for the now-delegated recipient (its
    fresh delegation target is cold) still fires.
    """
    sender_initial_balance = 10**18
    sender = pre.fund_eoa(sender_initial_balance)

    target_initial_balance = 100
    target = pre.fund_eoa(amount=target_initial_balance)
    delegated_to = pre.deploy_contract(code=Op.STOP)

    auth = AuthorizationTuple(
        address=delegated_to,
        nonce=0,
        signer=target,
        # Funded authority already exists, so no NEW_ACCOUNT.
        creates_account=False,
        first_write=not bool(value),
    )
    authorization_list = [auth]

    # Intrinsic sees the recipient in its pre-tx form (funded EOA); the
    # delegation only surfaces at the top-frame check.
    intrinsic_gas = fork.transaction_intrinsic_cost_calculator()(
        sends_value=bool(value),
        recipient_type=RecipientType.EOA,
        authorization_list_or_count=authorization_list,
        return_cost_deducted_prior_execution=True,
    )
    top_frame_regular = fork.transaction_top_frame_gas_calculator()(
        sends_value=bool(value),
        recipient_type=RecipientType.DELEGATION_7702,
        delegation_warm=False,
        authorizations=authorization_list,
    )
    top_frame_state = fork.transaction_top_frame_state_gas(
        sends_value=bool(value),
        recipient_type=RecipientType.DELEGATION_7702,
        authorizations=authorization_list,
    )

    # Costs are charged exactly (no refund); under the default zero
    # state-gas reservoir the state gas spills into regular gas.
    total_gas_cost = intrinsic_gas + top_frame_regular + top_frame_state
    tx_gas_limit = total_gas_cost + 1000
    gas_price = 1_000_000_000

    tx = Transaction(
        sender=sender,
        to=target,
        value=value,
        authorization_list=authorization_list,
        gas_limit=tx_gas_limit,
        max_fee_per_gas=gas_price,
        max_priority_fee_per_gas=gas_price,
    )

    sender_final_balance = (
        sender_initial_balance - value - (total_gas_cost * gas_price)
    )
```

--------------------------------

### Run state tests with different clients

Source: https://steel.ethereum.foundation/docs/execution-specs/running_tests/consume/direct

Examples of running state tests from a local fixtures folder using various supported client binaries.

```bash
uv run consume direct --input ./fixtures -m state_test --bin=evm
```

```bash
uv run consume direct --input ./fixtures -m state_test --bin=evmtool
```

```bash
uv run consume direct --input ./fixtures -m state_test --bin=nethtest
```

```bash
uv run consume direct --input ./fixtures --bin=evmone-statetest --bin=evmone-blockchaintest
```

--------------------------------

### Initialize EVM state and execution environment

Source: https://steel.ethereum.foundation/docs/execution-specs/specs/reference/diffs/byzantium/constantinople/vm/interpreter.py.html

Sets up the initial EVM state, including stack, memory, and jump destinations.

```python
tx_state = message.tx_env.state
if message.depth > STACK_DEPTH_LIMIT:
    raise StackDepthLimitError("Stack depth limit reached")
code = message.code
valid_jump_destinations = get_valid_jump_destinations(code)
evm = Evm(
    pc=Uint(0),
    stack=[],
    memory=bytearray(),
    code=code,
    gas_left=message.gas,
    valid_jump_destinations=valid_jump_destinations,
    logs=(),
    refund_counter=0,
    running=True,
    message=message,
    output=b"",
    accounts_to_delete=set(),
    touched_accounts=set(),
    return_data=b"",
    error=None,
)
```

--------------------------------

### Get Sigma Length

Source: https://steel.ethereum.foundation/docs/execution-specs/specs/reference/src/ethereum/crypto/blake2.py.html

Retrieves the length of the sigma parameter.

```python
@property
def sigma_len(self) -> int:
    return len(self.sigma)
```

--------------------------------

### Create Instruction

Source: https://steel.ethereum.foundation/docs/execution-specs/specs/reference/diffs/paris/shanghai/vm/instructions/system.py.html

Creates a new account with associated code.

```python
def create(evm: Evm) -> None:
```

```python
# STACK
endowment = pop(evm.stack)
memory_start_position = pop(evm.stack)
memory_size = pop(evm.stack)

# GAS
extend_memory = calculate_gas_extend_memory(
    evm.memory, [(memory_start_position, memory_size)]
)
init_code_gas = init_code_cost(Uint(memory_size))
```

--------------------------------

### Get test ID

Source: https://steel.ethereum.foundation/docs/execution-specs/library/execution_testing_fixtures

Returns the unique identifier for the test.

```python
def get_id(self) -> str:
    """Return the test id."""
    return self.id
```

--------------------------------

### Run eth-config standalone

Source: https://steel.ethereum.foundation/docs/execution-specs/running_tests/execute/eth_config

Execute the command directly without cloning the repository by using uv.

```bash
uv run --with "git+https://github.com/ethereum/execution-specs.git#subdirectory=packages/testing" execute eth-config --network Mainnet --rpc-endpoint http://<ETH_RPC_ENDPOINT>
```

--------------------------------

### CREATE Instruction Implementation

Source: https://steel.ethereum.foundation/docs/execution-specs/specs/reference/diffs/arrow_glacier/gray_glacier/vm/instructions/system.py.html

Handles the creation of a new account using the CREATE opcode logic.

```python
def create(evm: Evm) -> None:
```

```python
# STACK
endowment = pop(evm.stack)
memory_start_position = pop(evm.stack)
memory_size = pop(evm.stack)
```

```python
# GAS
extend_memory = calculate_gas_extend_memory(
    evm.memory, [(memory_start_position, memory_size)]
)
```

```python
charge_gas(evm, GasCosts.OPCODE_CREATE_BASE + extend_memory.cost)
```

```python
# OPERATION
evm.memory += b"\x00" * extend_memory.expand_by
contract_address = compute_contract_address(
    evm.message.current_target,
    get_account(
        evm.message.tx_env.state, evm.message.current_target
    ).nonce,
)
```

```python
generic_create(
    evm, endowment, contract_address, memory_start_position, memory_size
)
```

```python
# PROGRAM COUNTER
evm.pc += Uint(1)
```

--------------------------------

### Check for Hex Prefix

Source: https://steel.ethereum.foundation/docs/execution-specs/specs/reference/src/ethereum/utils/hexadecimal.py.html

Determines if a string starts with the '0x' prefix.

```python
return hex_string.startswith("0x")
```

--------------------------------

### Define InvalidContractPrefix Exception

Source: https://steel.ethereum.foundation/docs/execution-specs/specs/reference/diffs/arrow_glacier/gray_glacier/vm/exceptions.py.html

Raised when contract code starts with 0xEF.

```python
class InvalidContractPrefix:
```

--------------------------------

### CREATE Instruction Implementation

Source: https://steel.ethereum.foundation/docs/execution-specs/specs/reference/diffs/osaka/bpo1/vm/instructions/system.py.html

Handles the creation of a new account based on the sender's nonce.

```python
charge_gas(
    evm,
    GasCosts.OPCODE_CREATE_BASE + extend_memory.cost + init_code_gas,
)
```

```python
evm.memory += b"\x00" * extend_memory.expand_by
contract_address = compute_contract_address(
    evm.message.current_target,
    get_account(
        evm.message.tx_env.state, evm.message.current_target
    ).nonce,
)
```

```python
generic_create(
    evm,
    endowment,
    contract_address,
    memory_start_position,
    memory_size,
)
```

```python
evm.pc += Uint(1)
```

--------------------------------

### Parameter execution results

Source: https://steel.ethereum.foundation/docs/execution-specs/library/execution_testing_tools

Expected parameter sets resulting from the extend_with_defaults example.

```text
"default_case": {"min_value": 0, "max_value": 100, "average": 50}
"min_value_10": {"min_value": 10, "max_value": 100, "average": 50}
"max_value_200": {"min_value": 0, "max_value": 200, "average": 50}
"min_-10_max_50": {"min_value": -10, "max_value": 50, "average": 50}
"min_20_max_80_avg_50": {"min_value": 20, "max_value": 80, "average": 50}
# expected to fail
"invalid_range": {"min_value": 100, "max_value": 0, "average": 50}
```

--------------------------------

### Initialize Access List

Source: https://steel.ethereum.foundation/docs/execution-specs/specs/reference/diffs/cancun/prague/fork.py.html

Sets up the initial access list structures for addresses and storage keys.

```python
access_list_addresses = set()
```

```python
access_list_storage_keys = set()
```

```python
access_list_addresses.add(block_env.coinbase)
```

--------------------------------

### Build and Verify Documentation

Source: https://steel.ethereum.foundation/docs/execution-specs/dev/docs

Commands to build the documentation, run spellchecks, and lint markdown files.

```bash
just docs
```

```bash
just spellcheck
just lint-md
just docs
```

--------------------------------

### Build solc from Source on ARM

Source: https://steel.ethereum.foundation/docs/execution-specs/getting_started/installation_troubleshooting

Steps to build the Solidity compiler from source to resolve compilation failures on ARM platforms.

```bash
git clone --branch v0.8.28 --depth 1 https://github.com/ethereum/solidity.git
cd solidity && mkdir build && cd build
sudo apt install build-essential libboost-all-dev z3
cmake ..
make
mv $HOME/Documents/execution-specs/.venv/bin/solc $HOME/Documents/execution-specs/.venv/bin/solc-x86-64
cp ./solc/solc $HOME/Documents/execution-specs/.venv/bin/
chmod +x $HOME/Documents/execution-specs/.venv/bin/solc
```

--------------------------------

### Clean Generated Files

Source: https://steel.ethereum.foundation/docs/execution-specs/library/cli/eest

Commands and examples for cleaning generated files and directories.

```text
dry_run (bool): Simulate the cleanup without removing files.

verbose (bool): Show verbose output.
```

```bash
uv run eest clean --all -v
```

```text
🗑️  Deleted: .just
🗑️  Deleted: .venv
🗑️  Deleted: src/cli/et/__pycache__
🗑️  Deleted: src/cli/et/commands/__pycache__
🗑️  Deleted: src/cli/et/make/__pycache__
🗑️  Deleted: src/cli/et/make/commands/__pycache__
...
🧹 Cleanup complete!
```

```bash
eest clean [OPTIONS]
```

```bash
--all          Remove the virtual environment and .just directories as well.
  --dry-run      Simulate the cleanup without removing files.
  -v, --verbose  Show verbose output.
  -h, --help     Show this message and exit.
```

--------------------------------

### Build the Hive command-line tool

Source: https://steel.ethereum.foundation/docs/execution-specs/running_tests/hive

Clone the repository and compile the Hive binary using the Go toolchain.

```bash
git clone https://github.com/ethereum/hive
cd hive
go build .
```

--------------------------------

### Define TransactionStart Trace Event

Source: https://steel.ethereum.foundation/docs/execution-specs/specs/reference/src/ethereum/trace.py.html

Defines the event triggered at the start of a transaction.

```python
@final
@dataclass
class TransactionStart:
```
Tokens:
Raw