Skip to content

Ethereum Execution Spec Tests

Test Excess Blob Gas

execution-spec-tests

Test Excess Blob Gas¶

Documentation for tests/cancun/eip4844_blobs/test_excess_blob_gas.py.

Generate fixtures for these test cases for Cancun with:

Cancun only:

fill -v tests/cancun/eip4844_blobs/test_excess_blob_gas.py --fork=Cancun --evm-bin=/path/to/evm-tool-dev-version

For all forks up to and including Cancun:

fill -v tests/cancun/eip4844_blobs/test_excess_blob_gas.py --until=Cancun --evm-bin=/path/to/evm-tool-dev-version

abstract: Tests excessBlobGas and blobGasUsed block fields for EIP-4844: Shard Blob Transactions

Test `excessBlobGas` and `blobGasUsed` block fields for [EIP-4844: Shard Blob Transactions](https://eips.ethereum.org/EIPS/eip-4844).

note: Adding a new test

Add a function that is named `test_<test_name>` and takes at least the following arguments:

- blockchain_test
- env
- pre
- blocks
- post
- correct_excess_blob_gas

The following arguments *need* to be parametrized or the test will not be generated:

- new_blobs

All other `pytest.fixture` fixtures can be parametrized to generate new combinations and test
cases.

`test_correct_excess_blob_gas_calculation(blockchain_test, env, pre, blocks, post, correct_excess_blob_gas)` ¶

Test calculation of the excessBlobGas increase/decrease across multiple blocks with and without blobs:

With parent block containing [0, MAX_BLOBS_PER_BLOCK] blobs
With parent block containing [0, TARGET_BLOBS_PER_BLOCK] equivalent value of excess blob gas

Source code in tests/cancun/eip4844_blobs/test_excess_blob_gas.py

@pytest.mark.parametrize("parent_blobs", range(0, SpecHelpers.max_blobs_per_block() + 1))
@pytest.mark.parametrize("parent_excess_blobs", range(0, SpecHelpers.target_blobs_per_block() + 1))
@pytest.mark.parametrize("new_blobs", [1])
def test_correct_excess_blob_gas_calculation(
    blockchain_test: BlockchainTestFiller,
    env: Environment,
    pre: Mapping[str, Account],
    blocks: List[Block],
    post: Mapping[str, Account],
    correct_excess_blob_gas: int,
):
    """
    Test calculation of the `excessBlobGas` increase/decrease across
    multiple blocks with and without blobs:

    - With parent block containing `[0, MAX_BLOBS_PER_BLOCK]` blobs
    - With parent block containing `[0, TARGET_BLOBS_PER_BLOCK]` equivalent value of excess blob gas
    """  # noqa: E501
    blockchain_test(
        pre=pre,
        post=post,
        blocks=blocks,
        genesis_environment=env,
        tag=f"expected_excess_blob_gas:{hex(correct_excess_blob_gas)}",
    )

`test_correct_increasing_blob_gas_costs(blockchain_test, env, pre, blocks, post, correct_excess_blob_gas)` ¶

Test calculation of the excessBlobGas and blob gas tx costs at value points where the cost increases to interesting amounts:

At the first blob gas cost increase (1 to 2)
At total transaction data cost increase to > 2^32
At blob gas wei cost increase to > 2^32
At total transaction data cost increase to > 2^64
At blob gas wei cost increase to > 2^64
At blob gas wei cost increase of around current total Ether supply

Source code in tests/cancun/eip4844_blobs/test_excess_blob_gas.py

@pytest.mark.parametrize(
    "parent_excess_blobs",
    [g - 1 for g in BLOB_GAS_COST_INCREASES],
)
@pytest.mark.parametrize("parent_blobs", [SpecHelpers.target_blobs_per_block() + 1])
@pytest.mark.parametrize("new_blobs", [1])
def test_correct_increasing_blob_gas_costs(
    blockchain_test: BlockchainTestFiller,
    env: Environment,
    pre: Mapping[str, Account],
    blocks: List[Block],
    post: Mapping[str, Account],
    correct_excess_blob_gas: int,
):
    """
    Test calculation of the `excessBlobGas` and blob gas tx costs at
    value points where the cost increases to interesting amounts:

    - At the first blob gas cost increase (1 to 2)
    - At total transaction data cost increase to `> 2^32`
    - At blob gas wei cost increase to `> 2^32`
    - At total transaction data cost increase to `> 2^64`
    - At blob gas wei cost increase to `> 2^64`
    - At blob gas wei cost increase of around current total Ether supply
    """
    blockchain_test(
        pre=pre,
        post=post,
        blocks=blocks,
        genesis_environment=env,
        tag=f"expected_excess_blob_gas:{hex(correct_excess_blob_gas)}",
    )

`test_correct_decreasing_blob_gas_costs(blockchain_test, env, pre, blocks, post, correct_excess_blob_gas)` ¶

Test calculation of the excessBlobGas and blob gas tx costs at value points where the cost decreases to interesting amounts.

See test_correct_increasing_blob_gas_costs.

Source code in tests/cancun/eip4844_blobs/test_excess_blob_gas.py

@pytest.mark.parametrize(
    "parent_excess_blobs",
    [g for g in BLOB_GAS_COST_INCREASES],
)
@pytest.mark.parametrize("parent_blobs", [SpecHelpers.target_blobs_per_block() - 1])
@pytest.mark.parametrize("new_blobs", [1])
def test_correct_decreasing_blob_gas_costs(
    blockchain_test: BlockchainTestFiller,
    env: Environment,
    pre: Mapping[str, Account],
    blocks: List[Block],
    post: Mapping[str, Account],
    correct_excess_blob_gas: int,
):
    """
    Test calculation of the `excessBlobGas` and blob gas tx costs at
    value points where the cost decreases to interesting amounts.

    See test_correct_increasing_blob_gas_costs.
    """
    blockchain_test(
        pre=pre,
        post=post,
        blocks=blocks,
        genesis_environment=env,
        tag=f"expected_excess_blob_gas:{hex(correct_excess_blob_gas)}",
    )

`test_invalid_zero_excess_blob_gas_in_header(blockchain_test, env, pre, blocks, correct_excess_blob_gas, header_excess_blob_gas)` ¶

Test rejection of blocks where the excessBlobGas in the header drops to zero in a block with or without data blobs, but the excess blobs in the parent are greater than target.

Source code in tests/cancun/eip4844_blobs/test_excess_blob_gas.py

@pytest.mark.parametrize("header_excess_blob_gas", [0])
@pytest.mark.parametrize("new_blobs", [0, 1])
@pytest.mark.parametrize("parent_blobs", range(0, SpecHelpers.max_blobs_per_block() + 1))
def test_invalid_zero_excess_blob_gas_in_header(
    blockchain_test: BlockchainTestFiller,
    env: Environment,
    pre: Mapping[str, Account],
    blocks: List[Block],
    correct_excess_blob_gas: int,
    header_excess_blob_gas: Optional[int],
):
    """
    Test rejection of blocks where the `excessBlobGas` in the header drops to
    zero in a block with or without data blobs, but the excess blobs in the parent are
    greater than target.
    """
    if header_excess_blob_gas is None:
        raise Exception("test case is badly formatted")

    if header_excess_blob_gas == correct_excess_blob_gas:
        raise Exception("invalid test case")

    blockchain_test(
        pre=pre,
        post={},
        blocks=blocks,
        genesis_environment=env,
        tag="-".join(
            [
                f"correct:{hex(correct_excess_blob_gas)}",
                f"header:{hex(header_excess_blob_gas)}",
            ]
        ),
    )

`test_invalid_blob_gas_used_in_header(blockchain_test, env, pre, blocks, new_blobs, header_blob_gas_used)` ¶

Test rejection of blocks where the blobGasUsed in the header is invalid:

blobGasUsed is not equal to the number of data blobs in the block
blobGasUsed is the max uint64 value

Source code in tests/cancun/eip4844_blobs/test_excess_blob_gas.py

@pytest.mark.parametrize(
    "new_blobs,header_blob_gas_used",
    all_invalid_blob_gas_used_combinations(),
)
@pytest.mark.parametrize("parent_blobs", [0])
def test_invalid_blob_gas_used_in_header(
    blockchain_test: BlockchainTestFiller,
    env: Environment,
    pre: Mapping[str, Account],
    blocks: List[Block],
    new_blobs: int,
    header_blob_gas_used: Optional[int],
):
    """
    Test rejection of blocks where the `blobGasUsed` in the header is invalid:

    - `blobGasUsed` is not equal to the number of data blobs in the block
    - `blobGasUsed` is the max uint64 value
    """
    if header_blob_gas_used is None:
        raise Exception("test case is badly formatted")
    blockchain_test(
        pre=pre,
        post={},
        blocks=blocks,
        genesis_environment=env,
        tag="-".join(
            [
                f"correct:{hex(new_blobs * Spec.GAS_PER_BLOB)}",
                f"header:{hex(header_blob_gas_used)}",
            ]
        ),
    )

`test_invalid_excess_blob_gas_above_target_change(blockchain_test, env, pre, blocks, correct_excess_blob_gas, header_excess_blob_gas)` ¶

Test rejection of blocks where the excessBlobGas

decreases more than TARGET_BLOB_GAS_PER_BLOCK in a single block with zero blobs
increases more than TARGET_BLOB_GAS_PER_BLOCK in a single block with max blobs

Source code in tests/cancun/eip4844_blobs/test_excess_blob_gas.py

@pytest.mark.parametrize(
    "header_excess_blobs_delta,parent_blobs",
    [
        (-1, 0),
        (+1, SpecHelpers.max_blobs_per_block()),
    ],
    ids=["zero_blobs_decrease_more_than_expected", "max_blobs_increase_more_than_expected"],
)
@pytest.mark.parametrize("new_blobs", [1])
def test_invalid_excess_blob_gas_above_target_change(
    blockchain_test: BlockchainTestFiller,
    env: Environment,
    pre: Mapping[str, Account],
    blocks: List[Block],
    correct_excess_blob_gas: int,
    header_excess_blob_gas: Optional[int],
):
    """
    Test rejection of blocks where the `excessBlobGas`

    - decreases more than `TARGET_BLOB_GAS_PER_BLOCK` in a single block with zero blobs
    - increases more than `TARGET_BLOB_GAS_PER_BLOCK` in a single block with max blobs
    """
    if header_excess_blob_gas is None:
        raise Exception("test case is badly formatted")

    if header_excess_blob_gas == correct_excess_blob_gas:
        raise Exception("invalid test case")

    blockchain_test(
        pre=pre,
        post={},
        blocks=blocks,
        genesis_environment=env,
        tag="-".join(
            [
                f"correct:{hex(correct_excess_blob_gas)}",
                f"header:{hex(header_excess_blob_gas)}",
            ]
        ),
    )

`test_invalid_static_excess_blob_gas(blockchain_test, env, pre, blocks, correct_excess_blob_gas, parent_excess_blob_gas)` ¶

Test rejection of blocks where the excessBlobGas remains unchanged but the parent blobs included are not TARGET_BLOBS_PER_BLOCK.

Test is parametrized to MAX_BLOBS_PER_BLOCK and TARGET_BLOBS_PER_BLOCK.

Source code in tests/cancun/eip4844_blobs/test_excess_blob_gas.py

@pytest.mark.parametrize(
    "parent_blobs",
    [
        b
        for b in range(0, SpecHelpers.max_blobs_per_block() + 1)
        if b != SpecHelpers.target_blobs_per_block()
    ],
)
@pytest.mark.parametrize("parent_excess_blobs", [1, SpecHelpers.target_blobs_per_block()])
@pytest.mark.parametrize("new_blobs", [1])
def test_invalid_static_excess_blob_gas(
    blockchain_test: BlockchainTestFiller,
    env: Environment,
    pre: Mapping[str, Account],
    blocks: List[Block],
    correct_excess_blob_gas: int,
    parent_excess_blob_gas: int,
):
    """
    Test rejection of blocks where the `excessBlobGas` remains unchanged
    but the parent blobs included are not `TARGET_BLOBS_PER_BLOCK`.

    Test is parametrized to `MAX_BLOBS_PER_BLOCK` and `TARGET_BLOBS_PER_BLOCK`.
    """
    blocks[-1].rlp_modifier = Header(excess_blob_gas=parent_excess_blob_gas)
    blocks[-1].header_verify = None
    blocks[-1].exception = "invalid excess blob gas"
    blockchain_test(
        pre=pre,
        post={},
        blocks=blocks,
        genesis_environment=env,
        tag="-".join(
            [
                f"correct:{hex(correct_excess_blob_gas)}",
                f"header:{hex(parent_excess_blob_gas)}",
            ]
        ),
    )

`test_invalid_excess_blob_gas_target_blobs_increase_from_zero(blockchain_test, env, pre, blocks, correct_excess_blob_gas, header_excess_blob_gas)` ¶

Test rejection of blocks where the excessBlobGas increases from zero, even when the included blobs are on or below target.

Test is parametrized according to [0, TARGET_BLOBS_PER_BLOCK new blobs.

Source code in tests/cancun/eip4844_blobs/test_excess_blob_gas.py

@pytest.mark.parametrize("header_excess_blobs_delta", range(1, SpecHelpers.max_blobs_per_block()))
@pytest.mark.parametrize("parent_blobs", range(0, SpecHelpers.target_blobs_per_block() + 1))
@pytest.mark.parametrize("parent_excess_blobs", [0])  # Start at 0
@pytest.mark.parametrize("new_blobs", [1])
def test_invalid_excess_blob_gas_target_blobs_increase_from_zero(
    blockchain_test: BlockchainTestFiller,
    env: Environment,
    pre: Mapping[str, Account],
    blocks: List[Block],
    correct_excess_blob_gas: int,
    header_excess_blob_gas: Optional[int],
):
    """
    Test rejection of blocks where the `excessBlobGas` increases from zero,
    even when the included blobs are on or below target.

    Test is parametrized according to `[0, TARGET_BLOBS_PER_BLOCK` new blobs.
    """
    if header_excess_blob_gas is None:
        raise Exception("test case is badly formatted")

    if header_excess_blob_gas == correct_excess_blob_gas:
        raise Exception("invalid test case")

    blockchain_test(
        pre=pre,
        post={},
        blocks=blocks,
        genesis_environment=env,
        tag="-".join(
            [
                f"correct:{hex(correct_excess_blob_gas)}",
                f"header:{hex(header_excess_blob_gas)}",
            ]
        ),
    )

`test_invalid_static_excess_blob_gas_from_zero_on_blobs_above_target(blockchain_test, env, pre, blocks, correct_excess_blob_gas, header_excess_blob_gas)` ¶

Test rejection of blocks where the excessBlobGas does not increase from zero, even when the included blobs is above target.

Test is parametrized to [TARGET_BLOBS_PER_BLOCK+1, MAX_BLOBS_PER_BLOCK] new blobs.

Source code in tests/cancun/eip4844_blobs/test_excess_blob_gas.py

@pytest.mark.parametrize("header_excess_blob_gas", [0])
@pytest.mark.parametrize(
    "parent_blobs",
    range(SpecHelpers.target_blobs_per_block() + 1, SpecHelpers.max_blobs_per_block() + 1),
)
@pytest.mark.parametrize("parent_excess_blobs", [0])  # Start at 0
@pytest.mark.parametrize("new_blobs", [1])
def test_invalid_static_excess_blob_gas_from_zero_on_blobs_above_target(
    blockchain_test: BlockchainTestFiller,
    env: Environment,
    pre: Mapping[str, Account],
    blocks: List[Block],
    correct_excess_blob_gas: int,
    header_excess_blob_gas: Optional[int],
):
    """
    Test rejection of blocks where the `excessBlobGas` does not increase from
    zero, even when the included blobs is above target.

    Test is parametrized to `[TARGET_BLOBS_PER_BLOCK+1, MAX_BLOBS_PER_BLOCK]` new blobs.
    """
    if header_excess_blob_gas is None:
        raise Exception("test case is badly formatted")

    if header_excess_blob_gas == correct_excess_blob_gas:
        raise Exception("invalid test case")

    blockchain_test(
        pre=pre,
        post={},
        blocks=blocks,
        genesis_environment=env,
        tag="-".join(
            [
                f"correct:{hex(correct_excess_blob_gas)}",
                f"header:{hex(header_excess_blob_gas)}",
            ]
        ),
    )

`test_invalid_excess_blob_gas_change(blockchain_test, env, pre, blocks, correct_excess_blob_gas, header_excess_blob_gas)` ¶

Test rejection of blocks where the excessBlobGas changes to an invalid value.

Given a parent block containing [0, MAX_BLOBS_PER_BLOCK] blobs, test an invalid excessBlobGas value by changing it by [-TARGET_BLOBS_PER_BLOCK, TARGET_BLOBS_PER_BLOCK] from the correct value.

Source code in tests/cancun/eip4844_blobs/test_excess_blob_gas.py

@pytest.mark.parametrize(
    "parent_blobs,header_excess_blobs_delta",
    itertools.product(
        # parent_blobs
        range(0, SpecHelpers.max_blobs_per_block() + 1),
        # header_excess_blobs_delta (from correct value)
        [
            x
            for x in range(
                -SpecHelpers.target_blobs_per_block(), SpecHelpers.target_blobs_per_block() + 1
            )
            if x != 0
        ],
    ),
)
@pytest.mark.parametrize("new_blobs", [1])
def test_invalid_excess_blob_gas_change(
    blockchain_test: BlockchainTestFiller,
    env: Environment,
    pre: Mapping[str, Account],
    blocks: List[Block],
    correct_excess_blob_gas: int,
    header_excess_blob_gas: Optional[int],
):
    """
    Test rejection of blocks where the `excessBlobGas` changes to an invalid
    value.

    Given a parent block containing `[0, MAX_BLOBS_PER_BLOCK]` blobs, test an invalid
    `excessBlobGas` value by changing it by `[-TARGET_BLOBS_PER_BLOCK, TARGET_BLOBS_PER_BLOCK]`
    from the correct value.
    """
    if header_excess_blob_gas is None:
        raise Exception("test case is badly formatted")

    if header_excess_blob_gas == correct_excess_blob_gas:
        raise Exception("invalid test case")

    blockchain_test(
        pre=pre,
        post={},
        blocks=blocks,
        genesis_environment=env,
        tag="-".join(
            [
                f"correct:{hex(correct_excess_blob_gas)}",
                f"header:{hex(header_excess_blob_gas)}",
            ]
        ),
    )

`test_invalid_negative_excess_blob_gas(blockchain_test, env, pre, blocks, correct_excess_blob_gas, header_excess_blob_gas)` ¶

Test rejection of blocks where the excessBlobGas changes to the two's complement equivalent of the negative value after subtracting target blobs.

Reasoning is that the excessBlobGas is a uint64, so it cannot be negative, and we test for a potential underflow here.

Source code in tests/cancun/eip4844_blobs/test_excess_blob_gas.py

@pytest.mark.parametrize(
    "header_excess_blob_gas",
    [(2**64 + (x * Spec.GAS_PER_BLOB)) for x in range(-SpecHelpers.target_blobs_per_block(), 0)],
)
@pytest.mark.parametrize("parent_blobs", range(SpecHelpers.target_blobs_per_block()))
@pytest.mark.parametrize("new_blobs", [1])
@pytest.mark.parametrize("parent_excess_blobs", range(SpecHelpers.target_blobs_per_block()))
def test_invalid_negative_excess_blob_gas(
    blockchain_test: BlockchainTestFiller,
    env: Environment,
    pre: Mapping[str, Account],
    blocks: List[Block],
    correct_excess_blob_gas: int,
    header_excess_blob_gas: Optional[int],
):
    """
    Test rejection of blocks where the `excessBlobGas` changes to the two's
    complement equivalent of the negative value after subtracting target blobs.

    Reasoning is that the `excessBlobGas` is a `uint64`, so it cannot be negative, and
    we test for a potential underflow here.
    """
    if header_excess_blob_gas is None:
        raise Exception("test case is badly formatted")

    if header_excess_blob_gas == correct_excess_blob_gas:
        raise Exception("invalid test case")

    blockchain_test(
        pre=pre,
        post={},
        blocks=blocks,
        genesis_environment=env,
        tag="-".join(
            [
                f"correct:{hex(correct_excess_blob_gas)}",
                f"header:{hex(header_excess_blob_gas)}",
            ]
        ),
    )

`test_invalid_non_multiple_excess_blob_gas(blockchain_test, env, pre, blocks, correct_excess_blob_gas, header_excess_blob_gas)` ¶

Test rejection of blocks where the excessBlobGas changes to a value that is not a multiple of Spec.GAS_PER_BLOB`:

Parent block contains TARGET_BLOBS_PER_BLOCK + 1 blobs, but excessBlobGas is off by ±1
Parent block contains TARGET_BLOBS_PER_BLOCK - 1 blobs, but excessBlobGas is off by ±1

Source code in tests/cancun/eip4844_blobs/test_excess_blob_gas.py

@pytest.mark.parametrize(
    "parent_blobs,header_excess_blob_gas_delta",
    [
        (SpecHelpers.target_blobs_per_block() + 1, 1),
        (SpecHelpers.target_blobs_per_block() + 1, Spec.GAS_PER_BLOB - 1),
        (SpecHelpers.target_blobs_per_block() - 1, -1),
        (SpecHelpers.target_blobs_per_block() - 1, -(Spec.GAS_PER_BLOB - 1)),
    ],
)
@pytest.mark.parametrize("new_blobs", [1])
@pytest.mark.parametrize("parent_excess_blobs", [SpecHelpers.target_blobs_per_block() + 1])
def test_invalid_non_multiple_excess_blob_gas(
    blockchain_test: BlockchainTestFiller,
    env: Environment,
    pre: Mapping[str, Account],
    blocks: List[Block],
    correct_excess_blob_gas: int,
    header_excess_blob_gas: Optional[int],
):
    """
    Test rejection of blocks where the `excessBlobGas` changes to a value that
    is not a multiple of Spec.GAS_PER_BLOB`:

    - Parent block contains `TARGET_BLOBS_PER_BLOCK + 1` blobs, but `excessBlobGas` is off by +/-1
    - Parent block contains `TARGET_BLOBS_PER_BLOCK - 1` blobs, but `excessBlobGas` is off by +/-1
    """
    if header_excess_blob_gas is None:
        raise Exception("test case is badly formatted")

    if header_excess_blob_gas == correct_excess_blob_gas:
        raise Exception("invalid test case")

    blockchain_test(
        pre=pre,
        post={},
        blocks=blocks,
        genesis_environment=env,
        tag="-".join(
            [
                f"correct:{hex(correct_excess_blob_gas)}",
                f"header:{hex(header_excess_blob_gas)}",
            ]
        ),
    )