test_reservoir_settlement_by_failure_point()

Documentation for tests/amsterdam/eip2780_reduce_intrinsic_tx_gas/test_authorization_oog.py::test_reservoir_settlement_by_failure_point@26332146.

Generate fixtures for these test cases for Amsterdam with:

fill -v tests/amsterdam/eip2780_reduce_intrinsic_tx_gas/test_authorization_oog.py::test_reservoir_settlement_by_failure_point --fork Amsterdam

One transaction shape with a non-zero state-gas reservoir, failed at each point along the top frame, settles four different ways.

A non-zero reservoir requires gas_limit above the EIP-7825 cap, which also hands the frame the full execution budget -- so starving the preparation is only reachable when its demand exceeds the cap plus the reservoir. Account-creating authorizations are the one charge dense enough to get there: each demands ~234,606 gas (intrinsic base, ACCOUNT_WRITE, and NEW_ACCOUNT + AUTH_BASE state bytes), so ~73 of them overtop the cap. The count is derived from the fork's calculators. The recipient is a delegated EOA in every scenario, so the top-frame dispatch always owes a cold delegation-resolution access and only the failure_point moves:

• set_delegation_oog: the last authorization's closing AUTH_BASE charge is starved by one gas. The preparation snapshot rolls every delegation back, the refilled state charges restore the reservoir, and settlement returns it whole: gas_used == cap exactly, however much extra gas was sent.
• dispatch_charge_oog: every authorization applies, then the recipient's delegation-resolution access is starved by one gas. The charge shares the preparation snapshot, so the settlement is identical: gas_used == cap.
• execution_halt: preparation completes and the delegated code hits INVALID. The persisting delegations keep their state gas consumed -- far more than the reservoir holds -- so the fold leaves the reservoir empty and the halt burns the rest: gas_used == gas_limit, the full amount.
• execution_revert: as above, but REVERT returns the unused execution budget: gas_used is exactly the intrinsic cost plus every preparation charge plus the reverting code's own gas.

Together the four pin that the reservoir's fate follows the state it paid for: returned in full while nothing survives, consumed to the extent the delegations persist.

Source code in tests/amsterdam/eip2780_reduce_intrinsic_tx_gas/test_authorization_oog.py

@pytest.mark.parametrize(
    "failure_point",
    [
        "set_delegation_oog",
        "dispatch_charge_oog",
        "execution_halt",
        "execution_revert",
    ],
)
def test_reservoir_settlement_by_failure_point(
    fork: Fork,
    pre: Alloc,
    state_test: StateTestFiller,
    failure_point: str,
) -> None:
    """
    One transaction shape with a non-zero state-gas reservoir, failed
    at each point along the top frame, settles four different ways.

    A non-zero reservoir requires ``gas_limit`` above the EIP-7825 cap,
    which also hands the frame the *full* execution budget -- so starving
    the preparation is only reachable when its demand exceeds the cap
    plus the reservoir. Account-creating authorizations are the one
    charge dense enough to get there: each demands ~234,606 gas
    (intrinsic base, ``ACCOUNT_WRITE``, and ``NEW_ACCOUNT`` +
    ``AUTH_BASE`` state bytes), so ~73 of them overtop the cap. The
    count is derived from the fork's calculators. The recipient is a
    delegated EOA in every scenario, so the top-frame dispatch always
    owes a cold delegation-resolution access and only the
    ``failure_point`` moves:

    - ``set_delegation_oog``: the last authorization's closing
      ``AUTH_BASE`` charge is starved by one gas. The preparation
      snapshot rolls every delegation back, the refilled state charges
      restore the reservoir, and settlement returns it whole:
      ``gas_used == cap`` exactly, however much extra gas was sent.
    - ``dispatch_charge_oog``: every authorization applies, then the
      recipient's delegation-resolution access is starved by one gas.
      The charge shares the preparation snapshot, so the settlement is
      identical: ``gas_used == cap``.
    - ``execution_halt``: preparation completes and the delegated code
      hits ``INVALID``. The persisting delegations keep their state gas
      consumed -- far more than the reservoir holds -- so the fold
      leaves the reservoir empty and the halt burns the rest:
      ``gas_used == gas_limit``, the full amount.
    - ``execution_revert``: as above, but ``REVERT`` returns the unused
      execution budget: ``gas_used`` is exactly the intrinsic cost plus
      every preparation charge plus the reverting code's own gas.

    Together the four pin that the reservoir's fate follows the state
    it paid for: returned in full while nothing survives, consumed to
    the extent the delegations persist.
    """
    cap = fork.transaction_gas_limit_cap()
    assert cap is not None, "EIP-7825 cap expected on this fork"
    gas_costs = fork.gas_costs()

    sender = pre.fund_eoa()

    # Two distinct delegation targets are in play. ``delegation_target``
    # is the address every *authority's* authorization designates:
    # ``set_delegation`` writes it into the authorities' code but never
    # reads the account itself.
    delegation_target = pre.deploy_contract(code=Op.STOP)
    recipient_code: Bytecode
    if failure_point == "execution_halt":
        recipient_code = Op.INVALID
    elif failure_point == "execution_revert":
        recipient_code = Op.REVERT(0, 0)
    else:
        recipient_code = Op.STOP
    # ``code_target`` is the *recipient's* pre-existing delegation
    # target: the top-frame dispatch pays a cold access to resolve it
    # and, once paid, loads and runs its code.
    code_target = pre.deploy_contract(code=recipient_code)
    recipient = pre.fund_eoa(
        amount=EOA_INITIAL_BALANCE, delegation=code_target
    )

    def creation_authorization(authority: EOA) -> AuthorizationTuple:
        """Authorization creating a fresh authority's account leaf."""
        return AuthorizationTuple(
            address=delegation_target,
            nonce=0,
            signer=authority,
            creates_account=True,
        )

    probe_authority = pre.fund_eoa(amount=0)
    probe = creation_authorization(probe_authority)
    base_intrinsic = _intrinsic_execution(
        fork, [], recipient_type=RecipientType.DELEGATION_7702
    )
    per_auth_intrinsic = (
        _intrinsic_execution(
            fork, [probe], recipient_type=RecipientType.DELEGATION_7702
        )
        - base_intrinsic
    )
    per_auth_charges = _auth_top_frame_charges(fork, [probe])
    per_auth_total = per_auth_intrinsic + per_auth_charges

    # The smallest authorization count whose starved-by-one gas limit
    # exceeds the cap, plus one more so the reservoir is larger than a
    # full authorization's preparation charge -- a refund too big to be
    # confused with any single refilled charge.
    min_count = (cap + 1 - base_intrinsic) // per_auth_total + 1
    auth_count = min_count + 1

    authorities = [probe_authority] + [
        pre.fund_eoa(amount=0) for _ in range(auth_count - 1)
    ]
    authorization_list = [probe] + [
        creation_authorization(authority) for authority in authorities[1:]
    ]

    intrinsic_execution = base_intrinsic + auth_count * per_auth_intrinsic
    auth_charges = auth_count * per_auth_charges
    dispatch_charge = gas_costs.COLD_ACCOUNT_ACCESS
    auth_state_total = fork.transaction_top_frame_state_gas(
        recipient_type=RecipientType.CONTRACT,
        authorizations=authorization_list,
    )

    if failure_point == "set_delegation_oog":
        # The final authorization's closing AUTH_BASE is starved by one.
        gas_limit = intrinsic_execution + auth_charges - 1
        expected_gas_used = cap
        delegations_persist = False
    elif failure_point == "dispatch_charge_oog":
        # All authorizations apply; the recipient's cold
        # delegation-resolution access is starved by one.
        gas_limit = intrinsic_execution + auth_charges + dispatch_charge - 1
        expected_gas_used = cap
        delegations_persist = False
    elif failure_point == "execution_halt":
        gas_limit = (
            intrinsic_execution + auth_charges + dispatch_charge + 10_000
        )
        expected_gas_used = gas_limit
        delegations_persist = True
    else:  # execution_revert
        exec_gas = recipient_code.gas_cost(fork)
        gas_limit = (
            intrinsic_execution
            + auth_charges
            + dispatch_charge
            + exec_gas
            + 10_000
        )
        expected_gas_used = (
            intrinsic_execution + auth_charges + dispatch_charge + exec_gas
        )
        delegations_persist = True

    reservoir = gas_limit - cap
    if delegations_persist:
        # The persisting delegations' state gas exceeds the reservoir,
        # so the reservoir is consumed in full.
        assert reservoir < auth_state_total, (
            "the persisted auth state gas must swallow the reservoir"
        )
    else:
        assert reservoir > per_auth_charges, (
            "the reservoir must exceed one authorization's charges"
        )

    tx = Transaction(
        sender=sender,
        to=recipient,
        value=0,
        authorization_list=authorization_list,
        gas_limit=gas_limit,
        expected_receipt=TransactionReceipt(
            cumulative_gas_used=expected_gas_used,
        ),
    )

    applied_authority = Account(
        nonce=1,
        balance=0,
        code=Spec7702.delegation_designation(delegation_target),
    )
    post = {
        recipient: Account(
            nonce=1,
            balance=EOA_INITIAL_BALANCE,
            code=Spec7702.delegation_designation(code_target),
        ),
        **(
            dict.fromkeys(authorities, applied_authority)
            if delegations_persist
            # Every authority's account creation is rolled back.
            else dict.fromkeys(authorities)
        ),
    }

    # All authorities are read during authorization validation before
    # any failure, so they always appear in the block access list --
    # with their persisted nonce and code writes past an execution
    # failure, with no recorded changes past a preparation rollback.
    # The recipient is only loaded once preparation reaches the
    # dispatch charge, and its delegation target only once that charge
    # is paid and the delegated code loads -- so both out-of-gas
    # scenarios must leave the target absent from the list. The
    # authorities' delegation target is never read at all: writing a
    # designation does not access the designated account.
    if delegations_persist:
        authority_bal = BalAccountExpectation(
            nonce_changes=[BalNonceChange(block_access_index=1, post_nonce=1)],
            code_changes=[
                BalCodeChange(
                    block_access_index=1,
                    new_code=Spec7702.delegation_designation(
                        delegation_target
                    ),
                )
            ],
        )
    else:
        authority_bal = BalAccountExpectation.empty()
    recipient_bal = (
        None
        if failure_point == "set_delegation_oog"
        else BalAccountExpectation.empty()
    )
    code_target_bal = (
        BalAccountExpectation.empty() if delegations_persist else None
    )
    expected_block_access_list = BlockAccessListExpectation(
        account_expectations={
            recipient: recipient_bal,
            code_target: code_target_bal,
            delegation_target: None,
            **dict.fromkeys(authorities, authority_bal),
        }
    )

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

Parametrized Test Cases

This test generates 4 parametrized test cases across 1 fork.