Ethereum EIPs - Last Call Review

Add chain id to mixed-case checksum address encoding

Sun, 18 Mar 2018 00:00:00 +0000

EIP #1191 - Add chain id to mixed-case checksum address encoding is in Last Call status. It is authored by Juliano Rizzo (@juli) and was originally created 2018-03-18. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://github.com/ethereum/EIPs/issues/1121

Simple Summary

This EIP extends EIP-55 by optionally adding a chain id defined by EIP-155 to the checksum calculation.

Abstract

The EIP-55 was created to prevent users from losing funds by sending them to invalid addresses. This EIP extends EIP-55 to protect users from losing funds by sending them to addresses that are valid but that where obtained from a client of another network.For example, if this EIP is implemented, a wallet can alert the user that is trying to send funds to an Ethereum Testnet address from an Ethereum Mainnet wallet.

Motivation

The motivation of this proposal is to provide a mechanism to allow software to distinguish addresses from different Ethereum based networks. This proposal is necessary because Ethereum addresses are hashes of public keys and do not include any metadata. By extending the EIP-55 checksum algorithm it is possible to achieve this objective.

Specification

Convert the address using the same algorithm defined by EIP-55 but if a registered chain id is provided, add it to the input of the hash function. If the chain id passed to the function belongs to a network that opted for using this checksum variant, prefix the address with the chain id and the 0x separator before calculating the hash. Then convert the address to hexadecimal, but if the ith digit is a letter (ie. it’s one of abcdef) print it in uppercase if the 4*ith bit of the calculated hash is 1 otherwise print it in lowercase.

Rationale

Benefits:

By means of a minimal code change on existing libraries, users are protected from losing funds by mixing addresses of different Ethereum based networks.

Implementation

#!/usr/bin/python3
from sha3 import keccak_256
import random
"""
   addr (str): Hexadecimal address, 40 characters long with 2 characters prefix
   chainid (int): chain id from EIP-155 """
def eth_checksum_encode(addr, chainid=1):
    adopted_eip1191 = [30, 31]
    hash_input = str(chainid) + addr.lower() if chainid in adopted_eip1191 else addr[2:].lower()
    hash_output = keccak_256(hash_input.encode('utf8')).hexdigest()
    aggregate = zip(addr[2:].lower(),hash_output)
    out = addr[:2] + ''.join([c.upper() if int(a,16) >= 8 else c for c,a in aggregate])
    return out

Test Cases

eth_mainnet = [
"0x27b1fdb04752bbc536007a920d24acb045561c26",
"0x3599689E6292b81B2d85451025146515070129Bb",
"0x42712D45473476b98452f434e72461577D686318",
"0x52908400098527886E0F7030069857D2E4169EE7",
"0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
"0x6549f4939460DE12611948b3f82b88C3C8975323",
"0x66f9664f97F2b50F62D13eA064982f936dE76657",
"0x8617E340B3D01FA5F11F306F4090FD50E238070D",
"0x88021160C5C792225E4E5452585947470010289D",
"0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb",
"0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB",
"0xde709f2102306220921060314715629080e2fb77",
"0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359",
]
rsk_mainnet = [
"0x27b1FdB04752BBc536007A920D24ACB045561c26",
"0x3599689E6292B81B2D85451025146515070129Bb",
"0x42712D45473476B98452f434E72461577d686318",
"0x52908400098527886E0F7030069857D2E4169ee7",
"0x5aaEB6053f3e94c9b9a09f33669435E7ef1bEAeD",
"0x6549F4939460DE12611948B3F82B88C3C8975323",
"0x66F9664f97f2B50F62d13EA064982F936de76657",
"0x8617E340b3D01Fa5f11f306f4090fd50E238070D",
"0x88021160c5C792225E4E5452585947470010289d",
"0xD1220A0Cf47c7B9BE7a2e6ba89F429762E7B9adB",
"0xDBF03B407c01E7CD3cBea99509D93F8Dddc8C6FB",
"0xDe709F2102306220921060314715629080e2FB77",
"0xFb6916095cA1Df60bb79ce92cE3EA74c37c5d359",
]
rsk_testnet = [
"0x27B1FdB04752BbC536007a920D24acB045561C26",
"0x3599689e6292b81b2D85451025146515070129Bb",
"0x42712D45473476B98452F434E72461577D686318",
"0x52908400098527886E0F7030069857D2e4169EE7",
"0x5aAeb6053F3e94c9b9A09F33669435E7EF1BEaEd",
"0x6549f4939460dE12611948b3f82b88C3c8975323",
"0x66f9664F97F2b50f62d13eA064982F936DE76657",
"0x8617e340b3D01fa5F11f306F4090Fd50e238070d",
"0x88021160c5C792225E4E5452585947470010289d",
"0xd1220a0CF47c7B9Be7A2E6Ba89f429762E7b9adB",
"0xdbF03B407C01E7cd3cbEa99509D93f8dDDc8C6fB",
"0xDE709F2102306220921060314715629080e2Fb77",
"0xFb6916095CA1dF60bb79CE92ce3Ea74C37c5D359",
]
test_cases = {30 : rsk_mainnet, 31 : rsk_testnet, 1 : eth_mainnet}

for chainid, cases in test_cases.items():
    for addr in cases:
        assert ( addr == eth_checksum_encode(addr,chainid) )

Usage

Usage Table

Network	Chain id	Supports this EIP
RSK Mainnet	30	Yes
RSK Testnet	31	Yes

Implementation Table

Project	EIP Usage	Implementation
MyCrypto	Yes	JavaScript
MyEtherWallet	Yes	JavaScript
Ledger	Yes	C
Trezor	Yes	Python and C
Web3.js	Yes	JavaScript
EthereumJS-util	Yes	JavaScript
ENS address-encoder	Yes	TypeScript

Copyright

Atomic Swap-based American Call Option Contract Standard

Sat, 17 Aug 2019 00:00:00 +0000

EIP #2266 - Atomic Swap-based American Call Option Contract Standard is in Last Call status. It is authored by Runchao Han , Haoyu Lin , Jiangshan Yu and was originally created 2019-08-17. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://github.com/ethereum/EIPs/issues/2266

Simple Summary

A standard for token contracts providing Atomic Swap-based American Call Option functionalities.

Abstract

This standard provides functionality to make Atomic Swap-based American Call Option payment. The Atomic Swap protocol based on Hashed Time-Locked Contract (HTLC) ¹ has optionality ², and such optionality can be utilised to construct American Call Options without trusted third party. This standard defines the common way of implementing this protocol. In particular, this EIP defines technical terms, provides interfaces, and gives reference implementations of this protocol.

Motivation

Atomic Swap allows users to atomically exchange their tokens without trusted third parties while the HTLC is commonly used for the implementation. However, the HTLC-based Atomic Swap has optionality. More specifically, the swap initiator can choose to proceed or abort the swap for several hours, which gives him time for speculating according to the exchange rate. A discussion² shows that the HTLC-based Atomic Swap is equivalent to an American Call Option in finance. On the other hand,thanks to such optionality, the HTLC-based Atomic Swap can be utilised to construct American Call Options without trusted third party. A paper³ proposes a secure Atomic-Swap-based American Call Option protocol on smart contracts. This protocol not only eliminates the arbitrage opportunity but also prevents any party from locking the other party’s money maliciously. This EIP aims at providing the standard of implementing this protocol in existing token standards.

Specification

The Atomic Swap-based American Call Option smart contract should follow the syntax and semantics of Ethereum smart contracts.

Definitions

initiator: the party who publishes the advertisement of the swap.
participant: the party who agrees on the advertisement and participates in the swap with initiator.
asset: the amount of token(s) to be exchanged.
premium: the amount of token(s) that initiator pays to participant as the premium.
redeem: the action to claim the token from the other party.
refund: the action to claim the token from the party herself/himself, because of timelock expiration.
secrect: a random string chosen by initiator as the preimage of a hash.
secrectHash: a string equals to the hash of secrect, used for constructing HTLCs.
timelock: a timestamp representing the timelimit, before when the asset can be redeemed, and otherwise can only be refunded.

Storage Variables

swap

This mapping stores the metadata of the swap contracts, including the parties and tokens involved. Each contract uses different secretHash, and is distinguished by secretHash.

mapping(bytes32 => Swap) public swap;

initiatorAsset

This mapping stores the detail of the asset initiators want to sell, including the amount, the timelock and the state. It is associated with the swap contract with the same secretHash.

mapping(bytes32 => InitiatorAsset) public initiatorAsset;

participantAsset

This mapping stores the details of the asset participants want to sell, including the amount, the timelock and the state. It is associated with the swap contract with the same secretHash.

mapping(bytes32 => ParticipantAsset) public participantAsset;

premiumAsset

This mapping stores the details of the premium initiators attach in the swap contract, including the amount, the timelock and the state. It is associated with the swap contract with the same secretHash.

mapping(bytes32 => Premium) public premium;

Methods

setup

This function sets up the swap contract, including the both parties involved, the tokens to exchanged, and so on.

function setup(bytes32 secretHash, address payable initiator, address tokenA, address tokenB, uint256 initiatorAssetAmount, address payable participant, uint256 participantAssetAmount, uint256 premiumAmount) public payable

initiate

The initiator invokes this function to fill and lock the token she/he wants to sell and join the contract.

function initiate(bytes32 secretHash, uint256 assetRefundTime) public payable

fillPremium

The initiator invokes this function to fill and lock the premium.

function fillPremium(bytes32 secretHash, uint256 premiumRefundTime) public payable

participate

The participant invokes this function to fill and lock the token she/he wants to sell and join the contract.

function participate(bytes32 secretHash, uint256 assetRefundTime) public payable

redeemAsset

One of the parties invokes this function to get the token from the other party, by providing the preimage of the hash lock secret.

function redeemAsset(bytes32 secret, bytes32 secretHash) public

refundAsset

One of the parties invokes this function to get the token back after the timelock expires.

function refundAsset(bytes32 secretHash) public

redeemPremium

The participant invokes this function to get the premium. This can be invoked only if the participant has already invoked participate and the participant’s token is redeemed or refunded.

function redeemPremium(bytes32 secretHash) public

refundPremium

The initiator invokes this function to get the premium back after the timelock expires.

function refundPremium(bytes32 secretHash) public

Events

SetUp

This event indicates that one party has set up the contract using the function setup().

event SetUp(bytes32 secretHash, address initiator, address participant, address tokenA, address tokenB, uint256 initiatorAssetAmount, uint256 participantAssetAmount, uint256 premiumAmount);

Initiated

This event indicates that initiator has filled and locked the token to be exchanged using the function initiate().

event Initiated(uint256 initiateTimestamp, bytes32 secretHash, address initiator, address participant, address initiatorAssetToken, uint256 initiatorAssetAmount, uint256 initiatorAssetRefundTimestamp);

Participated

This event indicates that participant has filled and locked the token to be exchanged using the function participate().

event Participated(uint256 participateTimestamp, bytes32 secretHash, address initiator, address participant, address participantAssetToken, uint256 participantAssetAmount, uint256 participantAssetRefundTimestamp);

PremiumFilled

This event indicates that initiator has filled and locked premium using the function fillPremium().

event PremiumFilled(uint256 fillPremiumTimestamp, bytes32 secretHash, address initiator, address participant, address premiumToken, uint256 premiumAmount, uint256 premiumRefundTimestamp);

InitiatorAssetRedeemed/ParticipantAssetRedeemed

These two events indicate that asset has been redeemed by the other party before the timelock by providing secret.

event InitiatorAssetRedeemed(uint256 redeemTimestamp, bytes32 secretHash, bytes32 secret, address redeemer, address assetToken, uint256 amount);

event ParticipantAssetRedeemed(uint256 redeemTimestamp, bytes32 secretHash, bytes32 secret, address redeemer, address assetToken, uint256 amount);

InitiatorAssetRefunded/ParticipantAssetRefunded

These two events indicate that asset has been refunded by the original owner after the timelock expires.

event InitiatorAssetRefunded(uint256 refundTimestamp, bytes32 secretHash, address refunder, address assetToken, uint256 amount);

event ParticipantAssetRefunded(uint256 refundTimestamp, bytes32 secretHash, address refunder, address assetToken, uint256 amount);

PremiumRedeemed

This event indicates that premium has been redeemed by participant. This implies that asset is either redeemed by initiator if it can provide the preimage of secrectHash before asset timelock expires; or refunded by participant if asset timelock expires.

event PremiumRedeemed(uint256 redeemTimestamp,bytes32 secretHash,address redeemer,address token,uint256 amount);

PremiumRefunded

This event indicates that premium has been refunded back to initiator, because of participant doesn’t participate at all, by the time of premium timelock expires.

event PremiumRefunded(uint256 refundTimestamp, bytes32 secretHash, address refunder, address token, uint256 amount);

Rationale

To achieve the atomicity, HTLC is used.
The participant should decide whether to participate after the initiator locks the token and sets up the timelock.
The initiator should decide whether to proceed the swap (redeem the tokens from the participant and reveal the preimage of the hash lock), after the participant locks the tokens and sets up the time locks.
Premium is redeemable for the participant only if the participant participates in the swap and redeems the initiator’s token before premium’s timelock expires.
Premium is refundable for the initiator only if the initiator initiates but the participant does not participate in the swap at all.

Security Considerations

The initiateTimestamp should cover the whole swap process.
The participant should never participate before the premium has been deposited.

Backwards Compatibility

This proposal is fully backward compatible. Functionalities of existing standards will not be affected by this proposal, as it only provides additional features to them.

Implementation

Please visit here to find our example implementation.

Copyright

References

Resource-based intrinsic transaction gas

Sat, 11 Jul 2020 00:00:00 +0000

EIP #2780 - Resource-based intrinsic transaction gas is in Last Call status. It is authored by Matt Garnett (@lightclient), Uri Klarman (@uriklarman), Ben Adams (@benaadams), Maria Inês Silva (@misilva73), Anders Elowsson (@anderselowsson), Anthony Sassano (@sassal), Dragan Rakita (@rakita) and was originally created 2020-07-11. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-2780-reduce-intrinsic-cost-of-transactions/4413

Abstract

This EIP decomposes the flat 21,000 intrinsic transaction cost into explicit primitives, each priced to match the resources a transaction actually consumes. A plain ETH transfer to an existing account remains at 21,000 execution gas, and contract-creation transactions cost the same whether or not they carry value. Transactions that create new accounts or interact with EIP-7702 pay the additional runtime costs they incur.

In addition, the new primitives are split into intrinsic gas and runtime gas. Intrinsic gas is the state-independent cost of including the transaction in a block and is the sole input to the transaction-validity check. Runtime gas covers the state-dependent charges, such as new account creation and delegation resolution. Runtime gas is charged before the first frame is entered and is metered in the same way as gas inside the frame. Running out of runtime gas does not invalidate the transaction. Instead, the transaction is included, execution is skipped, and the pre-execution state changes are reverted.

This EIP does not change calldata or access-list metering.

Motivation

The flat 21,000 intrinsic cost charges every transaction the same amount regardless of what it does. A zero-value transaction to an existing account and a value transfer that creates a new account both pay 21,000, even though the latter touches an extra account, writes an extra balance, emits a log, and permanently grows the state. The single constant both over-prices the simplest paths and under-prices the ones that consume real, lasting resources.

This EIP replaces the constant with a decomposition into named primitives, each priced to the resource it represents. The goal is to make every transaction’s cost reflect its actual work:

Accuracy. Signature recovery, account accesses, account writes, value transfers, and state creation are billed separately, so cost tracks usage.
State growth is internalized. A value transfer that creates an account, like a contract-creation transaction, pays STATE_BYTES_PER_NEW_ACCOUNT × CPSB in state gas. This aligns top-level value transfers with internal CALL-based account creation, which already pays for the new leaf, and prices the durable state cost the flat base ignored.
Composability. Pricing intrinsic cost as a sum of the same primitives used elsewhere in the gas schedule lets future repricings (e.g. of cold-account access in EIP-8038, or of state bytes in EIP-8037) flow through automatically, without re-deriving a bespoke constant.
No worst-case reservation. State-dependent costs, such as new account creation and delegation resolution, are charged at runtime only when a transaction incurs them, rather than reserved up front. Intrinsic gas covers only inclusion and remains the sole validity input, so a transaction that funds inclusion but not a runtime charge is included, charged for the gas consumed, and reverted, exactly like an out-of-gas halt inside a call frame.

Specification

Parameters

Name	Value	Definition
`TX_BASE_COST`	12,000	Sender cost: ECDSA recovery, the sender’s account access, the sender’s account write and inclusion in block
`TX_VALUE_COST`	6,000	Recipient balance write and EIP-7708 transfer log performed by a value transfer

The remaining values are defined in other EIPs and referenced here:

Name	Value	Source	Definition
`COLD_ACCOUNT_ACCESS`	3,000	EIP-8038	Cold account touch
`WARM_ACCESS`	100	EIP-8038	Warm account touch
`ACCOUNT_WRITE`	9,000	EIP-8038	First write to an account leaf
`CREATE_ACCESS`	12,000	EIP-8038	Contract-deployment account access and write
`EXECUTION_PER_AUTH_BASE_COST`	7,816	EIP-8037	Per-authorization base: calldata, ECDSA recovery, cold authority access, and warm writes
`STATE_BYTES_PER_NEW_ACCOUNT × CPSB`	183,600	EIP-8037	State gas for one new account leaf
`STATE_BYTES_PER_AUTH_BASE × CPSB`	35,190	EIP-8037	State gas for one 23-byte delegation indicator

The two state-gas products change whenever CPSB changes. Execution-gas and state-gas semantics are defined by EIP-8037.

Intrinsic gas costs

A transaction’s intrinsic base cost is decomposed into the following explicit primitives:

tx.sender is charged TX_BASE_COST in execution gas, accounting for one ECDSA recovery, the sender’s account access and write, and the inclusion of the transaction’s bytes in the block.
tx.to is charged based on its type:
- if self-transfer (tx.sender == tx.to), there are no charges;
- if None (contract-creation transaction), charge CREATE_ACCESS in execution gas; the new-account state charge depends on whether the deployment target exists and is charged at runtime;
- otherwise, charge COLD_ACCOUNT_ACCESS in execution gas (covering the recipient touch, charged at the cold rate unconditionally).
tx.value is charged based on its value:
- if zero, there are no charges;
- if non-zero and self-transfer, there are no charges;
- if non-zero and contract creation, there are no charges; the recipient balance write is already covered by CREATE_ACCESS;
- otherwise, charge TX_VALUE_COST in execution gas.
each EIP-7702 authorization is charged EXECUTION_PER_AUTH_BASE_COST in execution gas.

The recipient touch and the authority access (inside EXECUTION_PER_AUTH_BASE_COST) are charged at the cold rate every time, even if the account would be warm (for example, via an access list), keeping intrinsic gas computable without any state read.

These charges replace the legacy contract-creation transaction charges and EIP-7702’s flat PER_EMPTY_ACCOUNT_COST × authorization_list_length intrinsic charge.

Calldata and access-list metering remain unchanged.

Runtime gas costs

Once the transaction passes the intrinsic gas check, the state-dependent gas costs (i.e., runtime costs) are applied. The runtime charges happen in a distinct window — the pre-execution phase — after the transaction is already deemed valid but before the first EVM frame is entered. This phase includes the following actions, in order:

The available gas is split into gas_left and state_gas_reservoir, and all the gas accounting counters are initialized, per EIP-8037;
EIP-7702 authorizations are processed;
The recipient account is added to the EIP-7928’s Block-Level Access List (its access was already charged at the cold rate at the intrinsic phase, and it is warm from transaction start);
The remaining account creation and access costs are applied.

Like every charge in this EIP, each runtime charge is split into execution gas and state gas per EIP-8037: account accesses and writes are execution gas, while durable state growth (new account leaves and net-new delegation bytes) is state gas. This mirrors how a CALL frame is metered: accesses, account creation, and writes are charged as state is touched, not up front.

Running out of gas during these runtime charges does not invalidate the transaction. Validity is decided solely by the intrinsic gas check.

If the transaction goes out-of-gas in this pre-execution phase, the sender pays for all gas consumed, and all pre-execution state changes are reverted, including any EIP-7702 delegations. The included transaction still increments the sender’s nonce and pays its gas fees. By contrast, if the transaction goes out-of-gas after entering the first EVM frame, the delegations applied during the pre-execution phase stay in place, per EIP-7702; the state gas that paid for them — each authority’s account-creation and delegation-indicator bytes — therefore stays consumed, since that state persists beyond the frame. Runtime state charges whose state is instead rolled back with the frame (for example, a contract-creation transaction’s new-account charge; see below) are refilled in LIFO order per EIP-8037, and execution-gas runtime charges (such as a delegation-target access) remain consumed.

If a contract-creation transaction’s initcode reverts, the transaction remains valid and any state gas charged at runtime is refilled in last-in, first-out (LIFO) order, per EIP-8037: the portion the charge drew from gas_left is credited back to gas_left, and only the remainder returns to the state_gas_reservoir.

On an exceptional halt, the same LIFO refill applies. A plain value transfer to a new account executes no code and so cannot revert. Its new-account state charge is therefore never rolled back this way. The exception is a transfer to an empty precompile, which does execute and can fail, though on mainnet all precompiles are already pre-funded.

EIP-7702 authorization processing

While processing each valid authorization, the following charges are applied at most once per authority:

if the authority account does not already exist, charge STATE_BYTES_PER_NEW_ACCOUNT × CPSB in state gas for the new account leaf;
if this is the first write to the authority within the transaction, charge ACCOUNT_WRITE in execution gas; the charge is skipped when the write is already paid for, namely when the authority:
- is tx.sender, covered by TX_BASE_COST;
- was written by a preceding valid authorization;
- is tx.to of a value-bearing transaction, covered by TX_VALUE_COST;
if the authorization sets a non-zero delegation target, the authority had no delegation indicator at transaction start, and no earlier authorization set one for that authority in this transaction, charge STATE_BYTES_PER_AUTH_BASE × CPSB in state gas. Clearing an indicator does not refund this charge or make a later set chargeable again. An indicator present at transaction start can be cleared and re-set without paying this charge.

Authorization validation and warming retain the ordering in EIP-7702: check the chain ID and nonce bound, recover the authority, add it to accessed_addresses, and then check its code and current nonce. An authorization skipped because of the latter checks still warms the recovered authority; one rejected before recovery does not. The state-dependent charges above apply only after validation succeeds, before applying the authorization.

Account creation and access charges

If the transaction is not a contract creation, then the following charges are applied:

if the recipient is non-existent and tx.value > 0, charge STATE_BYTES_PER_NEW_ACCOUNT × CPSB in state gas (never applies to a self-transfer, whose recipient is the already-existing sender);
if the recipient is an EIP-7702 delegated account, additionally charge the delegation-target access in execution gas: COLD_ACCOUNT_ACCESS if cold, WARM_ACCESS if warm.

For a contract-creation transaction, if the deployment address does not already exist, per the existence rule of EIP-8037, charge STATE_BYTES_PER_NEW_ACCOUNT × CPSB in state gas.

Transaction reference cases

Costs are split between the intrinsic phase and the runtime phase, each in execution gas and state gas, per EIP-8037. “execution” denotes contract execution charged at the standard schedule; it, and every runtime charge, is drawn from the gas passed into the first frame, so that frame is entered with the gas remaining after the runtime execution and state charges. The recipient touch is charged at the cold rate at the intrinsic phase; the only runtime account access is the delegation-target load, shown at the cold rate — a target warmed beforehand pays WARM_ACCESS rather than COLD_ACCOUNT_ACCESS. Create rows assume the deployment target does not already exist; a pre-existing target pays no new-account state charge. A plain ETH transfer to an existing EOA remains at the legacy 21,000 execution gas; the other rows show the decomposition for each transaction shape.

Case	Intrinsic (execution / state)	Runtime (execution / state)	Total (execution / state)
ETH transfer to self	`TX_BASE_COST` / 0	0 / 0	12,000 / 0
No-transfer to EOA / empty account	`TX_BASE_COST + COLD_ACCOUNT_ACCESS` / 0	0 / 0	15,000 / 0
No-transfer to contract	`TX_BASE_COST + COLD_ACCOUNT_ACCESS` / 0	execution / 0	15,000 + execution / 0
ETH transfer to existing EOA	`TX_BASE_COST + COLD_ACCOUNT_ACCESS + TX_VALUE_COST` / 0	0 / 0	21,000 / 0
ETH transfer to contract	`TX_BASE_COST + COLD_ACCOUNT_ACCESS + TX_VALUE_COST` / 0	execution / 0	21,000 + execution / 0
No-transfer to 7702 delegated	`TX_BASE_COST + COLD_ACCOUNT_ACCESS` / 0	`COLD_ACCOUNT_ACCESS` + execution / 0	18,000 + execution / 0
ETH transfer to 7702 delegated	`TX_BASE_COST + COLD_ACCOUNT_ACCESS + TX_VALUE_COST` / 0	`COLD_ACCOUNT_ACCESS` + execution / 0	24,000 + execution / 0
ETH transfer to self, sender 7702 delegated	`TX_BASE_COST` / 0	`COLD_ACCOUNT_ACCESS` + execution / 0	15,000 + execution / 0
ETH transfer creating new account	`TX_BASE_COST + COLD_ACCOUNT_ACCESS + TX_VALUE_COST` / 0	0 / `STATE_BYTES_PER_NEW_ACCOUNT × CPSB`	21,000 / 183,600
Create transaction, `tx.value` = 0	`TX_BASE_COST + CREATE_ACCESS` / 0	0 / `STATE_BYTES_PER_NEW_ACCOUNT × CPSB`	24,000 / 183,600
Create transaction, `tx.value` > 0	`TX_BASE_COST + CREATE_ACCESS` / 0	0 / `STATE_BYTES_PER_NEW_ACCOUNT × CPSB`	24,000 / 183,600
Create transaction, `tx.value` > 0, `created_address.balance` > 0	`TX_BASE_COST + CREATE_ACCESS` / 0	0 / 0	24,000 / 0

Interactions with other EIPs

EIP-2929 (warm/cold accounting). The sender access folded into TX_BASE_COST, the recipient’s COLD_ACCOUNT_ACCESS, and the authority access inside EXECUTION_PER_AUTH_BASE_COST are all charged at the intrinsic phase at fixed cold rates, independent of the account’s warm/cold state — an access-list entry for the recipient or an authority does not discount them. The sender, the recipient, and each processed authority are added to accessed_addresses, so subsequent execution-level touches are warm. The only runtime account access is the delegation-target load, which follows the standard EIP-2929 warm/cold model: COLD_ACCOUNT_ACCESS if cold, WARM_ACCESS if warm. The same model governs all execution-level account touches, including internal CALLs.
EIP-2930 (access lists). Access lists keep their existing per-entry charges and warming semantics for execution-level touches. Listing the recipient or an authority does not reduce the intrinsic cold-rate charges; it only pre-warms the address for execution.
EIP-7623 (calldata floor). EIP-7623 floors a transaction’s cost at 21,000 + TOTAL_COST_FLOOR_PER_TOKEN × tokens_in_calldata, where the flat 21,000 is the intrinsic base this EIP decomposes. With this EIP active, that base term is replaced by the transaction’s decomposed base — TX_BASE_COST plus the applicable recipient and value primitives (COLD_ACCOUNT_ACCESS and TX_VALUE_COST for a value transfer to a different account, or CREATE_ACCESS for contract creation). Per-authorization charges and initcode word charges are excluded from this base, so the floor and its validity check rest on the same per-transaction base as the rest of intrinsic gas rather than a stale constant. Like the floor, this base is state-independent, so the state-dependent runtime charges (the new-account state-gas charge and the delegation-target access) do not enter it. The calldata schedule itself is unchanged; only the base the floor sits on moves.
EIP-7702 (set EOA code). TX_BASE_COST is unchanged when the sender is delegated or an authorization changes its delegation. An authorization supplies a delegation target address, not the target’s code. Computing the intrinsic charge does not require loading that code; resolving a delegation for execution does. When tx.to is a delegated account, resolving the delegation loads the target’s code, charged COLD_ACCOUNT_ACCESS on first touch or warm thereafter, following the standard EIP-2929 accessed_addresses model. Setting a delegation (writing the 23-byte pointer) is distinct from resolving one (reading the target’s code); the resolution charge is genuine work and is not prepaid by the authorization. Authorization cost itself is decomposed: EXECUTION_PER_AUTH_BASE_COST — which already includes the authority’s cold access — is charged per authorization at the intrinsic phase, while the state-dependent charges (STATE_BYTES_PER_NEW_ACCOUNT × CPSB for a non-existent authority, ACCOUNT_WRITE for the first write to the authority within the transaction, and STATE_BYTES_PER_AUTH_BASE × CPSB for net-new delegation bytes) are charged at runtime during authorization processing, replacing the worst-case PER_EMPTY_ACCOUNT_COST intrinsic charge and refund.
EIP-7708 (ETH transfers emit a log). Every non-zero-value transfer to a different account emits a transfer log; its cost is folded into TX_VALUE_COST alongside the recipient balance write rather than priced as a separate primitive.
EIP-7928 (block-level access lists). tx.sender is accessed at the intrinsic phase and tx.to at the runtime phase, so both are included in the block-level access list even when the transaction reverts.

Rationale

Intrinsic versus runtime gas

The split follows a single line: can the charge be computed without reading state? Signature recovery, the sender’s access and write, the transaction’s block bytes, the value charges, and the per-authorization base are all fixed by the transaction’s fields alone, so they are intrinsic and decide validity. The recipient touch and the authority access are also intrinsic, charged unconditionally at the cold rate: a top-level account is loaded from cold state once per transaction, and pricing that load at a fixed cold rate — rather than discounting the rare case where an access list pre-warmed it — keeps the charge state-independent without underpricing the work. The state-touching remainder is runtime, billed as each account is actually loaded: whether the recipient, an authority, or a deployment target exists, and whether a delegation must be resolved.

Charging the runtime part as the first frame is entered makes the top-level transaction behave like an ordinary CALL: a frame is metered against the gas handed to it, and exhausting that gas halts the frame without unwinding the caller’s decision to make the call. Here the “caller” is block inclusion, and the intrinsic check is its decision; a runtime out-of-gas therefore cannot retract validity. Keeping validity on a state-independent quantity is also what lets a block builder decide inclusion without executing the transaction, and lets later EIPs price new state-dependent work at runtime without ever touching the validity boundary.

Pricing only the work each transaction does

The decomposition charges each primitive once, where the resource is consumed: signature recovery and the sender’s access and write in TX_BASE_COST; the recipient touch in COLD_ACCOUNT_ACCESS; the recipient balance write and transfer log in TX_VALUE_COST; and durable state creation in STATE_BYTES_PER_NEW_ACCOUNT × CPSB. A zero-value transaction pays only for the touches it makes, while a value transfer that creates an account pays for the new leaf it adds. This removes the cross-subsidy in the flat base, where simple transactions overpaid and state-creating ones underpaid.

The new-account state charge does not apply to CREATE/CREATE2: the GAS_CREATE opcode base already prices internal account creation, and top-level contract-creation transactions pay CREATE_ACCESS intrinsically plus the same state-gas charge at runtime when the deployment target does not already exist. Charging the state-growth cost on top-level value transfers that create accounts aligns them with the CALL-based creation path, which has always paid for the new leaf.

Deriving the decomposition from measured client run times

The values of TX_BASE_COST and TX_VALUE_COST are not set by intuition; they are derived from measured client execution times, using the same approach as EIP-8038.

The derivation uses the EELS test_ether_transfers_onchain_receivers benchmark, executed across all major execution-layer clients (Besu, Erigon, Geth, Nethermind, Reth). The benchmark fills blocks with ether transfers to four kinds of receiver, each exercising a different work path:

transfers to a contract with shared code, where the code lookup is cached across transactions;
transfers to a contract with unique 24 KiB code, forcing a fresh code read and JUMPDEST analysis on every transaction (the heaviest path);
transfers to an existing EOA;
transfers to a non-existent EOA, where the client must create a new account.

For each (client, receiver) pair, a non-negative least-squares model fits measured block runtime as a linear function of the number of transfers and the number of value-bearing transfers. The two fitted coefficients are the per-transfer base runtime and the additional runtime of moving value. Each coefficient is converted to gas at a fixed throughput anchor of 100 Mgas/s (gas = ceil(100,000 × runtime_ms)).

For any candidate target, the analysis surfaces each client’s worst case across receiver types, separating clients that already meet the target from those that must optimize to reach it. The proposed TX_BASE_COST and TX_VALUE_COST are set as such targets: they align intrinsic cost with the resource usage of well-optimized clients while leaving slower clients a defined optimization goal.

The two empirical coefficients map onto the decomposition as follows:

the per-transfer base runtime covers signature recovery, the sender’s access and write, and the recipient touch → TX_BASE_COST + COLD_ACCOUNT_ACCESS;
the value increment covers the recipient balance write and the transfer log → TX_VALUE_COST.

COLD_ACCOUNT_ACCESS is taken directly from EIP-8038, since the recipient touch is the same cold-account access priced there. TX_BASE_COST and TX_VALUE_COST are the residual parameters this EIP introduces.

As in EIP-8038, these numbers are provisional. At the 100 Mgas/s anchor some clients are currently slower than the target on the heaviest paths and must optimize to meet it; the values will be refined as client optimizations land and the benchmarks mature.

Not metering the transaction envelope as calldata

Only tx.data bytes are metered at the calldata schedule; the envelope RLP (nonce, gas*, to, value, v, r, s) is not. Pricing full-transaction bytes would make intrinsic gas depend on gas_limit and variable-length signature elements — creating a fixed-point estimation problem, since gas_limit would depend on the signature, which itself encodes gas_limit — and would couple the fee to one serialization, weakening EIP-2718 type neutrality and future encodings. Treating calldata as opaque bytes avoids both issues. A plain ETH transfer carries empty tx.data and so pays zero calldata gas regardless.

Self-transfers

A self-transfer (tx.sender == tx.to) charges neither the recipient touch nor the value cost: the account is already accessed and written as the sender, and EIP-7708 emits no transfer log when sender and recipient coincide. Only TX_BASE_COST applies to the intrinsic base. If the sender is delegated, the delegation-target access and any delegated execution are still charged at runtime.

Decomposing authorization cost

EIP-7702 charges PER_EMPTY_ACCOUNT_COST per authorization at the intrinsic phase and refunds it when the authority already exists, over-reserving gas the transaction may never use. Splitting the cost removes the over-charge: only EXECUTION_PER_AUTH_BASE_COST — the calldata, signature recovery, cold authority access, and warm writes every authorization performs — is knowable without state access and stays intrinsic. The new-account leaf, the first-write ACCOUNT_WRITE, and the delegation-indicator bytes depend on state and are charged at runtime during authorization processing, billed only for the authorities that incur them.

Backwards Compatibility

This EIP is not backward compatible. It is a consensus gas repricing that must be activated at a network upgrade. Wallets, RPCs, gas estimators, and any logic that assumes a flat 21,000 intrinsic base must update, particularly to account for the state-gas charge on transactions that create new accounts.

Test Cases

Costs are given as intrinsic + runtime, by case. These examples omit calldata, access-list, and initcode word charges and, except in case 8, authorization charges; executed code is charged separately. Delegation-target accesses shown at the cold rate cost WARM_ACCESS instead when the target is already warm:

Self-transfer (from == to): 12,000 intrinsic, 0 runtime. If the sender is 7702-delegated, the delegation-target access is additionally charged at runtime, per case 5.
Zero-value transaction to a distinct existing or empty EOA: 15,000 intrinsic (TX_BASE_COST + COLD_ACCOUNT_ACCESS), 0 runtime, 0 state. A contract recipient additionally pays for execution; a delegated recipient also pays for the delegation-target access. A self-target has a 12,000 intrinsic base, with delegated execution charged as in case 1.
Value transfer to an existing EOA: 21,000 intrinsic, 0 runtime, 0 state.
Value transfer creating a new account (recipient non-existent): 21,000 intrinsic execution; STATE_BYTES_PER_NEW_ACCOUNT × CPSB = 183,600 runtime state.
Value transfer to a 7702-delegated account: 21,000 intrinsic + COLD_ACCOUNT_ACCESS runtime = 24,000 execution gas plus contract execution.
Contract-creation transaction, value = 0: 24,000 intrinsic execution; 183,600 runtime state if the deployment target did not exist, 0 otherwise.
Contract-creation transaction, value > 0: 24,000 intrinsic execution (identical to the value = 0 case, since the recipient balance write is covered by CREATE_ACCESS); 183,600 runtime state if the deployment target did not exist, 0 otherwise.
EIP-7702 transaction: TX_BASE_COST is unchanged even when the sender assumes code. Each authorization is charged EXECUTION_PER_AUTH_BASE_COST (which already covers the cold authority access) at the intrinsic phase; at runtime, a non-existent authority additionally pays STATE_BYTES_PER_NEW_ACCOUNT × CPSB state, the first write to the authority within the transaction pays ACCOUNT_WRITE execution, and net-new delegation bytes add STATE_BYTES_PER_AUTH_BASE × CPSB state — replacing the flat PER_EMPTY_ACCOUNT_COST intrinsic charge and refund.
Contract-creation transaction whose initcode reverts (value-bearing or not): the transaction remains valid; the 183,600 new-account state-gas charge is refilled in LIFO order per EIP-8037 — credited to gas_left up to the portion the charge drew from it, with the remainder returning to the state_gas_reservoir.
Transaction whose gas covers intrinsic cost but not a runtime charge — e.g. a value transfer to a non-existent recipient or a contract creation to a non-existent target lacking gas for the new-account state charge, or a transfer to a delegated account lacking gas for the delegation-target access: the transaction is valid and included, halts out-of-gas, and all runtime state changes — including any applied EIP-7702 delegations — are reverted; it is not invalidated.

Blocks of pure ETH transfers should be tested across all EL clients (e.g. on Perfnet) to confirm the pricing matches measured run times at the chosen throughput anchor.

Security Considerations

The decomposed charges, intrinsic plus runtime, sum to at least the legacy 21,000 for any transaction that moves value to a distinct, cold account, and add state gas for transactions that grow the state. No path is cheaper than under the flat base in a way that increases per-block resource consumption; the change reallocates cost to match resources and prices state growth that was previously not priced.

Moving the state-dependent charges to runtime lowers the validity threshold (a simple call is valid at TX_BASE_COST + COLD_ACCOUNT_ACCESS rather than 21,000), but does not enable underpriced work. A transaction that passes the intrinsic check yet runs out of runtime gas is still included and the sender still pays for every gas unit consumed, with all state changes reverted — exactly the cost profile of an out-of-gas inside a call frame. The runtime mechanism thus charges the same resources as before; it only relocates where, in the lifecycle, the gas is metered.

The semantics of SELFDESTRUCT are unchanged. Per EIP-6780, only contracts created within the same transaction may be fully deleted; this EIP does not reprice or modify any SELFDESTRUCT side effects.

Copyright

Slashing Protection Interchange Format

Tue, 27 Oct 2020 00:00:00 +0000

EIP #3076 - Slashing Protection Interchange Format is in Last Call status. It is authored by Michael Sproul (@michaelsproul), Sacha Saint-Leger (@sachayves), Danny Ryan (@djrtwo) and was originally created 2020-10-27. It is in the Interface category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-3076-validator-client-interchange-format-slashing-protection/4883

Abstract

A standard format for transferring a key’s signing history allows validators to easily switch between clients without the risk of signing conflicting messages. While a common keystore format provides part of the solution, it does not contain any information about a key’s signing history. For a validator moving their keys from client A to client B, this could lead to scenarios in which client B inadvertently signs a message that conflicts with an earlier message signed with client A. The interchange format described here provides a solution to this problem.

Motivation

The proof of stake (PoS) protocol penalises validators for voting in ways that could result in two different versions of the chain being finalised. These types of penalties are called slashings.

For a validator following the protocol correctly, there is, in principle, no risk of being slashed. However, changing clients (from client A to client B, say) can result in a slashing risk if client B is unaware of the blocks and attestations that were signed with client A.

This can occur if client A and client B do not agree on what the present time is. For example, say client A’s time is accidentally set to a day in the future (225 epochs), and a validator switches from client A to client B without giving B a record of the blocks and attestations signed with A. The validator in question now runs the risk of attesting to two different blocks in the same epoch (a slashable offence) for the next 225 epochs (since they’ve already voted on these epochs with client A, and now stand to vote on them again with client B). Such time-skew bugs have been observed in the wild.

Another situation in which slashing protection is critical is in the case of re-orgs. During a re-org it is possible for a validator to be assigned new attestation duties for an epoch in which it has already signed an attestation. In this case it is essential that the record of the previous attestation is available, even if the validator just moved from one client to another in the space of a single epoch.

Specification

JSON Schema

A valid interchange file is one that adheres to the following JSON schema, and is interpreted according to the Conditions.

{
  "title": "Signing history",
  "description": "This schema provides a record of the blocks and attestations signed by a set of validators",
  "type": "object",
  "properties": {
    "metadata": {
      "type": "object",
      "properties": {
        "interchange_format_version": {
          "type": "string",
          "description": "The version of the interchange format that this document adheres to"
        },
        "genesis_validators_root": {
          "type": "string",
          "description": "Calculated at Genesis time; serves to uniquely identify the chain"
        }
      },
      "required": [
        "interchange_format_version",
        "genesis_validators_root"
      ]
    },
    "data": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "pubkey": {
              "type": "string",
              "description": "The BLS public key of the validator (encoded as a 0x-prefixed hex string)"
            },
            "signed_blocks": {
              "type": "array",
              "items": [
                {
                  "type": "object",
                  "properties": {
                    "slot": {
                      "type": "string",
                      "description": "The slot number of the block that was signed"
                    },
                    "signing_root": {
                      "type": "string",
                      "description": "The output of compute_signing_root(block, domain)"
                    }
                  },
                  "required": [
                    "slot"
                  ]
                }
              ]
            },
            "signed_attestations": {
              "type": "array",
              "items": [
                {
                  "type": "object",
                  "properties": {
                    "source_epoch": {
                      "type": "string",
                      "description": "The attestation.data.source.epoch of the signed attestation"
                    },
                    "target_epoch": {
                      "type": "string",
                      "description": "The attestation.data.target.epoch of the signed attestation"
                    },
                    "signing_root": {
                      "type": "string",
                      "description": "The output of compute_signing_root(attestation, domain)"
                    }
                  },
                  "required": [
                    "source_epoch",
                    "target_epoch"
                  ]
                }
              ]
            }
          },
          "required": [
            "pubkey",
            "signed_blocks",
            "signed_attestations"
          ]
        }
      ]
    }
  },
  "required": [
    "metadata",
    "data"
  ]
}

Example JSON Instance

{
  "metadata": {
    "interchange_format_version": "5",
    "genesis_validators_root": "0x04700007fabc8282644aed6d1c7c9e21d38a03a0c4ba193f3afe428824b3a673"
  },
  "data": [
    {
      "pubkey": "0xb845089a1457f811bfc000588fbb4e713669be8ce060ea6be3c6ece09afc3794106c91ca73acda5e5457122d58723bed",
      "signed_blocks": [
        {
          "slot": "81952",
          "signing_root": "0x4ff6f743a43f3b4f95350831aeaf0a122a1a392922c45d804280284a69eb850b"
        },
        {
          "slot": "81951"
        }
      ],
      "signed_attestations": [
        {
          "source_epoch": "2290",
          "target_epoch": "3007",
          "signing_root": "0x587d6a4f59a58fe24f406e0502413e77fe1babddee641fda30034ed37ecc884d"
        },
        {
          "source_epoch": "2290",
          "target_epoch": "3008"
        }
      ]
    }
  ]
}

Conditions

After importing an interchange file with data field data, a signer must respect the following conditions:

Refuse to sign any block that is slashable with respect to the blocks contained in data.signed_blocks. For details of what constitutes a slashable block, see process_proposer_slashing (from consensus-specs). If the signing_root is absent from a block, a signer must assume that any new block with the same slot is slashable with respect to the imported block.
Refuse to sign any block with slot <= min(b.slot for b in data.signed_blocks if b.pubkey == proposer_pubkey), except if it is a repeat signing as determined by the signing_root.
Refuse to sign any attestation that is slashable with respect to the attestations contained in data.signed_attestations. For details of what constitutes a slashable attestation, see is_slashable_attestation_data.
Refuse to sign any attestation with source epoch less than the minimum source epoch present in that signer’s attestations (as seen in data.signed_attestations). In pseudocode:

source.epoch <
    min(att.source_epoch
        for att in data.signed_attestations
        if att.pubkey == attester_pubkey)

Refuse to sign any attestation with target epoch less than or equal to the minimum target epoch present in that signer’s attestations (as seen in data.signed_attestations), except if it is a repeat signing as determined by the signing_root. In pseudocode:

target_epoch <=
    min(att.target_epoch
        for att in data.signed_attestations
        if att.pubkey == attester_pubkey)

Additional Information

The interchange_format_version version is set to 5.
A signed block or attestation’s signing_root refers to the message data (hash tree root) that gets signed with a BLS signature. It allows validators to re-sign and re-broadcast blocks or attestations if asked.
The signed_blocks signing_roots are calculated using compute_signing_root(block, domain): where block is the block (of type BeaconBlock or BeaconBlockHeader) that was signed, and domain is equal to compute_domain(DOMAIN_BEACON_PROPOSER, fork, metadata.genesis_validators_root).
The signed_attestations signing_roots are calculated using compute_signing_root(attestation, domain): where attestation is the attestation (of type AttestationData) that was signed, and domain is equal to compute_domain(DOMAIN_BEACON_ATTESTER, fork, metadata.genesis_validators_root).

Rationale

Supporting Different Strategies

The interchange format is designed to be flexible enough to support the full variety of slashing protection strategies that clients may implement, which may be categorised into two main types:

Complete: a database containing every message signed by each validator.
Minimal: a database containing only the latest messages signed by each validator.

The advantage of the minimal strategy is its simplicity and succinctness. Using only the latest messages for each validator, safe slashing protection can be achieved by refusing to sign messages for slots or epochs prior.

On the other hand, the complete strategy can provide safe slashing protection while also avoiding false positives (meaning that it only prevents a validator from signing if doing so would guarantee a slashing).

The two strategies are unified in the interchange format through the inclusion of conditions (2), (4) and (5). This allows the interchange to transfer detailed or succinct information, as desired.

Integer Representation

Most fields in the JSON schema are strings. For fields in which it is possible to encode the value as either a string or an integer, strings were chosen. This choice was made in order to avoid issues with different languages supporting different ranges of integers (specifically JavaScript, where the number type is a 64-bit float). If a validator is yet to sign a block or attestation, the relevant list is simply left empty.

Versioning

The interchange_format_version is set to 5 because the specification went through several breaking changes during its design, incorporating feedback from implementers.

Backwards Compatibility

This specification is not backwards-compatible with previous draft versions that used version numbers less than 5.

Security Considerations

In order to minimise risk and complexity, the format has been designed to map cleanly onto the internal database formats used by implementers. Nevertheless, there are a few pitfalls worth illuminating.

Advice for Complete Databases

For implementers who use a complete record of signed messages to implement their slashing protection database, we make the following recommendations:

You MUST ensure that, in addition to importing all of the messages from an interchange, all the conditions are enforced. In particular, conditions (2), (4) and (5) may not have been enforced by your implementation before adopting the interchange format. Our recommendation is to enforce these rules at all times, to keep the implementation clean and minimise the attack surface. For example: your slashing protection mechanism should not sign a block with a slot number less than, or equal to, the minimum slot number of a previously signed block, irrespective of whether that minimum-slot block was imported from an interchange file, or inserted as part of your database’s regular operation.
If your database records the signing roots of messages in addition to their slot/epochs, you should ensure that imported messages without signing roots are assigned a suitable dummy signing root internally. We suggest using a special “null” value which is distinct from all other signing roots, although a value like 0x0 may be used instead (as it is extremely unlikely to collide with any real signing root).
Care must be taken to avoid signing messages within a gap in the database (an area of unknown signing activity). This could occur if two interchanges were imported with a large gap between the last entry of the first and the first entry of the second. Signing in this gap is not safe, and would violate conditions (2), (4) and (5). It can be avoided by storing an explicit low watermark in addition to the actual messages of the slashing protection database, or by pruning on import so that the oldest messages from the interchange become the oldest messages in the database.

Advice for Minimal Databases

For implementers who wish to implement their slashing protection database by storing only the latest block and attestation for each validator, we make the following recommendations:

During import, make sure you take the maximum slot block and maximum source and target attestations for each validator. Although the conditions require the minimums to be enforced, taking the maximums from an interchange file and merging them with any existing values in the database is the recommended approach. For example, if the interchange file includes blocks for validator V at slots 4, 98 and 243, then the latest signed block for validator V should be updated to the one from slot 243. However, if the database has already included a block for this validator at a slot greater than 243, for example, slot 351, then the database’s existing value should remain unchanged.

General Recommendations

To avoid exporting an outdated interchange file – an action which creates a slashing risk – your implementation should only allow the slashing protection database to be exported when the validator client or signer is stopped – in other words, when the client or signer is no longer adding new messages to the database.
Similarly, your implementation should only allow an interchange file to be imported when the validator client is stopped.

Copyright

EVM trace specification

Mon, 07 Dec 2020 00:00:00 +0000

EIP #3155 - EVM trace specification is in Last Call status. It is authored by Martin Holst Swende (@holiman), Marius van der Wijden (@MariusVanDerWijden) and was originally created 2020-12-07. It is in the Interface category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-3155-create-evm-trace-specification/5007

Abstract

Introduce a new JSON standard for EVM traces during execution of state tests.

Motivation

The Ethereum Virtual Machine executes all smart contract code on ethereum. In order to debug smart contracts and state tests better, a common format was introduced to log every execution step of the EVM. This format was implemented by Go-Ethereum, Parity-Ethereum, Nethermind and Besu. Since the common format was not well-defined, the implementations differed slightly, making it hard to develop adequate tooling which reduces the usefulness of tracing significantly.

This EIP has multiple goals:

Move the specification to a more visible place to encourage new clients to implement it
Strictly define corner cases that were not addressed in the previous version
Allow for updates to the specification in case new fields are introduced during execution
Provide sample output

Implementing this EIP in all major clients allows us to create meaningful differential fuzzers that fuzz EVM implementations for the mainnet and all upcoming hardforks. It also helps to find differences in execution quickly in the case of a chain split.

This EIP will enable users to create better differential fuzzing infrastructure to compare the EVM implementations of all major Ethereum clients against each other. This could help to find bugs that are currently present in the client implementations.

Specification

Clients should be able to execute simple transactions as well as code and return traces. In the following, we will call this client CUT (client under test) and use go-ethereum’s evm binary for code examples.

Datatypes

Type	Explanation	Example
Number	Plain json number	“pc”:0
Hex-Number	Hex-encoded number	“gas”:”0x2540be400”
String	Plain string	“opName”:”PUSH1”
Hex-String	Hex-encoded string
Array of x	Array of x encoded values
Key-Value	Key-Value structure with key and values encoded as hex strings
Boolean	Json bool can either be true or false	“pass”: true

Output

The CUT MUST output a json object for EACH operation.

Required Fields

Name	Type	Explanation
`pc`	Number	Program Counter
`op`	Number	OpCode
`gas`	Hex-Number	Gas left before executing this operation
`gasCost`	Hex-Number	Gas cost of this operation
`memSize`	Number	Size of memory array
`stack`	Array of Hex-Numbers	Array of all values on the stack
`depth`	Number	Depth of the call stack
`returnData`	Hex-String	Data returned by function call
`refund`	Number	Amount of global gas refunded

Optional Fields

Name	Type	Explanation
`opName`	String	Name of the operation
`error`	Hex-String	Description of an error (should contain revert reason if supported)
`memory`	Array of Hex-Strings	Array of all allocated values
`storage`	Key-Value	Array of all stored values

Example:

{"pc":0,"op":96,"gas":"0x2540be400","gasCost":"0x3","memory":"0x","memSize":0,"stack":[],"depth":1,"error":null,"opName":"PUSH1"}

The stack, memory and memSize are the values before execution of the op.
All array attributes (stack, memory) MUST be initialized to empty arrays ("stack":[]) NOT to null.
If the CUT will not be outputting values for memory or storage then the memory and storage fields are omitted. This can happen either because the CUT does not support tracing these fields or it has been configured not to trace it.
The memSize field MUST be present regardless of memory support.
Clients SHOULD implement a way to disable recording the storage as the stateroot includes all storage updates.
Clients SHOULD output the fields in the same order as listed in this EIP.

The CUT MUST NOT output a line for the STOP operation if an error occurred:

Example:

{"pc":2,"op":0,"gas":"0x2540be3fd","gasCost":"0x0","memory":"0x","memSize":0,"stack":["0x40"],"depth":1,"error":null,"opName":"STOP"}

Summary and Error Handling

At the end of execution, the CUT MUST print summary info; this info SHOULD have the following fields. The summary should be a single jsonl object.

Required Fields

Name	Type	Explanation
`stateRoot`	Hex-String	Root of the state trie after executing the transaction
`output`		Return values of the function
`gasUsed`	Hex-Number	All gas used by the transaction
`pass`	Boolean	Bool whether transaction was executed successfully

Optional Fields

Name	Type	Explanation
`time`	Number	Time in nanoseconds needed to execute the transaction
`fork`	String	Name of the fork rules used for execution

Example:

{"stateRoot":"0xd4c577737f5d20207d338c360c42d3af78de54812720e3339f7b27293ef195b7","output":"","gasUsed":"0x3","pass":"true","time":141485}

Rationale

This EIP is largely based on the previous non-official documentation for EVM tracing. It tries to cover as many corner cases as possible to enable true client compatibility. The datatypes and if a field is optional is chosen to be as compatible with current implementations as possible.

Backwards Compatibility

This EIP is fully backward compatible with ethereum as it only introduces a better tracing infrastructure that is optional for clients to implement.

Clients

This EIP is fully backward compatible with go-ethereum. OpenEthereum, Besu and Nethermind clients would have to change their JSON output of openethereum-evm evmtool and nethtest slightly do adhere to the new and stricter specs. New clients would need to implement this change if they want to be part of the differential fuzzing group.

Test Cases

${BESU_HOME}/bin/evmtool --code 0x604080536040604055604060006040600060025afa6040f3 {"pc":0,"op":96,"gas":"0x2540be400","gasCost":"0x3","memSize":0,"stack":[],"depth":1,"refund":0,"opName":"PUSH1"}
{"pc":2,"op":128,"gas":"0x2540be3fd","gasCost":"0x3","memSize":0,"stack":["0x40"],"depth":1,"refund":0,"opName":"DUP1"}
{"pc":3,"op":83,"gas":"0x2540be3fa","gasCost":"0xc","memSize":0,"stack":["0x40","0x40"],"depth":1,"refund":0,"opName":"MSTORE8"}
{"pc":4,"op":96,"gas":"0x2540be3ee","gasCost":"0x3","memory":"0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000","memSize":96,"stack":[],"depth":1,"refund":0,"opName":"PUSH1"}
{"pc":6,"op":96,"gas":"0x2540be3eb","gasCost":"0x3","memory":"0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000","memSize":96,"stack":["0x40"],"depth":1,"refund":0,"opName":"PUSH1"}
{"pc":8,"op":85,"gas":"0x2540be3e8","gasCost":"0x4e20","memory":"0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000","memSize":96,"stack":["0x40","0x40"],"depth":1,"refund":0,"opName":"SSTORE"}
{"pc":9,"op":96,"gas":"0x2540b95c8","gasCost":"0x3","memory":"0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000","memSize":96,"stack":[],"depth":1,"refund":0,"opName":"PUSH1"}
{"pc":11,"op":96,"gas":"0x2540b95c5","gasCost":"0x3","memory":"0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000","memSize":96,"stack":["0x40"],"depth":1,"refund":0,"opName":"PUSH1"}
{"pc":13,"op":96,"gas":"0x2540b95c2","gasCost":"0x3","memory":"0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000","memSize":96,"stack":["0x40","0x0"],"depth":1,"refund":0,"opName":"PUSH1"}
{"pc":15,"op":96,"gas":"0x2540b95bf","gasCost":"0x3","memory":"0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000","memSize":96,"stack":["0x40","0x0","0x40"],"depth":1,"refund":0,"opName":"PUSH1"}
{"pc":17,"op":96,"gas":"0x2540b95bc","gasCost":"0x3","memory":"0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000","memSize":96,"stack":["0x40","0x0","0x40","0x0"],"depth":1,"refund":0,"opName":"PUSH1"}
{"pc":19,"op":90,"gas":"0x2540b95b9","gasCost":"0x2","memory":"0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000","memSize":96,"stack":["0x40","0x0","0x40","0x0","0x2"],"depth":1,"refund":0,"opName":"GAS"}
{"pc":20,"op":250,"gas":"0x2540b95b7","gasCost":"0x24abb676c","memory":"0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000","memSize":96,"stack":["0x40","0x0","0x40","0x0","0x2","0x2540b95b7"],"depth":1,"refund":0,"opName":"STATICCALL"}
{"pc":21,"op":96,"gas":"0x2540b92a7","gasCost":"0x3","memory":"0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b00000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000","memSize":96,"stack":["0x1"],"returnData":"0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b","depth":1,"refund":0,"opName":"PUSH1"}
{"pc":23,"op":243,"gas":"0x2540b92a4","gasCost":"0x0","memory":"0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b00000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000","memSize":96,"stack":["0x1","0x40"],"returnData":"0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b","depth":1,"refund":0,"opName":"RETURN"}
{"stateRoot":"0x8fa0dcc7f1d2383c89e5737c2843632db881c0946e80b71fe7175365e6538797","output":"0x40","gasUsed":"0x515c","pass":true,"fork":"Istanbul"}

Security Considerations

Tracing is expensive.

Exposing an endpoint for creating traces publicly could open up a denial of service vector.

Clients should consider putting trace endpoints behind a separate flag from other endpoints.

Copyright

ERC-721 Nonce Extension

Sun, 10 Apr 2022 00:00:00 +0000

EIP #5008 - ERC-721 Nonce Extension is in Last Call status. It is authored by Anders (@0xanders), Lance (@LanceSnow), Shrug and was originally created 2022-04-10. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip5008-eip-721-nonce-and-metadata-update-extension/8925

Abstract

This standard is an extension of ERC-721. It proposes adding a nonce function to ERC-721 tokens.

Motivation

Some orders of NFT marketplaces have been attacked and the NFTs sold at a lower price than the current market floor price. This can happen when users transfer an NFT to another wallet and, later, back to the original wallet. This reactivates the order, which may list the token at a much lower price than the owner would have intended.

This EIP proposes adding a nonce property to ERC-721 tokens, and the nonce will be changed when a token is transferred. If a nonce is added to an order, the order can be checked to avoid attacks.

Specification

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY” and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

/// @dev the ERC-165 identifier for this interface is 0xce03fdab.
interface IERC5008 /* is IERC165 */ {
    /// @notice Emitted when the `nonce` of an NFT is changed
    event NonceChanged(uint256 tokenId, uint256 nonce);

    /// @notice Get the nonce of an NFT
    /// Throws if `tokenId` is not a valid NFT
    /// @param tokenId The id of the NFT
    /// @return The nonce of the NFT
    function nonce(uint256 tokenId) external view returns(uint256);
}

The nonce(uint256 tokenId) function MUST be implemented as view.

The supportsInterface method MUST return true when called with 0xce03fdab.

Rationale

At first transferCount was considered as function name, but there may some case to change the nonce besides transfer, such as important properties changed, then we changed transferCount to nonce.

Backwards Compatibility

This standard is compatible with ERC-721.

Test Cases

Test cases are included in test.js.

Run:

cd ../assets/eip-5008
npm install
npm run test

Reference Implementation

See ERC5008.sol.

Security Considerations

No security issues found.

Copyright

Soulbound Badge

Mon, 30 May 2022 00:00:00 +0000

EIP #5114 - Soulbound Badge is in Last Call status. It is authored by Micah Zoltu (@MicahZoltu) and was originally created 2022-05-30. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-5114-soulbound-token/9417

Abstract

A soulbound badge is a token that, when minted, is bound to another Non-Fungible Token (NFT), and cannot be transferred/moved after that.

Specification

interface IERC5114 {
	// fired anytime a new instance of this badge is minted
	// this event **MUST NOT** be fired twice for the same `badgeId`
	event Mint(uint256 indexed badgeId, address indexed nftAddress, uint256 indexed nftTokenId);

	// returns the NFT that this badge is bound to.
	// this function **MUST** throw if the badge hasn't been minted yet
	// this function **MUST** always return the same result every time it is called after it has been minted
	// this function **MUST** return the same value as found in the original `Mint` event for the badge
	function ownerOf(uint256 badgeId) external view returns (address nftAddress, uint256 nftTokenId);

	// returns a URI with details about this badge collection
	// the metadata returned by this is merged with the metadata return by `badgeUri(uint256)`
	// the collectionUri **MUST** be immutable (e.g., ipfs:// and not http://)
	// the collectionUri **MUST** be content addressable (e.g., ipfs:// and not http://)
	// data from `badgeUri` takes precedence over data returned by this method
	// any external links referenced by the content at `collectionUri` also **MUST** follow all of the above rules
	function collectionUri() external pure returns (string collectionUri);

	// returns a censorship resistant URI with details about this badge instance
	// the collectionUri **MUST** be immutable (e.g., ipfs:// and not http://)
	// the collectionUri **MUST** be content addressable (e.g., ipfs:// and not http://)
	// data from this takes precedence over data returned by `collectionUri`
	// any external links referenced by the content at `badgeUri` also **MUST** follow all of the above rules
	function badgeUri(uint256 badgeId) external view returns (string badgeUri);

	// returns a string that indicates the format of the `badgeUri` and `collectionUri` results (e.g., 'EIP-ABCD' or 'soulbound-schema-version-4')
	function metadataFormat() external pure returns (string format);
}

Implementers of this standard SHOULD also depend on a standard for interface detection so callers can easily find out if a given contract implements this interface.

Rationale

Immutability

By requiring that badges can never move, we both guarantee non-separability and non-mergeability among collections of soulbound badges that are bound to a single NFT while simultaneously allowing users to aggressively cache results.

Content Addressable URIs Required

Soulbound badges are meant to be permanent badges/indicators attached to a persona. This means that not only can the user not transfer ownership, but the minter also cannot withdraw/transfer/change ownership as well. This includes mutating or removing any remote content as a means of censoring or manipulating specific users.

No Specification for `badgeUri` Data Format

The format of the data pointed to by collectionUri() and badgeUri(uint256), and how to merge them, is intentionally left out of this standard in favor of separate standards that can be iterated on in the future. The immutability constraints are the only thing defined by this to ensure that the spirit of this badge is maintained, regardless of the specifics of the data format. The metadataFormat function can be used to inform a caller what type/format/version of data they should expect at the URIs, so the caller can parse the data directly without first having to deduce its format via inspection.

Backwards Compatibility

This is a new token type and is not meant to be backward compatible with any existing tokens other than existing viable souls (any asset that can be identified by [address,id]).

Security Considerations

Users of badges that claim to implement this EIP must be diligent in verifying they actually do. A badge author can create a badge that, upon initial probing of the API surface, may appear to follow the rules when in reality it doesn’t. For example, the contract could allow transfers via some mechanism and simply not utilize them initially.

It should also be made clear that soulbound badges are not bound to a human, they are bound to a persona. A persona is any actor (which could be a group of humans) that collects multiple soulbound badges over time to build up a collection of badges. This persona may transfer to another human, or to another group of humans, and anyone interacting with a persona should not assume that there is a single permanent human behind that persona.

It is possible for a soulbound badge to be bound to another soulbound badge. In theory, if all badges in the chain are created at the same time they could form a loop. Software that tries to walk such a chain should take care to have an exit strategy if a loop is detected.

Copyright

Cross-Chain Execution

Tue, 14 Jun 2022 00:00:00 +0000

EIP #5164 - Cross-Chain Execution is in Last Call status. It is authored by Brendan Asselstine (@asselstine), Pierrick Turelier (@PierrickGT), Chris Whinfrey (@cwhinfrey) and was originally created 2022-06-14. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-5164-cross-chain-execution/9658

Abstract

This specification defines a cross-chain execution interface for EVM-based blockchains. Implementations of this specification will allow contracts on one chain to call contracts on another by sending a cross-chain message.

The specification defines two components: the “Message Dispatcher” and the “Message Executor”. The Message Dispatcher lives on the calling side, and the executor lives on the receiving side. When a message is sent, a Message Dispatcher will move the message through a transport layer to a Message Executor, where they are executed. Implementations of this specification must implement both components.

Motivation

Many Ethereum protocols need to coordinate state changes across multiple EVM-based blockchains. These chains often have native or third-party bridges that allow Ethereum contracts to execute code. However, bridges have different APIs so bridge integrations are custom. Each one affords different properties; with varying degrees of security, speed, and control. Defining a simple, common specification will increase code re-use and allow us to use common bridge implementations.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

This specification allows contracts on one chain to send messages to contracts on another chain. There are two key interfaces that needs to be implemented:

MessageDispatcher
MessageExecutor

The MessageDispatcher lives on the origin chain and dispatches messages to the MessageExecutor for execution. The MessageExecutor lives on the destination chain and executes dispatched messages.

MessageDispatcher

The MessageDispatcher lives on the chain from which messages are sent. The Dispatcher’s job is to broadcast messages through a transport layer to one or more MessageExecutor contracts.

A unique messageId MUST be generated for each message or message batch. The message identifier MUST be unique across chains and dispatchers. This can be achieved by hashing a tuple of chainId, dispatcherAddress, messageNonce where messageNonce is a monotonically increasing integer per message.

MessageDispatcher Methods

dispatchMessage

Will dispatch a message to be executed by the MessageExecutor on the destination chain specified by toChainId.

MessageDispatchers MUST emit the MessageDispatched event when a message is dispatched.

MessageDispatchers MUST revert if toChainId is not supported.

MessageDispatchers MUST forward the message to a MessageExecutor on the toChainId.

MessageDispatchers MUST use a unique messageId for each message.

MessageDispatchers MUST return the messageId to allow the message sender to track the message.

MessageDispatchers MAY require payment.

interface MessageDispatcher {
  function dispatchMessage(uint256 toChainId, address to, bytes calldata data) external payable returns (bytes32 messageId);
}

- name: dispatchMessage
  type: function
  stateMutability: payable
  inputs:
    - name: toChainId
      type: uint256
    - name: to
      type: address
    - name: data
      type: bytes
  outputs:
    - name: messageId
      type: bytes32

MessageDispatcher Events

MessageDispatched

The MessageDispatched event MUST be emitted by the MessageDispatcher when an individual message is dispatched.

interface MessageDispatcher {
  event MessageDispatched(
    bytes32 indexed messageId,
    address indexed from,
    uint256 indexed toChainId,
    address to,
    bytes data,
  );
}

- name: MessageDispatched
  type: event
  inputs:
    - name: messageId
      indexed: true
      type: bytes32
    - name: from
      indexed: true
      type: address
    - name: toChainId
      indexed: true
      type: uint256
    - name: to
      type: address
    - name: data
      type: bytes

MessageExecutor

The MessageExecutor executes dispatched messages and message batches. Developers must implement a MessageExecutor in order to execute messages on the receiving chain.

The MessageExecutor will execute a messageId only once, but may execute messageIds in any order. This specification makes no ordering guarantees, because messages and message batches may travel non-sequentially through the transport layer.

Execution

MessageExecutors SHOULD verify all message data with the bridge transport layer.

MessageExecutors MUST NOT successfully execute a message more than once.

MessageExecutors MUST revert the transaction when a message fails to be executed allowing the message to be retried at a later time.

Calldata

MessageExecutors MUST append the ABI-packed (messageId, fromChainId, from) to the calldata for each message being executed. This allows the receiver of the message to verify the cross-chain sender and the chain that the message is coming from.

to.call(abi.encodePacked(data, messageId, fromChainId, from));

- name: calldata
  type: bytes
  inputs:
    - name: data
      type: bytes
    - name: messageId
      type: bytes32
    - name: fromChainId
      type: uint256
    - name: from
      type: address

MessageExecutor Events

MessageIdExecuted

MessageIdExecuted MUST be emitted once a message or message batch has been executed.

interface MessageExecutor {
  event MessageIdExecuted(
    uint256 indexed fromChainId,
    bytes32 indexed messageId
  );
}

- name: MessageIdExecuted
  type: event
  inputs:
    - name: fromChainId
      indexed: true
      type: uint256
    - name: messageId
      indexed: true
      type: bytes32

MessageExecutor Errors

MessageAlreadyExecuted

MessageExecutors MUST revert if a messageId has already been executed and SHOULD emit a MessageIdAlreadyExecuted custom error.

interface MessageExecutor {
  error MessageIdAlreadyExecuted(
    bytes32 messageId
  );
}

MessageFailure

MessageExecutors MUST revert if an individual message fails and SHOULD emit a MessageFailure custom error.

interface MessageExecutor {
  error MessageFailure(
    bytes32 messageId,
    bytes errorData
  );
}

Rationale

The MessageDispatcher can be coupled to one or more MessageExecutor. It is up to bridges to decide how to couple the two. Users can easily bridge a message by calling dispatchMessage without being aware of the MessageExecutor address. Messages can also be traced by a client using the data logged by the MessageIdExecuted event.

Some bridges may require payment in the native currency, so the dispatchMessage function is payable.

Backwards Compatibility

This specification is compatible with existing governance systems as it offers simple cross-chain execution.

Security Considerations

Bridge trust profiles are variable, so users must understand that bridge security depends on the implementation.

Copyright

ERC-1155 Allowance Extension

Mon, 11 Jul 2022 00:00:00 +0000

EIP #5216 - ERC-1155 Allowance Extension is in Last Call status. It is authored by Iván Mañús (@ivanmmurciaua), Juan Carlos Cantó (@EscuelaCryptoES) and was originally created 2022-07-11. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-erc1155-approval-by-amount/9898

Abstract

This ERC defines standard functions for granular approval of ERC-1155 tokens by both id and amount. This ERC extends ERC-1155.

Motivation

ERC-1155’s popularity means that multi-token management transactions occur on a daily basis. Although it can be used as a more comprehensive alternative to ERC-721, ERC-1155 is most commonly used as intended: creating multiple ids, each with multiple tokens. While many projects interface with these semi-fungible tokens, by far the most common interactions are with NFT marketplaces.

Due to the nature of the blockchain, programming errors or malicious operators can cause permanent loss of funds. It is therefore essential that transactions are as trustless as possible. ERC-1155 uses the setApprovalForAll function, which approves ALL tokens with a specific id. This system has obvious minimum required trust flaws. This ERC combines ideas from ERC-20 and ERC-721 in order to create a trust mechanism where an owner can allow a third party, such as a marketplace, to approve a limited (instead of unlimited) number of tokens of one id.

Specification

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Contracts using this ERC MUST implement the IERC5216 interface.

Interface implementation

/**
 * @title ERC-1155 Allowance Extension
 * Note: the ERC-165 identifier for this interface is 0x1be07d74
 */
interface IERC5216 is IERC1155 {

    /**
     * @notice Emitted when `account` grants or revokes permission to `operator` to transfer their tokens, according to
     * `id` and with an amount: `amount`.
     */
    event Approval(address indexed account, address indexed operator, uint256 id, uint256 amount);

    /**
     * @notice Grants permission to `operator` to transfer the caller's tokens, according to `id`, and an amount: `amount`.
     * Emits an {Approval} event.
     *
     * Requirements:
     * - `operator` cannot be the caller.
     */
    function approve(address operator, uint256 id, uint256 amount) external;

    /**
     * @notice Returns the amount allocated to `operator` approved to transfer `account`'s tokens, according to `id`.
     */
    function allowance(address account, address operator, uint256 id) external view returns (uint256);
}

The approve(address operator, uint256 id, uint256 amount) function MUST be either public or external.

The allowance(address account, address operator, uint256 id) function MUST be either public or external and MUST be view.

The safeTrasferFrom function (as defined by ERC-1155) MUST:

Not revert if the user has approved msg.sender with a sufficient amount
Subtract the transferred amount of tokens from the approved amount if msg.sender is not approved with setApprovalForAll

In addition, the safeBatchTransferFrom MUST:

Add an extra condition that checks if the allowance of all ids have the approved amounts (See _checkApprovalForBatch function reference implementation)

The Approval event MUST be emitted when a certain number of tokens are approved.

The supportsInterface method MUST return true when called with 0x1be07d74.

Rationale

The name “ERC-1155 Allowance Extension” was chosen because it is a succinct description of this ERC. Users can approve their tokens by id and amount to operators.

By having a way to approve and revoke in a manner similar to ERC-20, the trust level can be more directly managed by users:

Using the approve function, users can approve an operator to spend an amount of tokens for each id.
Using the allowance function, users can see the approval that an operator has for each id.

The ERC-20 name patterns were used due to similarities with ERC-20 approvals.

Backwards Compatibility

This standard is compatible with ERC-1155.

Reference Implementation

The reference implementation can be found here.

Security Considerations

Users of this ERC must thoroughly consider the amount of tokens they give permission to operators, and should revoke unused authorizations.

Copyright

Endorsement - Permit for Any Functions

Fri, 12 Aug 2022 00:00:00 +0000

EIP #5453 - Endorsement - Permit for Any Functions is in Last Call status. It is authored by Zainan Victor Zhou (@xinbenlv) and was originally created 2022-08-12. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/erc-5453-endorsement-standard/10355

Abstract

This EIP establishes a general protocol for permitting and approving function calls in the same transaction relying on ERC-5750. Unlike a few prior art (ERC-2612 for ERC-20, ERC-4494 for ERC-721 that usually only permit for a single behavior (transfer for ERC-20 and safeTransferFrom for ERC-721) and a single approver in two transactions (first a permit(...) TX, then a transfer-like TX), this EIP provides a way to permit arbitrary behaviors and aggregating multiple approvals from arbitrary number of approvers in the same transaction, allowing for Multi-Sig or Threshold Signing behavior.

Motivation

Support permit(approval) alongside a function call.
Support a second approval from another user.
Support pay-for-by another user
Support multi-sig
Support persons acting in concert by endorsements
Support accumulated voting
Support off-line signatures

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Interfaces

The interfaces and structures referenced here are as follows

pragma solidity ^0.8.9;

struct ValidityBound {
    bytes32 functionParamStructHash;
    uint256 validSince;
    uint256 validBy;
    uint256 nonce;
}

struct SingleEndorsementData {
    address endorserAddress; // 32
    bytes sig; // dynamic = 65
}

struct GeneralExtensionDataStruct {
    bytes32 erc5453MagicWord;
    uint256 erc5453Type;
    uint256 nonce;
    uint256 validSince;
    uint256 validBy;
    bytes endorsementPayload;
}

interface IERC5453EndorsementCore {
    function eip5453Nonce(address endorser) external view returns (uint256);
    function isEligibleEndorser(address endorser) external view returns (bool);
}

interface IERC5453EndorsementDigest {
    function computeValidityDigest(
        bytes32 _functionParamStructHash,
        uint256 _validSince,
        uint256 _validBy,
        uint256 _nonce
    ) external view returns (bytes32);

    function computeFunctionParamHash(
        string memory _functionName,
        bytes memory _functionParamPacked
    ) external view returns (bytes32);
}

interface IERC5453EndorsementDataTypeA {
    function computeExtensionDataTypeA(
        uint256 nonce,
        uint256 validSince,
        uint256 validBy,
        address endorserAddress,
        bytes calldata sig
    ) external view returns (bytes memory);
}


interface IERC5453EndorsementDataTypeB {
    function computeExtensionDataTypeB(
        uint256 nonce,
        uint256 validSince,
        uint256 validBy,
        address[] calldata endorserAddress,
        bytes[] calldata sigs
    ) external view returns (bytes memory);
}

See IERC5453.sol.

Behavior specification

As specified in ERC-5750 General Extensibility for Method Behaviors, any compliant method that has a bytes extraData parameter as its last designated parameter for extending behaviors can conform to ERC-5453 as the way to indicate a permit from a certain user.

Any compliant method of this EIP MUST be a ERC-5750 compliant method.
Caller MUST pass in the last parameter bytes extraData conforming to Solidity memory-encoded bytes of GeneralExtensionDataStruct specified in Section Interfaces. The following descriptions are based on when decoding bytes extraData into a GeneralExtensionDataStruct
In the GeneralExtensionDataStruct-decoded extraData, caller MUST set the value of GeneralExtensionDataStruct.erc5453MagicWord to be the keccak256("ERC5453-ENDORSEMENT").
Caller MUST set the value of GeneralExtensionDataStruct.erc5453Type to be one of the supported values.

uint256 constant ERC5453_TYPE_A = 1;
uint256 constant ERC5453_TYPE_B = 2;

When the value of GeneralExtensionDataStruct.erc5453Type is set to be ERC5453_TYPE_A, GeneralExtensionDataStruct.endorsementPayload MUST be abi encoded bytes of a SingleEndorsementData.
When the value of GeneralExtensionDataStruct.erc5453Type is set to be ERC5453_TYPE_B, GeneralExtensionDataStruct.endorsementPayload MUST be abi encoded bytes of SingleEndorsementData[] (a dynamic array).
Each SingleEndorsementData MUST have a address endorserAddress; and a 65-bytes bytes sig signature.
Each bytes sig MUST be an ECDSA (secp256k1) signature using private key of signer whose corresponding address is endorserAddress signing validityDigest which is the hashTypeDataV4 of EIP-712 of hashStruct of ValidityBound data structure as follows:

bytes32 validityDigest =
    eip712HashTypedDataV4(
        keccak256(
            abi.encode(
                keccak256(
                    "ValidityBound(bytes32 functionParamStructHash,uint256 validSince,uint256 validBy,uint256 nonce)"
                ),
                functionParamStructHash,
                _validSince,
                _validBy,
                _nonce
            )
        )
    );

The functionParamStructHash MUST be computed as follows

        bytes32 functionParamStructHash = keccak256(
            abi.encodePacked(
                keccak256(bytes(_functionStructure)),
                _functionParamPacked
            )
        );
        return functionParamStructHash;

whereas

_functionStructure MUST be computed as function methodName(type1 param1, type2 param2, ...).
_functionParamPacked MUST be computed as enc(param1) || enco(param2) ...

Upon validating that endorserAddress == ecrecover(validityDigest, signature) or EIP1271(endorserAddress).isValidSignature(validityDigest, signature) == ERC1271.MAGICVALUE, the single endorsement MUST be deemed valid.
Compliant method MAY choose to impose a threshold for a number of endorsements needs to be valid in the same ERC5453_TYPE_B kind of endorsementPayload.
The validSince and validBy are both inclusive. Implementer MAY choose to use blocknumber or timestamp. Implementors SHOULD find a way to indicate whether validSince and validBy is blocknumber or timestamp.

Rationale

We chose to have both ERC5453_TYPE_A(single-endorsement) and ERC5453_TYPE_B(multiple-endorsements, same nonce for entire contract) so we could balance a wider range of use cases. E.g. the same use cases of ERC-2612 and ERC-4494 can be supported by ERC5453_TYPE_A. And threshold approvals can be done via ERC5453_TYPE_B. More complicated approval types can also be extended by defining new ERC5453_TYPE_?
We chose to include both validSince and validBy to allow maximum flexibility in expiration. This can also be supported natively by the EVM if ERC-5081 is adopted, but ERC-5081 will not be adopted anytime soon, so we choose to add these two numbers in our protocol to allow smart contract level support.

Backwards Compatibility

The design assumes a bytes calldata extraData to maximize the flexibility of future extensions. This assumption is compatible with ERC-721, ERC-1155 and many other ERC-track EIPs. Those that aren’t, such as ERC-20, can also be updated to support it, such as using a wrapper contract or proxy upgrade.

Reference Implementation

In addition to the specified algorithm for validating endorser signatures, we also present the following reference implementations.

pragma solidity ^0.8.9;

import "@openzeppelin/contracts/utils/cryptography/SignatureChecker.sol";
import "@openzeppelin/contracts/utils/cryptography/EIP712.sol";

import "./IERC5453.sol";

abstract contract AERC5453Endorsible is EIP712,
    IERC5453EndorsementCore, IERC5453EndorsementDigest, IERC5453EndorsementDataTypeA, IERC5453EndorsementDataTypeB {
    // ...

    function _validate(
        bytes32 msgDigest,
        SingleEndorsementData memory endersement
    ) internal virtual {
        require(
            endersement.sig.length == 65,
            "AERC5453Endorsible: wrong signature length"
        );
        require(
            SignatureChecker.isValidSignatureNow(
                endersement.endorserAddress,
                msgDigest,
                endersement.sig
            ),
            "AERC5453Endorsible: invalid signature"
        );
    }
    // ...

    modifier onlyEndorsed(
        bytes32 _functionParamStructHash,
        bytes calldata _extensionData
    ) {
        require(_isEndorsed(_functionParamStructHash, _extensionData));
        _;
    }

    function computeExtensionDataTypeB(
        uint256 nonce,
        uint256 validSince,
        uint256 validBy,
        address[] calldata endorserAddress,
        bytes[] calldata sigs
    ) external pure override returns (bytes memory) {
        require(endorserAddress.length == sigs.length);
        SingleEndorsementData[]
            memory endorsements = new SingleEndorsementData[](
                endorserAddress.length
            );
        for (uint256 i = 0; i < endorserAddress.length; ++i) {
            endorsements[i] = SingleEndorsementData(
                endorserAddress[i],
                sigs[i]
            );
        }
        return
            abi.encode(
                GeneralExtensionDataStruct(
                    MAGIC_WORLD,
                    ERC5453_TYPE_B,
                    nonce,
                    validSince,
                    validBy,
                    abi.encode(endorsements)
                )
            );
    }
}

See AERC5453.sol

Reference Implementation of `EndorsableERC721`

Here is a reference implementation of EndorsableERC721 that achieves similar behavior to ERC-4494.

pragma solidity ^0.8.9;

contract EndorsableERC721 is ERC721, AERC5453Endorsible {
    //...

    function mint(
        address _to,
        uint256 _tokenId,
        bytes calldata _extraData
    )
        external
        onlyEndorsed(
            _computeFunctionParamHash(
                "function mint(address _to,uint256 _tokenId)",
                abi.encode(_to, _tokenId)
            ),
            _extraData
        )
    {
        _mint(_to, _tokenId);
    }
}

See EndorsableERC721.sol

Reference Implementation of `ThresholdMultiSigForwarder`

Here is a reference implementation of ThresholdMultiSigForwarder that achieves similar behavior of multi-sig threshold approval remote contract call like a Gnosis-Safe wallet.

pragma solidity ^0.8.9;

contract ThresholdMultiSigForwarder is AERC5453Endorsible {
    //...
    function forward(
        address _dest,
        uint256 _value,
        uint256 _gasLimit,
        bytes calldata _calldata,
        bytes calldata _extraData
    )
        external
        onlyEndorsed(
            _computeFunctionParamHash(
                "function forward(address _dest,uint256 _value,uint256 _gasLimit,bytes calldata _calldata)",
                abi.encode(_dest, _value, _gasLimit, keccak256(_calldata))
            ),
            _extraData
        )
    {
        string memory errorMessage = "Fail to call remote contract";
        (bool success, bytes memory returndata) = _dest.call{value: _value}(
            _calldata
        );
        Address.verifyCallResult(success, returndata, errorMessage);
    }

}

See ThresholdMultiSigForwarder.sol

Security Considerations

Replay Attacks

A replay attack is a type of attack on cryptography authentication. In a narrow sense, it usually refers to a type of attack that circumvents the cryptographically signature verification by reusing an existing signature for a message being signed again. Any implementations relying on this EIP must realize that all smart endorsements described here are cryptographic signatures that are public and can be obtained by anyone. They must foresee the possibility of a replay of the transactions not only at the exact deployment of the same smart contract, but also other deployments of similar smart contracts, or of a version of the same contract on another chainId, or any other similar attack surfaces. The nonce, validSince, and validBy fields are meant to restrict the surface of attack but might not fully eliminate the risk of all such attacks, e.g. see the Phishing section.

Phishing

It’s worth pointing out a special form of replay attack by phishing. An adversary can design another smart contract in a way that the user may be tricked into signing a smart endorsement for a seemingly legitimate purpose, but the data-to-designed matches the target application

Copyright

Multi-privilege Management NFT Extension

Sat, 30 Jul 2022 00:00:00 +0000

EIP #5496 - Multi-privilege Management NFT Extension is in Last Call status. It is authored by Jeremy Z (@wnft) and was originally created 2022-07-30. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-5496-multi-privilege-management-extension-for-erc-721/10427

Abstract

This EIP defines an interface extending EIP-721 to provide shareable multi-privileges for NFTs. Privileges may be on-chain (voting rights, permission to claim an airdrop) or off-chain (a coupon for an online store, a discount at a local restaurant, access to VIP lounges in airports). Each NFT may contain many privileges, and the holder of a privilege can verifiably transfer that privilege to others. Privileges may be non-shareable or shareable. Shareable privileges can be cloned, with the provider able to adjust the details according to the spreading path. Expiration periods can also be set for each privilege.

Motivation

This standard aims to efficiently manage privileges attached to NFTs in real-time. Many NFTs have functions other than just being used as profile pictures or art collections, they may have real utilities in different scenarios. For example, a fashion store may give a discount for its own NFT holders; a DAO member NFT holder can vote for the proposal of how to use their treasury; a dApp may create an airdrop event to attract a certain group of people like some blue chip NFT holders to claim; the grocery store can issue its membership card on chain (as an NFT) and give certain privileges when the members shop at grocery stores, etc. There are cases when people who own NFTs do not necessarily want to use their privileges. By providing additional data recording different privileges a NFT collection has and interfaces to manage them, users can transfer or sell privileges without losing their ownership of the NFT.

EIP-721 only records the ownership and its transfer, the privileges of an NFT are not recorded on-chain. This extension would allow merchants/projects to give out a certain privilege to a specified group of people, and owners of the privileges can manage each one of the privileges independently. This facilitates a great possibility for NFTs to have real usefulness.

For example, an airline company issues a series of EIP-721/EIP-1155 tokens to Crypto Punk holders to give them privileges, in order to attract them to join their club. However, since these tokens are not bound to the original NFT, if the original NFT is transferred, these privileges remain in the hands of the original holders, and the new holders cannot enjoy the privileges automatically. So, we propose a set of interfaces that can bind the privileges to the underlying NFT, while allowing users to manage the privileges independently.

Specification

Every contract complying with this standard MUST implement the IERC5496 interface. The shareable multi-privilege extension is OPTIONAL for EIP-721 contracts.

/// @title multi-privilege extension for EIP-721
///  Note: the EIP-165 identifier for this interface is 0x076e1bbb
interface IERC5496{
    /// @notice Emitted when `owner` changes the `privilege holder` of a NFT.
    event PrivilegeAssigned(uint256 tokenId, uint256 privilegeId, address user, uint256 expires);
    /// @notice Emitted when `contract owner` changes the `total privilege` of the collection
    event PrivilegeTotalChanged(uint256 newTotal, uint256 oldTotal);

    /// @notice set the privilege holder of a NFT.
    /// @dev expires should be less than 30 days
    /// Throws if `msg.sender` is not approved or owner of the tokenId.
    /// @param tokenId The NFT to set privilege for
    /// @param privilegeId The privilege to set
    /// @param user The privilege holder to set
    /// @param expires For how long the privilege holder can have
    function setPrivilege(uint256 tokenId, uint256 privilegeId, address user, uint256 expires) external;

    /// @notice Return the expiry timestamp of a privilege
    /// @param tokenId The identifier of the queried NFT
    /// @param privilegeId The identifier of the queried privilege
    /// @return Whether a user has a certain privilege
    function privilegeExpires(uint256 tokenId, uint256 privilegeId) external view returns(uint256);

    /// @notice Check if a user has a certain privilege
    /// @param tokenId The identifier of the queried NFT
    /// @param privilegeId The identifier of the queried privilege
    /// @param user The address of the queried user
    /// @return Whether a user has a certain privilege
    function hasPrivilege(uint256 tokenId, uint256 privilegeId, address user) external view returns(bool);
}

Every contract implementing this standard SHOULD set a maximum privilege number before setting any privilege, the privilegeId MUST NOT be greater than the maximum privilege number.

The PrivilegeAssigned event MUST be emitted when setPrivilege is called.

The PrivilegeTotalChanged event MUST be emitted when the total privilege of the collection is changed.

The supportsInterface method MUST return true when called with 0x076e1bbb.

/// @title Cloneable extension - Optional for EIP-721
interface IERC721Cloneable {
    /// @notice Emitted when set the `privilege ` of a NFT cloneable.
    event PrivilegeCloned(uint tokenId, uint privId, address from, address to);

    /// @notice set a certain privilege cloneable
    /// @param tokenId The identifier of the queried NFT
    /// @param privilegeId The identifier of the queried privilege
    /// @param referrer The address of the referrer
    /// @return Whether the operation is successful or not
    function clonePrivilege(uint tokenId, uint privId, address referrer) external returns (bool);
}

The PrivilegeCloned event MUST be emitted when clonePrivilege is called.

For Compliant contract, it is RECOMMENDED to use EIP-1271 to validate the signatures.

Rationale

Shareable Privileges

The number of privilege holders is limited by the number of NFTs if privileges are non-shareable. A shareable privilege means the original privilege holder can copy the privilege and give it to others, not transferring his/her own privilege to them. This mechanism greatly enhances the spread of privileges as well as the adoption of NFTs.

Expire Date Type

The expiry timestamp of a privilege is a timestamp and stored in uint256 typed variables.

Beneficiary of Referrer

For example, a local pizza shop offers a 30% off Coupon and the owner of the shop encourages their consumers to share the coupon with friends, then the friends can get the coupon. Let’s say Tom gets 30% off Coupon from the shop and he shares the coupon with Alice. Alice gets the coupon too and Alice’s referrer is Tom. For some certain cases, Tom may get more rewards from the shop. This will help the merchants in spreading the promotion among consumers.

Proposal: NFT Transfer

If the owner of the NFT transfers ownership to another user, there is no impact on “privileges”. But errors may occur if the owner tries to withdraw the original EIP-721 token from the wrapped NFT through unwrap() if any available privileges are still ongoing. We protect the rights of holders of the privileges to check the last expiration date of the privilege.

function unwrap(uint256 tokenId, address to) external {
    require(getBlockTimestamp() >= privilegeBook[tokenId].lastExpiresAt, "privilege not yet expired");

    require(ownerOf(tokenId) == msg.sender, "not owner");

    _burn(tokenId);

    IERC721(nft).transferFrom(address(this), to, tokenId);

    emit Unwrap(nft, tokenId, msg.sender, to);
}

Backwards Compatibility

This EIP is compatible with any kind of NFTs that follow the EIP-721 standard. It only adds more functions and data structures without interfering with the original EIP-721 standard.

Test Cases

Test cases are implemented with the reference implementation.

Test Code

test.js

Run in terminal:

truffle test ./test/test.js

testCloneable.js

Run in terminal:

truffle test ./test/testCloneable.js

Reference Implementation

// SPDX-License-Identifier: CC0-1.0
pragma solidity ^0.8.0; 

import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "@openzeppelin/contracts/utils/introspection/IERC165.sol";
import "./IERC5496.sol";

contract ERC5496 is ERC721, IERC5496 {
    struct PrivilegeRecord {
        address user;
        uint256 expiresAt;
    }
    struct PrivilegeStorage {
        uint lastExpiresAt;
        // privId => PrivilegeRecord
        mapping(uint => PrivilegeRecord) privilegeEntry;
    }

    uint public privilegeTotal;
    // tokenId => PrivilegeStorage
    mapping(uint => PrivilegeStorage) public privilegeBook;
    mapping(address => mapping(address => bool)) private privilegeDelegator;

    constructor(string memory name_, string memory symbol_)
    ERC721(name_,symbol_)
    {
    
    }

    function setPrivilege(
        uint tokenId,
        uint privId,
        address user,
        uint64 expires
    ) external virtual {
        require((hasPrivilege(tokenId, privId, ownerOf(tokenId)) && _isApprovedOrOwner(msg.sender, tokenId)) || _isDelegatorOrHolder(msg.sender, tokenId, privId), "ERC721: transfer caller is not owner nor approved");
        require(expires < block.timestamp + 30 days, "expire time invalid");
        require(privId < privilegeTotal, "invalid privilege id");
        privilegeBook[tokenId].privilegeEntry[privId].user = user;
        if (_isApprovedOrOwner(msg.sender, tokenId)) {
            privilegeBook[tokenId].privilegeEntry[privId].expiresAt = expires;
            if (privilegeBook[tokenId].lastExpiresAt < expires) {
                privilegeBook[tokenId].lastExpiresAt = expires;
            }
        }
        emit PrivilegeAssigned(tokenId, privId, user, uint64(privilegeBook[tokenId].privilegeEntry[privId].expiresAt));
    }

    function hasPrivilege(
        uint256 tokenId,
        uint256 privId,
        address user
    ) public virtual view returns(bool) {
        if (privilegeBook[tokenId].privilegeEntry[privId].expiresAt >= block.timestamp){
            return privilegeBook[tokenId].privilegeEntry[privId].user == user;
        }
        return ownerOf(tokenId) == user;
    }

    function privilegeExpires(
        uint256 tokenId,
        uint256 privId
    ) public virtual view returns(uint256){
        return privilegeBook[tokenId].privilegeEntry[privId].expiresAt;
    }

    function _setPrivilegeTotal(
        uint total
    ) internal {
        emit PrivilegeTotalChanged(total, privilegeTotal);
        privilegeTotal = total;
    }

    function getPrivilegeInfo(uint tokenId, uint privId) external view returns(address user, uint256 expiresAt) {
        return (privilegeBook[tokenId].privilegeEntry[privId].user, privilegeBook[tokenId].privilegeEntry[privId].expiresAt);
    }

    function setDelegator(address delegator, bool enabled) external {
        privilegeDelegator[msg.sender][delegator] = enabled;
    }

    function _isDelegatorOrHolder(address delegator, uint256 tokenId, uint privId) internal virtual view returns (bool) {
        address holder = privilegeBook[tokenId].privilegeEntry[privId].user;
         return (delegator == holder || isApprovedForAll(holder, delegator) || privilegeDelegator[holder][delegator]);
    }

    function supportsInterface(bytes4 interfaceId) public override virtual view returns (bool) {
        return interfaceId == type(IERC5496).interfaceId || super.supportsInterface(interfaceId);
    }
}

Security Considerations

Implementations must thoroughly consider who has the permission to set or clone privileges.

Copyright

Contracts Dependencies Registry

Tue, 27 Dec 2022 00:00:00 +0000

EIP #6224 - Contracts Dependencies Registry is in Last Call status. It is authored by Artem Chystiakov (@arvolear) and was originally created 2022-12-27. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-6224-contracts-dependencies-registry/12316

Abstract

This EIP introduces an on-chain registry system that a decentralized protocol may use to manage its smart contracts.

The proposed system consists of two components: ContractsRegistry and Dependant. The ContractsRegistry contract stores references to every smart contract used within a protocol, optionally making them upgradeable by deploying self-managed proxies on top, and acts as a hub the Dependant contracts query to fetch their required dependencies from.

Motivation

In the ever-growing Ethereum ecosystem, projects tend to become more and more complex. Modern protocols require portability and agility to satisfy customer needs by continuously delivering new features and staying on pace with the industry. However, the requirement is hard to achieve due to the immutable nature of blockchains and smart contracts. Moreover, the increased complexity and continuous delivery bring bugs and entangle the dependencies between the contracts, making systems less supportable.

Applications that have a clear architectural facade; which are designed with forward compatibility in mind; which dependencies are transparent and clean are easier to develop and maintain. The given EIP tries to solve the aforementioned problems by presenting two smart contracts: the ContractsRegistry and the Dependant.

The advantages of using the provided system might be:

Structured smart contracts management via specialized contracts.
Ad-hoc upgradeability provision of a protocol.
Runtime addition, removal, and substitution of smart contracts.
Dependency injection mechanism to keep smart contracts’ dependencies under control.
Ability to specify custom access control rules to maintain the protocol.

Specification

Overview

The system consists of two smart contracts:

ContractsRegistry that is a singleton registry to manage and upgrade a protocol’s smart contracts.
Dependant that is a mix-in which enables a dependency injection mechanism.

The following diagram depicts the relationship between the registry and its dependants:

ContractsRegistry

The ContractsRegistry is the main contract of the proposed system. It MUST store the references to every standalone contract used within a protocol. The ContractRegistry MAY be configured to deploy a proxy contract of choice on top of the registered contracts.

Additionally, the ContractsRegistry MUST reject the registration of zero addresses.

The ContractsRegistry MUST implement the following interface:

pragma solidity ^0.8.0;

interface IContractsRegistry {
    /**
     * @notice The event that is emitted when the contract gets added to the registry
     * @param name the name of the contract
     * @param contractAddress the address of the added contract
     */
    event ContractAdded(string name, address contractAddress);
 
    /**
     * @notice The event that is emitted when the proxy contract gets added to the registry
     * @param name the name of the contract
     * @param contractAddress the address of the proxy contract
     * @param implementation the address of the implementation contract
     */
    event ProxyContractAdded(string name, address contractAddress, address implementation);
 
    /**
     * @notice The event that is emitted when the proxy contract gets upgraded through the registry
     * @param name the name of the contract
     * @param newImplementation the address of the new implementation contract
     */
    event ProxyContractUpgraded(string name, address newImplementation);
 
    /**
     * @notice The event that is emitted when the contract gets removed from the registry
     * @param name the name of the removed contract
     */
    event ContractRemoved(string name);
 
    /**
     * @notice The function that returns an associated contract by the name. 
     *
     * MUST revert if the requested contract is `address(0)`
     *
     * @param name the name of the contract
     * @return the address of the contract
     */
    function getContract(string memory name) external view returns (address);
 
    /**
     * @notice The function that checks if a contract with a given name has been added
     * @param name the name of the contract
     * @return true if the contract is present in the registry
     */
    function hasContract(string memory name) external view returns (bool);
 
    /**
     * @notice The function that injects dependencies into the given contract.
     *
     * MUST call the `setDependencies()` with `address(this)` and `bytes("")` as arguments on the provided contract
     *
     * @param name the name of the contract
     */
    function injectDependencies(string memory name) external;
 
    /**
     * @notice The function that injects dependencies into the given contract with extra data.
     *
     * MUST call the `setDependencies()` with `address(this)` and `data` as arguments on the provided contract
     *
     * @param name the name of the contract
     * @param data the extra context data that will be passed to the dependant contract
     */
    function injectDependenciesWithData(
        string memory name,
        bytes memory data
    ) external;
 
    /**
     * @notice The function that upgrades added proxy contract with a new implementation.
     *
     * It is the Owner's responsibility to ensure the compatibility between implementations.
     *
     * MUST emit `ProxyContractUpgraded` event
     *
     * @param name the name of the proxy contract
     * @param newImplementation the new implementation the proxy will be upgraded to
     */
    function upgradeContract(string memory name, address newImplementation) external;
 
    /**
     * @notice The function that upgrades added proxy contract with a new implementation, providing data
     *
     * It is the Owner's responsibility to ensure the compatibility between implementations.
     *
     * MUST emit `ProxyContractUpgraded` event
     *
     * @param name the name of the proxy contract
     * @param newImplementation the new implementation the proxy will be upgraded to
     * @param data the data that the proxy will be called with after upgrade. This can be an ABI encoded function call
     */
    function upgradeContractAndCall(
        string memory name,
        address newImplementation,
        bytes memory data
    ) external;
 
    /**
     * @notice The function that adds pure (non-proxy) contracts to the `ContractsRegistry`. The contracts MAY either be
     * the ones the system does not have direct upgradeability control over or those that are not upgradeable by design.
     *
     * MUST emit `ContractAdded` event. Reverts if the provided address is `address(0)`
     *
     * @param name the name to associate the contract with
     * @param contractAddress the address of the contract to be added
     */
    function addContract(string memory name, address contractAddress) external;
 
    /**
     * @notice The function that adds the proxy contracts to the registry by deploying them above the provided implementation.
     *
     * The function may be used to add a contract that the `ContractsRegistry` has to be able to upgrade.
     *
     * MUST emit `ProxyContractAdded` event. Reverts if implementation address is `address(0)`
     *
     * @param name the name to associate the contract with
     * @param contractAddress the address of the implementation to point the proxy to
     */
    function addProxyContract(string memory name, address contractAddress) external;
 
    /**
     * @notice The function that adds the proxy contracts to the registry by deploying them above the provided implementation,
     * providing data.
     *
     * The function may be used to add a contract that the `ContractsRegistry` has to be able to upgrade.
     *
     * MUST emit `ProxyContractAdded` event. Reverts if implementation address is `address(0)`
     *
     * @param name the name to associate the contract with
     * @param contractAddress the address of the implementation
     * @param data the data that the proxy will be called with. This can be an ABI encoded initialization call
     */
    function addProxyContractAndCall(
        string memory name,
        address contractAddress,
        bytes memory data
    ) external;
 
    /**
     * @notice The function that adds an already deployed proxy to the `ContractsRegistry`. It MAY be used
     * when the system migrates to the new `ContractRegistry`. In that case, the new registry MUST have the
     * credentials to upgrade the newly added proxies.
     *
     * MUST emit `ProxyContractAdded` event. Reverts if implementation address is `address(0)`
     *
     * @param name the name to associate the contract with
     * @param contractAddress the address of the proxy
     */
    function justAddProxyContract(string memory name, address contractAddress) external;
 
    /**
     * @notice The function to remove contracts from the ContractsRegistry.
     *
     * MUST emit `ContractRemoved` event. Reverts if the contract is already removed
     *
     * @param name the associated name with the contract
     */
    function removeContract(string memory name) external;
}

Dependant

The ContractsRegistry works together with the Dependant contract. Every standalone contract of a protocol MUST inherit Dependant in order to support the dependency injection mechanism.

The required dependencies MUST be set in the overridden setDependencies method, not in the constructor or initializer methods.

Only the injector MUST be able to call the setDependencies and setInjector methods. The initial injector will be a zero address, in that case, the call MUST NOT revert on access control checks.

The Dependant contract MUST implement the following interface:

pragma solidity ^0.8.0;

interface IDependant {
    /**
     * @notice The function that is called from the `ContractsRegistry` to inject dependencies.
     *
     * The contract MUST perform a proper access check of `msg.sender`. The calls should only be possible from `ContractsRegistry`
     *
     * @param contractsRegistry the registry to pull dependencies from
     * @param data the extra data that might provide additional application-specific context
     */
    function setDependencies(address contractsRegistry, bytes memory data) external;
 
    /**
     * @notice The function that sets the new dependency injector.
     *
     * The contract MUST perform a proper access check of `msg.sender`
     *
     * @param injector the new dependency injector
     */
    function setInjector(address injector) external;
 
    /**
     * @notice The function that gets the current dependency injector
     * @return the current dependency injector
     */
    function getInjector() external view returns (address);
}

The Dependant contract MAY store the dependency injector (usually ContractsRegistry) address in the special slot 0x3d1f25f1ac447e55e7fec744471c4dab1c6a2b6ffb897825f9ea3d2e8c9be583 (obtained as bytes32(uint256(keccak256("eip6224.dependant.slot")) - 1)).

Rationale

There are a few design decisions that have to be explicitly specified:

ContractsRegistry Rationale

Contracts Identifier

The string contracts identifier is chosen over the uint256 and bytes32 to maintain code readability and reduce the human error chances when interacting with the ContractsRegistry. Being the topmost smart contract of a protocol, it MAY be typical for the users to interact with it via block explorers or DAOs. Clarity was prioritized over gas usage.

Due to the string identifier, the event parameters are not indexed. The string indexed parameter will become the keccak256 hash of the contract name if it is larger than 32 bytes. This fact reduces readability, which was prioritized.

Reverts

The getContract view function reverts if the requested contract is address(0). This is essential to minimize the risks of misinitialization of a protocol. Correct contracts SHOULD be added to the registry prior to any dependency injection actions.

The addContract, addProxyContract, addProxyContractAndCall, and justAddProxyContract methods revert if the provided address is address(0) for the same risk minimization reason.

Dependant Rationale

Dependencies

The data parameter is provided to carry additional application-specific context. It MAY be used to extend the method’s behavior.

Injector

The setInjector function is made external to support the dependency injection mechanism for factory-made contracts. However, the method SHOULD be used with extra care.

Reference Implementation

Note that the reference implementation depends on OpenZeppelin contracts 4.9.2.

ContractsRegistry Implementation

pragma solidity ^0.8.0;

import {Address} from "@openzeppelin/contracts/utils/Address.sol";
import {TransparentUpgradeableProxy} from "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol";
import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";

import {Dependant} from "./Dependant.sol";

interface IContractsRegistry {
    event ContractAdded(string name, address contractAddress);
    event ProxyContractAdded(
        string name,
        address contractAddress,
        address implementation
    );
    event ProxyContractUpgraded(string name, address newImplementation);
    event ContractRemoved(string name);

    function getContract(string memory name) external view returns (address);

    function hasContract(string memory name) external view returns (bool);

    function injectDependencies(string memory name) external;

    function injectDependenciesWithData(string memory name, bytes memory data)
        external;

    function upgradeContract(string memory name, address newImplementation)
        external;

    function upgradeContractAndCall(
        string memory name,
        address newImplementation,
        bytes memory data
    ) external;

    function addContract(string memory name, address contractAddress) external;

    function addProxyContract(string memory name, address contractAddress)
        external;

    function addProxyContractAndCall(
        string memory name,
        address contractAddress,
        bytes memory data
    ) external;

    function justAddProxyContract(string memory name, address contractAddress)
        external;

    function removeContract(string memory name) external;
}

contract ProxyUpgrader {
    using Address for address;

    address private immutable _OWNER;

    modifier onlyOwner() {
        _onlyOwner();
        _;
    }

    constructor() {
        _OWNER = msg.sender;
    }

    function upgrade(address what_, address to_, bytes calldata data_) external onlyOwner {
        if (data_.length > 0) {
            TransparentUpgradeableProxy(payable(what_)).upgradeToAndCall(to_, data_);
        } else {
            TransparentUpgradeableProxy(payable(what_)).upgradeTo(to_);
        }
    }

    function getImplementation(address what_) external view onlyOwner returns (address) {
        // bytes4(keccak256("implementation()")) == 0x5c60da1b
        (bool success_, bytes memory returndata_) = address(what_).staticcall(hex"5c60da1b");

        require(success_, "ProxyUpgrader: not a proxy");

        return abi.decode(returndata_, (address));
    }

    function _onlyOwner() internal view {
        require(_OWNER == msg.sender, "ProxyUpgrader: not an owner");
    }
}

contract ContractsRegistry is IContractsRegistry, OwnableUpgradeable {
    ProxyUpgrader private _proxyUpgrader;

    mapping(string => address) private _contracts;
    mapping(address => bool) private _isProxy;

    function __ContractsRegistry_init() public initializer {
        _proxyUpgrader = new ProxyUpgrader();

        __Ownable_init();
    }

    function getContract(string memory name_) public view returns (address) {
        address contractAddress_ = _contracts[name_];

        require(
            contractAddress_ != address(0),
            "ContractsRegistry: this mapping doesn't exist"
        );

        return contractAddress_;
    }

    function hasContract(string memory name_) public view returns (bool) {
        return _contracts[name_] != address(0);
    }

    function getProxyUpgrader() external view returns (address) {
        return address(_proxyUpgrader);
    }

    function injectDependencies(string memory name_) public virtual onlyOwner {
        injectDependenciesWithData(name_, bytes(""));
    }

    function injectDependenciesWithData(string memory name_, bytes memory data_)
        public
        virtual
        onlyOwner
    {
        address contractAddress_ = _contracts[name_];

        require(
            contractAddress_ != address(0),
            "ContractsRegistry: this mapping doesn't exist"
        );

        Dependant dependant_ = Dependant(contractAddress_);
        dependant_.setDependencies(address(this), data_);
    }

    function upgradeContract(string memory name_, address newImplementation_)
        public
        virtual
        onlyOwner
    {
        upgradeContractAndCall(name_, newImplementation_, bytes(""));
    }

    function upgradeContractAndCall(
        string memory name_,
        address newImplementation_,
        bytes memory data_
    ) public virtual onlyOwner {
        address contractToUpgrade_ = _contracts[name_];

        require(
            contractToUpgrade_ != address(0),
            "ContractsRegistry: this mapping doesn't exist"
        );
        require(
            _isProxy[contractToUpgrade_],
            "ContractsRegistry: not a proxy contract"
        );

        _proxyUpgrader.upgrade(contractToUpgrade_, newImplementation_, data_);

        emit ProxyContractUpgraded(name_, newImplementation_);
    }

    function addContract(string memory name_, address contractAddress_)
        public
        virtual
        onlyOwner
    {
        require(
            contractAddress_ != address(0),
            "ContractsRegistry: zero address is forbidden"
        );

        _contracts[name_] = contractAddress_;

        emit ContractAdded(name_, contractAddress_);
    }

    function addProxyContract(string memory name_, address contractAddress_)
        public
        virtual
        onlyOwner
    {
        addProxyContractAndCall(name_, contractAddress_, bytes(""));
    }

    function addProxyContractAndCall(
        string memory name_,
        address contractAddress_,
        bytes memory data_
    ) public virtual onlyOwner {
        require(
            contractAddress_ != address(0),
            "ContractsRegistry: zero address is forbidden"
        );

        address proxyAddr_ = _deployProxy(
            contractAddress_,
            address(_proxyUpgrader),
            data_
        );

        _contracts[name_] = proxyAddr_;
        _isProxy[proxyAddr_] = true;

        emit ProxyContractAdded(name_, proxyAddr_, contractAddress_);
    }

    function justAddProxyContract(string memory name_, address contractAddress_)
        public
        virtual
        onlyOwner
    {
        require(
            contractAddress_ != address(0),
            "ContractsRegistry: zero address is forbidden"
        );

        _contracts[name_] = contractAddress_;
        _isProxy[contractAddress_] = true;

        emit ProxyContractAdded(
            name_,
            contractAddress_,
            _proxyUpgrader.getImplementation(contractAddress_)
        );
    }

    function removeContract(string memory name_) public virtual onlyOwner {
        address contractAddress_ = _contracts[name_];

        require(
            contractAddress_ != address(0),
            "ContractsRegistry: this mapping doesn't exist"
        );

        delete _isProxy[contractAddress_];
        delete _contracts[name_];

        emit ContractRemoved(name_);
    }

    function _deployProxy(
        address contractAddress_,
        address admin_,
        bytes memory data_
    ) internal virtual returns (address) {
        return
            address(
                new TransparentUpgradeableProxy(contractAddress_, admin_, data_)
            );
    }
}

Dependant Implementation

pragma solidity ^0.8.0;

interface IDependant {
    function setDependencies(address contractsRegistry, bytes memory data) external;
 
    function setInjector(address injector) external;
 
    function getInjector() external view returns (address);
}

abstract contract Dependant is IDependant {
    /**
     * @dev bytes32(uint256(keccak256("eip6224.dependant.slot")) - 1)
     */
    bytes32 private constant _INJECTOR_SLOT =
        0x3d1f25f1ac447e55e7fec744471c4dab1c6a2b6ffb897825f9ea3d2e8c9be583;

    modifier dependant() {
        _checkInjector();
        _;
        _setInjector(msg.sender);
    }

    function setDependencies(address contractsRegistry_, bytes memory data_) public virtual;

    function setInjector(address injector_) external {
        _checkInjector();
        _setInjector(injector_);
    }

    function getInjector() public view returns (address injector_) {
        bytes32 slot_ = _INJECTOR_SLOT;

        assembly {
            injector_ := sload(slot_)
        }
    }

    function _setInjector(address injector_) internal {
        bytes32 slot_ = _INJECTOR_SLOT;

        assembly {
            sstore(slot_, injector_)
        }
    }

    function _checkInjector() internal view {
        address injector_ = getInjector();

        require(injector_ == address(0) || injector_ == msg.sender, "Dependant: not an injector");
    }
}

Security Considerations

It is crucial for the owner of ContractsRegistry to keep their keys in a safe place. The loss/leakage of credentials to the ContractsRegistry will lead to the application’s point of no return. The ContractRegistry is a cornerstone of a protocol, access must be granted to the trusted parties only.

ContractsRegistry Security

The ContractsRegistry does not perform any upgradeability checks between the proxy upgrades. It is the user’s responsibility to make sure that the new implementation is compatible with the old one.

Dependant Security

The Dependant contract MUST set its dependency injector no later than the first call to the setDependencies function is made. That being said, it is possible to front-run the first dependency injection.

Copyright

Single-contract Multi-delegatecall

Wed, 18 Jan 2023 00:00:00 +0000

EIP #6357 - Single-contract Multi-delegatecall is in Last Call status. It is authored by Gavin John (@Pandapip1) and was originally created 2023-01-18. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-6357-single-contract-multicall/12621

Abstract

This EIP standardizes an interface containing a single function, multicall, allowing EOAs to call multiple functions of a smart contract in a single transaction, and revert all calls if any call fails.

Motivation

Currently, in order to transfer several ERC-721 NFTs, one needs to submit a number of transactions equal to the number of NFTs being tranferred. This wastes users’ funds by requiring them to pay 21000 gas fee for every NFT they transfer.

Specification

Contracts implementing this EIP must implement the following interface:

pragma solidity ^0.8.0;

interface IMulticall {
    /// @notice           Takes an array of abi-encoded call data, delegatecalls itself with each calldata, and returns the abi-encoded result
    /// @dev              Reverts if any delegatecall reverts
    /// @param    data    The abi-encoded data
    /// @returns  results The abi-encoded return values
    function multicall(bytes[] calldata data) external virtual returns (bytes[] memory results);

    /// @notice           OPTIONAL. Takes an array of abi-encoded call data, delegatecalls itself with each calldata, and returns the abi-encoded result
    /// @dev              Reverts if any delegatecall reverts
    /// @param    data    The abi-encoded data
    /// @param    values  The effective msg.values. These must add up to at most msg.value
    /// @returns  results The abi-encoded return values
    function multicallPayable(bytes[] calldata data, uint256[] values) external payable virtual returns (bytes[] memory results);
}

Rationale

multicallPayable is optional because it isn’t always feasible to implement, due to the msg.value splitting.

Backwards Compatibility

This is compatible with most existing multicall functions.

Test Cases

The following JavaScript code, using the Ethers library, should atomically transfer amt units of an ERC-20 token to both addressA and addressB.

await token.multicall(await Promise.all([
    token.interface.encodeFunctionData('transfer', [ addressA, amt ]),
    token.interface.encodeFunctionData('transfer', [ addressB, amt ]),
]));

Reference Implementation

pragma solidity ^0.8.0;

/// Derived from OpenZeppelin's implementation
abstract contract Multicall is IMulticall {
    function multicall(bytes[] calldata data) external virtual returns (bytes[] memory results) {
        results = new bytes[](data.length);
        for (uint256 i = 0; i < data.length; i++) {
            (bool success, bytes memory returndata) = address(this).delegatecall(data[i]);
            require(success);
            results[i] = returndata;
        }
        return results;
    }
}

Security Considerations

multicallPayable should only be used if the contract is able to support it. A naive attempt at implementing it could allow an attacker to call a payable function multiple times with the same ether.

Copyright

Empty accounts deprecation

Tue, 19 Sep 2023 00:00:00 +0000

EIP #7523 - Empty accounts deprecation is in Last Call status. It is authored by Peter Davies (@petertdavies) and was originally created 2023-09-19. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-7523-empty-accounts-deprecation/15870

Abstract

This EIP prohibits the state of any post-merge network from containing empty accounts. Since no empty accounts exist outside the testsuite and no new ones can be created this requirement is already achieved in practice. An explicit ban reduces technical debt going forward.

Motivation

The possibility of empty accounts is a historical artifact of the early history of Ethereum. The only networks that have ever been capable of containing them are Ethereum Mainnet, the deprecated testnet Ropsten, Etheruem Classic Mainnet and various Ethereum Classic testnets. All remaining empty accounts on Mainnet were cleared in block 14049881 (transaction 0xf955834bfa097458a9cf6b719705a443d32e7f43f20b9b0294098c205b4bcc3d) and a similar transaction was sent on Ethereum Classic. None of the other myriad EVM-compatible networks are old enough to have empty accounts and there is no realistic prospect that anyone will encounter an empty account in a production context.

Despite empty accounts no longer existing, they still impose a legacy of technical debt. EIP-161 imposes complicated rules that require a client to delete an empty account when it is “touched”. As the Ethereum specification continues to evolve new edgecases of the “touch” rules arise which must be debated, implemented, tested and documented. If a future client wishes to only support post-merge blocks it must implement unnecessary empty account support solely to pass the test suite.

By prohibiting empty accounts on post-merge networks, this EIP frees designers and implementers of Ethereum and related blockchains from the burden of having to consider them going forward.

Specification

An empty account is an account with has no code and zero nonce and zero balance. This is the same as the definition in EIP-161.

On networks that undergo the merge transition, the pre state of the merge block may not contain any empty accounts. For networks that are merged at genesis, none of the genesis accounts may be empty accounts.

Rather than performing a scan of the state, clients MAY assume the following chains have no post-merge empty accounts:

The Mainnet chain whose merge block has hash 0x56a9bb0302da44b8c0b3df540781424684c3af04d0b7a38d72842b762076a664.
Any chain which satisfies all of the following:
- has no empty accounts in the genesis.
- had a post Spurious Dragon fork at genesis.

The Ethereum specification is declared to be undefined in the presence of an empty account in a post-merge context. Any testcase involving post-merge empty accounts is invalid.

Rationale

This EIP was drafted to be the simplest possible way of eliminating the long term technical debt imposed by empty accounts. The Merge was chosen as a natural easily identifiable cutoff point.

Alternative approaches include:

Using an earlier cutoff point, such as block 14049881.
Identifying a wider range of edge case behaviour that never happened.

These approaches were rejected as being unnecessarily complicated.

Backwards Compatibility

As EIP does not change any behaviour that can occur outside the testsuite, it has no backwards compatibility consequences.

Security Considerations

The validity of this EIP is dependent on the assertion that all empty accounts on Ethereum Mainnet were cleared prior to the merge. This should be subject to appropriate verification.

Any networks artificially created with empty accounts will cause problems with tooling and clients.

Copyright

Revert creation in case of non-empty storage

Fri, 02 Feb 2024 00:00:00 +0000

EIP #7610 - Revert creation in case of non-empty storage is in Last Call status. It is authored by Gary Rong (@rjl493456442), Martin Holst Swende (@holiman) and was originally created 2024-02-02. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-revert-creation-in-case-of-non-empty-storage/18452

Abstract

This EIP causes contract creation to throw an error when attempted at an address with pre-existing storage.

Specification

If a contract creation is attempted due to a creation transaction, the CREATE opcode, the CREATE2 opcode, or any other reason, and the destination address already has either a nonzero nonce, a nonzero code length, or non-empty storage, then the creation MUST throw as if the first byte in the init code were an invalid opcode. This change MUST apply retroactively for all existing blocks.

This EIP amends EIP-684 with one extra condition, requiring empty storage for contract deployment.

This EIP will not affect EIP-7702, since the authority’s nonce is always incremented after an authorization is applied, which conflicts with the condition required for contract deployment.

Rationale

EIP-684 defines two conditions for contract deployment: the destination address must have zero nonce and zero code length. Unfortunately, this is not sufficient. Before EIP-161 was applied, the nonce of a newly deployed contract remained set to zero. Therefore, it was entirely possible to create a contract with a zero nonce and zero code length but with non-empty storage, if slots were set in the constructor. There exists 28 such contracts on Ethereum mainnet at this time.

Backwards Compatibility

This is an execution layer upgrade, and so it requires a hard fork.

Test Cases

There exists quite a number of tests in the ethereum tests repo as well as in the execution spec tests, which test the scenario of deployment to targets with non-empty storage. These tests have been considered problematic in the past; Reth and EELS both intentionally implement a version of the account reset solely to pass the tests. Py-evm declared the situation impossible and never implemented account reset.

Refilling the existing tests will provide sufficient coverage for this EIP.

Security Considerations

This EIP is a security upgrade: it enforces the immutability of deployed code.

Copyright

ETH transfers emit a log

Fri, 17 May 2024 00:00:00 +0000

EIP #7708 - ETH transfers emit a log is in Last Call status. It is authored by Vitalik Buterin (@vbuterin), Peter Davies (@petertdavies), Etan Kissling (@etan-status), Gajinder Singh (@g11tech), Carson (@carsons-eels), Jared Wasinger (@jwasinger) and was originally created 2024-05-17. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-7708-eth-transfers-emit-a-log/20034

Abstract

All ETH transfers emit a log.

Motivation

Logs are often used to track when balance changes of assets on Ethereum. Logs work for ERC-20 tokens, but they do not work for ETH. ETH transfers from EOAs can be read from the transaction list in the block, but ETH transfers from smart contract wallets are not automatically logged anywhere. This has already led to problems in the past, eg. early exchanges would often not properly support deposits from smart contract wallets, or only support them with a much longer delay. This EIP proposes that we automatically generate a log every time a value-transferring CALL or SELFDESTRUCT happens. We also add a similar log for transfers in transactions, so that all ETH transfers can be tracked using one mechanism.

Specification

ETH transfer logs

A log, identical to a LOG3, is issued for:

Any nonzero-value-transferring transaction to a different account, before any other logs created by EVM execution
Any nonzero-value-transferring CALL to a different account, at the time that the value transfer executes
Any nonzero-value-transferring SELFDESTRUCT to a different account, at the time that the value transfer executes
Any nonzero-value-transferring CREATE or CREATE2 to the created account, at the time that the value transfer executes

Field	Value
`address` emitting log	`0xfffffffffffffffffffffffffffffffffffffffe` (`SYSTEM_ADDRESS`)
`topics[0]`	`0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef` (`keccak256('Transfer(address,address,uint256)')`)
`topics[1]`	`from` address (zero prefixed to fill uint256)
`topics[2]`	`to` address (zero prefixed to fill uint256)
`data`	`amount` in Wei (big endian uint256)

This matches the ERC-20 Transfer event definition.

Rationale

This is the simplest possible implementation that ensures that all ETH transfers are implemented in some kind of record that can be easily accessed through making RPC calls into a node, or through asking for a Merkle branch that is hashed into the block root. The log type is compatible with the ERC-20 token standard, but does not introduce any overly-specific ERC-20 features (eg. ABI encodings) into the specification.

The SYSTEM_ADDRESS is reused as the log emitter for consistency with other protocol-originated operations (e.g. EIP-4788) and to distinguish these protocol-generated logs from logs emitted by user contracts.

Fee payment logs for priority fees paid to the coinbase were considered. However, they are a distinct category from transfers, and adding these logs to this EIP would explode the log volume in a way that raises the intrinsic cost of transfer logs (and therefore transactions), putting an unreasonable load on the network. Clients can already compute these fee amounts from the block header and transaction receipt, so it is unnecessary to log them. The base fee burn is excluded for the same reason: the burned amount is already derivable from the block header.

Withdrawals were also considered, but they are not attached to a transaction, which means there is no natural emission point. Additionally, they are already easily derivable from block information. Adding these kinds of logs would duplicate data already available to clients.

Clients who wish to provide a unified view for consumers MAY expose a new aggregating RPC.

Backwards Compatibility

ETH burns via `SELFDESTRUCT`

After EIP-8246, ETH can no longer be burned via SELFDESTRUCT to self or by sending ETH to an account marked for selfdestruction. Therefore, this EIP does not specify this edge-case.

Test Cases

Transfer log emission for plain transactions, EOAs, delegated EOAs, and across all transaction types
Transfer logs across the CALL family and how the executing context attributes the sender
Transfer logs for CREATE / CREATE2 endowments, initcode behavior, and failure modes
Transfer logs for SELFDESTRUCT to self vs. a different beneficiary, including pre-existing and cross-tx contracts
Log ordering: Transfer logs appear before any EVM-emitted logs in a transaction, and nested-CALL Transfer logs appear in chronological call order
Negative cases where no log is emitted (zero-value, reverts, rolled-back inner calls, fee payments)
Transfers to special-purpose addresses (precompiles, the system address, the coinbase)
Fork transition behavior at the EIP-7708 activation boundary

Test cases for this EIP can be found in the Execution Layer Specification suite eip7708_eth_transfer_logs.

Security Considerations

ETH transfers already cost a minimum of 6700 gas, which is much more expensive than the LOG3 opcode (1500 gas). Hence, this EIP does not increase the worst-case number of logs that can be put into a block. It will somewhat increase the average number of logs.

Copyright

Network Upgrade Inclusion Stages

Wed, 12 Jun 2024 00:00:00 +0000

EIP #7723 - Network Upgrade Inclusion Stages is in Last Call status. It is authored by Tim Beiko (@timbeiko), Alex Stokes (@ralexstokes), Ansgar Dietrichs (@adietrichs), Nixo (@nixorokish), Parithosh Jayanthi (@parithosh) and was originally created 2024-06-12. It is in the category of type Meta. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-7723-network-upgrade-inclusion-stages/20281

Abstract

Defines the stages that EIPs go through in the process of planning network upgrades: Proposed for Inclusion, Considered for Inclusion, Scheduled for Inclusion, Declined for Inclusion and Included.

Motivation

This EIP proposes definitions for the various stages EIPs go through when planning network upgrades. It also provides context and guidelines around when and how EIPs should be moved from one stage to the next.

Specification

All EIP stages apply to a single network upgrade. EIPs must be Proposed, Considered, Declined or Scheduled separately for each network upgrade. While an EIP cannot be Included in two network upgrades, an EIP being Declined for Inclusion in a previous upgrade does not prevent it from being Proposed, Considered, Declined or Scheduled for inclusion in any future upgrade.

The stages below are generally defined for Standards Track - Core EIPs, which must be activated synchronously by all nodes on a network. To help with prioritization and communications, non-Core EIPs may also be assigned these stages. The differences in the process and implications for non-Core EIPs are noted in each stage’s definition.

Upgrade Meta EIPs

Anyone MAY draft a Meta EIP to list EIPs for a network upgrade. This Meta EIP SHOULD include four categories in its specification section: Proposed for Inclusion, Declined for Inclusion, Considered for Inclusion and Scheduled for Inclusion. Even if a category is TBD, it SHOULD be included in the initial draft for clarity.

When the Upgrade Meta EIP is moved to Review, the Proposed for Inclusion and the Declined for Inclusion list SHOULD be removed. When it is moved to Last Call, Considered for Inclusion lists SHOULD be removed, leaving only the Scheduled for Inclusion list.

Before the Upgrade Meta EIP is moved to Final, the Scheduled for Inclusion stage MUST be renamed to Included and contain only EIPs that were activated with the upgrade.

Upgrade Devnets

When preparing a network upgrade, client developers typically implement EIPs first on an ephemeral test network (upgrade devnet) to verify client interoperability before deploying to long-lived test networks. These upgrade devnets follow a naming convention of upgradeName-devnet-version (e.g. pectra-devnet-0 for the first upgrade devnet of the Pectra network upgrade, dencun-devnet-1 for the second upgrade devnet of the Dencun update, etc).

Since client developers’ ability to include EIPs in a network upgrade is constrained by what can be implemented and tested in these upgrade devnets, the Considered for Inclusion and Scheduled for Inclusion sections below propose aligning these statuses with EIPs’ implementation status in upgrade devnets.

Proposed for Inclusion

To propose an EIP for inclusion, someone MUST open a pull request to add it to the Proposed for Inclusion (PFI) section of the Upgrade Meta EIP. The proposer of an EIP SHOULD serve as the primary point of contact for that EIP for the duration of the upgrade cycle or SHOULD designate another person to serve in that role. Reasonable pull requests SHOULD be merged in a timely fashion by the Upgrade Meta EIP author.

At this stage, implementation teams SHOULD review the EIP. For Core EIPs, this should be in the context of including it in the said upgrade. For non-Core EIPs, this should be in the context of supporting Core EIPs before the network upgrade is activated.

Note that EIPs must be Proposed for Inclusion for each network upgrade. In other words, proposals do not “carry over” to the next upgrade if an EIP is not included in the one it was first proposed for.

Considered for Inclusion

Once client developers have reviewed an EIP which was Proposed for Inclusion, they MAY move it to the Considered for Inclusion (CFI) stage. Once a decision is made by client teams to move an EIP to Considered for Inclusion, the Upgrade Meta EIP SHOULD be updated to reflect this.

Considered for Inclusion signals that client developers intend to attempt to include the EIP in devnets. The All Core Devs Execution (ACDE) and Consensus (ACDC) call facilitators should work with the testing teams to propose a priority ordering of CFI EIPs to be reviewed by client developers, and then reflect this prioritization in the Meta EIP. This prioritization should inform which EIPs should be included in upcoming devnets, with some flexibility if circumstances change.

Assuming it meets all the requirements for mainnet deployment it MAY be included in the network upgrade. This stage is similar to “concept ACK” in other open source projects, and is not sufficient to result in deployment to mainnet.

Non-Core EIPs that are Considered for Inclusion SHOULD be supported prior to the network upgrade being activated.

An EIP MAY be moved from Considered for Inclusion to Declined for Inclusion if client teams are against including the EIP in the network upgrade.

An EIP SHOULD have a Python implementation accompanied by tests in execution-specs submitted as an open PR. The EIP writer is encouraged to reach out to the maintainers of execution-specs for assistance with implementation. Client developers MAY decide to allow an EIP to be moved to Considered for Inclusion without either implementation, being aware that the absence of these implementations could lead to delays in the testing cycle.

Any updates to an EIP that is already at this stage SHOULD be accompanied by the appropriate updates to its implementation and tests in execution-specs if deemed necessary by client developers.

Declined for Inclusion

At any time during the network upgrade planning process, client developers MAY move EIPs from any other stage to the Declined for Inclusion (DFI) stage if client teams are against including the EIP in the network upgrade. Once a decision is made by client teams to move an EIP to Declined for Inclusion, the Upgrade Meta EIP SHOULD be updated to reflect this.

Declined for Inclusion signals that client developers wish to exclude the EIP from the current network upgrade and stop discussing its potential inclusion or implementation status in relation to this upgrade. An EIP which was Declined for Inclusion in a particular upgrade MAY still be Proposed for Inclusion in a subsequent upgrade. In exceptional circumstances, client developers MAY choose to move an EIP from Declined for Inclusion to Considered for Inclusion or Scheduled for Inclusion.

Scheduled for Inclusion

An EIP can be moved to Scheduled for Inclusion (SFI) when core developers:

Agree upon a strong intent to include the EIP in the next network upgrade.
Agree that an EIP’s specifications and implementations have reached a certain level of maturity.

I.e., an SFI status signals that the EIP is on track for inclusion barring unforeseen issues.

The following critieria can be applied to ascertain whether an EIP is mature (stable) enough to move to SFI:

It has been included in a devnet that has demonstrated stability (e.g., high participation, no critical bugs for ≥1 week).
The EIP specification is close to final (no placeholder values or pending design decisions).
It has minimal interactions with other CFI EIPs, OR those interactions have been tested in the same devnet.
Testing coverage is adequate (clients pass consensus tests, no known divergence across clients).

All Core Devs Testing (ACDT) calls may review EIPs to determine SFI eligibility. Status changes will then be ratified on ACDE or ACDC before assigning SFI status.

Scheduled for Inclusion signals that the EIP is on track for inclusion barring unforeseen issues. EIPs with incomplete specs or untested interactions should remain CFI until these conditions are met. The latest Upgrade Devnet must contain all Scheduled for Inclusion Core EIPs.

An EIP MAY be moved from Scheduled for Inclusion to Declined for Inclusion if circumstances necessitate removal, as agreed by client teams. An EIP MAY also be moved from Scheduled for Inclusion to Considered for Inclusion if client teams remain in favor of including the EIP in the network upgrade but cannot commit to including it in the next Upgrade Devnet.

An EIP MUST have a Python implementation accompanied by tests in execution-specs, submitted as an open PR or merged to the devnets/upgradeName/version branch of the repository. Client developers MAY decide to allow an EIP to be moved to Scheduled for Inclusion without an execution-specs implementation, but the tests are strictly mandatory.

Any updates to an EIP that is already at this stage MUST be accompanied by appropriate updates to its implementation and tests in execution-specs if deemed necessary by client developers.

Included

After network upgrade activation, all included Core EIPs and activated non-Core EIPs MUST be moved to Included in the Meta EIP. All other status lists MUST be removed from the Meta EIP.

Included signals that the EIPs have been activated as part of the network upgrade.

Rationale

Formalizing the Proposed for Inclusion, Considered for Inclusion, Scheduled for Inclusion, Declined for Inclusion and Included stages provides better legibility to both protocol maintainers and the broader Ethereum community.

The specification tries to minimize steps that MUST be followed to align with Ethereum’s “rough consensus” governance model.

Assuming it is adopted, the process outlined in this EIP should be used for at least one full network upgrade cycle before moving to Last Call and at least two full network upgrade cycles before moving to Final. This way, the EIP can be updated to reflect changes made to the process over time.

Backwards Compatibility

This EIP does not directly change the Ethereum protocol. It formalizes parts of the current network upgrade planning process.

Security Considerations

None.

Copyright

Enshrined Proposer-Builder Separation

Fri, 28 Jun 2024 00:00:00 +0000

EIP #7732 - Enshrined Proposer-Builder Separation is in Last Call status. It is authored by Francesco D'Amato , Nico Flaig , Barnabé Monnot , Michael Neuder , Potuz (@potuz), Justin Traglia , Terence Tsao and was originally created 2024-06-28. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-7732-enshrined-proposer-builder-separation-epbs/19634

Abstract

This EIP fundamentally changes the way an Ethereum block is validated by decoupling the execution validation from the consensus validation both logically as well as temporally. It does so by introducing a new in-protocol entity called builders and adding a new duty (submitting payload timeliness attestations) to Ethereum validators. The ExecutionPayload field of the BeaconBlockBody is removed and instead it is replaced by a signed commitment (a SignedExecutionPayloadBid object) from a builder to later reveal the corresponding execution payload. This commitment specifies in particular the blockhash of the execution block and a value to be paid to the beacon block proposer. When processing the BeaconBlock, the committed value is deducted from the builder’s beacon chain balance and later a withdrawal is placed to an address, of the proposer’s choosing, in the execution layer. A subset of validators in the beacon committee is assigned to the Payload Timeliness Committee (PTC), these validators are tasked to attest (by broadcasting a PayloadAttestationMessage) to whether the corresponding builder has revealed the committed execution payload (with the right blockhash) in a timely fashion and whether the correspoding blob data was available according to their view. PTC members are not required to validate the execution payload, execution validation is thus deferred until the next beacon block validation. While builder’s are staked entities, their stake is not actively validating the beacon chain, they are not subject to the usual deposit and exit churn/queues and can be staked for as little as 1ETH. While the in-protocol payment via withdrawals is trustlessly deducted from this stake, the protocol also accomodates for trusted payments in the form of promises to be fulfiled elsewhere.

Motivation

This EIP solves a different set of unrelated important problems.

An overwhelming majority of beacon block proposers outsource the construction of the execution payload within their blocks to a third party (henceforth called a builder). In order to do so, they request the hash tree root (HTR) of a promised execution payload and submit a SignedBlindedBeaconBlock to a trusted party that is tasked with replacing the HTR with the full execution payload (received from the builder) before broadcasting. This EIP allows for a trust-free fair exchange between the beacon block proposer and the builder, guaranteeing that an honest beacon block proposer will receive payment from the builder regardless of the latter’s actions and that the honest builder’s payload will be the canonical head of the chain regardless of the proposer’s action.
Currently, validators have the time between receiving the full beacon block (including an execution payload) and the attesting deadline (4 seconds in Ethereum mainnet) to perform both consensus and execution state transition functions, check blob data availability and evaluate the new head of the blockchain. The remainder of the slot time is spent doing less CPU-intense and critical task. By separating the validation of the execution and consensus part of the block, validators are only tasked to perform the consensus state transition function in this critical time before attesting, while execution and data availability validation is deferred for most of the remainder of the slot (between the builder’s reveal time and the next attestation deadline).
By removing the full execution payload size from the consensus block, it allows for faster network propagation on the critical path.
It removes the increased reorg likeliness of including blob transactions in blocks given the natural increase in timelines for data availability checks and the fact that the builder may broadcast the blob sidecars even before attestations for the beacon block have been released.
It prevents validators from missing attestations and strengthens the weight properties of fork choice in the event that builders produce invalid payloads.
It removes the need to use trusted middleware in order to delegate block construction to a builder.

Specification

Execution Layer

No changes are required.

Consensus Layer

The full consensus changes can be found in the consensus-specs Github repository. They are split between:

Beacon Chain changes.
Fork choice changes.
P2P changes.
Honest validator guide changes.
A new honest builder guide.
Fork logic changes.

A summary of the main changes is included below, the Rationale section contains an explanation for most of the design decisions around these changes.

Beacon chain changes

Types

Name	SSZ equivalent	Description
`BuilderIndex`	`uint64`	Builder registry index

Constants

Index flags

Name	Value	Description
`BUILDER_INDEX_FLAG`	`uint64(2**40)`	Bitwise flag which indicates that a `ValidatorIndex` should be treated as a `BuilderIndex`

Domains

Name	Value
`DOMAIN_BEACON_BUILDER`	`DomainType('0x0B000000')`
`DOMAIN_PTC_ATTESTER`	`DomainType('0x0C000000')`
`DOMAIN_PROPOSER_PREFERENCES`	`DomainType('0x0D000000')`

Misc

Name	Value	Description
`BUILDER_INDEX_SELF_BUILD`	`BuilderIndex(UINT64_MAX)`	Value which indicates the proposer built the payload
`BUILDER_PAYMENT_THRESHOLD_NUMERATOR`	`uint64(6)`
`BUILDER_PAYMENT_THRESHOLD_DENOMINATOR`	`uint64(10)`

Withdrawal prefixes

Name	Value	Description
`BUILDER_WITHDRAWAL_PREFIX`	`Bytes1('0x03')`	Withdrawal credential prefix for a builder

Preset

Misc

Name	Value
`PTC_SIZE`	`uint64(2**9)` (= 512)

Max operations per block

Name	Value
`MAX_PAYLOAD_ATTESTATIONS`	`4`

State list lengths

Name	Value	Unit
`BUILDER_REGISTRY_LIMIT`	`uint64(2**40)` (= 1,099,511,627,776)	Builders
`BUILDER_PENDING_WITHDRAWALS_LIMIT`	`uint64(2**20)` (= 1,048,576)	Builder pending withdrawals

Withdrawals processing

Name	Value
`MAX_BUILDERS_PER_WITHDRAWALS_SWEEP`	`2**14` (= 16,384)

Configuration

Time parameters

Name	Value	Unit
`MIN_BUILDER_WITHDRAWABILITY_DELAY`	`uint64(2**6)` (= 64)	epochs

Containers

New containers

`Builder`

class Builder(Container):
    pubkey: BLSPubkey
    version: uint8
    execution_address: ExecutionAddress
    balance: Gwei
    deposit_epoch: Epoch
    withdrawable_epoch: Epoch

`BuilderPendingPayment`

class BuilderPendingPayment(Container):
    weight: Gwei
    withdrawal: BuilderPendingWithdrawal

`BuilderPendingWithdrawal`

class BuilderPendingWithdrawal(Container):
    fee_recipient: ExecutionAddress
    amount: Gwei
    builder_index: BuilderIndex

`PayloadAttestationData`

class PayloadAttestationData(Container):
    beacon_block_root: Root
    slot: Slot
    payload_present: boolean
    blob_data_available: boolean

`PayloadAttestation`

class PayloadAttestation(Container):
    aggregation_bits: Bitvector[PTC_SIZE]
    data: PayloadAttestationData
    signature: BLSSignature

`PayloadAttestationMessage`

class PayloadAttestationMessage(Container):
    validator_index: ValidatorIndex
    data: PayloadAttestationData
    signature: BLSSignature

`IndexedPayloadAttestation`

class IndexedPayloadAttestation(Container):
    attesting_indices: List[ValidatorIndex, PTC_SIZE]
    data: PayloadAttestationData
    signature: BLSSignature

`ExecutionPayloadBid`

class ExecutionPayloadBid(Container):
    parent_block_hash: Hash32
    parent_block_root: Root
    block_hash: Hash32
    prev_randao: Bytes32
    fee_recipient: ExecutionAddress
    gas_limit: uint64
    builder_index: BuilderIndex
    slot: Slot
    value: Gwei
    execution_payment: Gwei
    blob_kzg_commitments: List[KZGCommitment, MAX_BLOB_COMMITMENTS_PER_BLOCK]

`SignedExecutionPayloadBid`

class SignedExecutionPayloadBid(Container):
    message: ExecutionPayloadBid
    signature: BLSSignature

`ExecutionPayloadEnvelope`

class ExecutionPayloadEnvelope(Container):
    payload: ExecutionPayload
    execution_requests: ExecutionRequests
    builder_index: BuilderIndex
    beacon_block_root: Root
    slot: Slot
    state_root: Root

`SignedExecutionPayloadEnvelope`

class SignedExecutionPayloadEnvelope(Container):
    message: ExecutionPayloadEnvelope
    signature: BLSSignature

Modified containers

`BeaconBlockBody`

Note: The removed fields (execution_payload, blob_kzg_commitments, and execution_requests) now exist in ExecutionPayloadEnvelope.

class BeaconBlockBody(Container):
    randao_reveal: BLSSignature
    eth1_data: Eth1Data
    graffiti: Bytes32
    proposer_slashings: List[ProposerSlashing, MAX_PROPOSER_SLASHINGS]
    attester_slashings: List[AttesterSlashing, MAX_ATTESTER_SLASHINGS_ELECTRA]
    attestations: List[Attestation, MAX_ATTESTATIONS_ELECTRA]
    deposits: List[Deposit, MAX_DEPOSITS]
    voluntary_exits: List[SignedVoluntaryExit, MAX_VOLUNTARY_EXITS]
    sync_aggregate: SyncAggregate
    # [Modified in Gloas:EIP7732]
    # Removed `execution_payload`
    bls_to_execution_changes: List[SignedBLSToExecutionChange, MAX_BLS_TO_EXECUTION_CHANGES]
    # [Modified in Gloas:EIP7732]
    # Removed `blob_kzg_commitments`
    # [Modified in Gloas:EIP7732]
    # Removed `execution_requests`
    # [New in Gloas:EIP7732]
    signed_execution_payload_bid: SignedExecutionPayloadBid
    # [New in Gloas:EIP7732]
    payload_attestations: List[PayloadAttestation, MAX_PAYLOAD_ATTESTATIONS]

`BeaconState`

class BeaconState(Container):
    genesis_time: uint64
    genesis_validators_root: Root
    slot: Slot
    fork: Fork
    latest_block_header: BeaconBlockHeader
    block_roots: Vector[Root, SLOTS_PER_HISTORICAL_ROOT]
    state_roots: Vector[Root, SLOTS_PER_HISTORICAL_ROOT]
    historical_roots: List[Root, HISTORICAL_ROOTS_LIMIT]
    eth1_data: Eth1Data
    eth1_data_votes: List[Eth1Data, EPOCHS_PER_ETH1_VOTING_PERIOD * SLOTS_PER_EPOCH]
    eth1_deposit_index: uint64
    validators: List[Validator, VALIDATOR_REGISTRY_LIMIT]
    balances: List[Gwei, VALIDATOR_REGISTRY_LIMIT]
    randao_mixes: Vector[Bytes32, EPOCHS_PER_HISTORICAL_VECTOR]
    slashings: Vector[Gwei, EPOCHS_PER_SLASHINGS_VECTOR]
    previous_epoch_participation: List[ParticipationFlags, VALIDATOR_REGISTRY_LIMIT]
    current_epoch_participation: List[ParticipationFlags, VALIDATOR_REGISTRY_LIMIT]
    justification_bits: Bitvector[JUSTIFICATION_BITS_LENGTH]
    previous_justified_checkpoint: Checkpoint
    current_justified_checkpoint: Checkpoint
    finalized_checkpoint: Checkpoint
    inactivity_scores: List[uint64, VALIDATOR_REGISTRY_LIMIT]
    current_sync_committee: SyncCommittee
    next_sync_committee: SyncCommittee
    # [Modified in Gloas:EIP7732]
    # Removed `latest_execution_payload_header`
    # [New in Gloas:EIP7732]
    latest_execution_payload_bid: ExecutionPayloadBid
    next_withdrawal_index: WithdrawalIndex
    next_withdrawal_validator_index: ValidatorIndex
    historical_summaries: List[HistoricalSummary, HISTORICAL_ROOTS_LIMIT]
    deposit_requests_start_index: uint64
    deposit_balance_to_consume: Gwei
    exit_balance_to_consume: Gwei
    earliest_exit_epoch: Epoch
    consolidation_balance_to_consume: Gwei
    earliest_consolidation_epoch: Epoch
    pending_deposits: List[PendingDeposit, PENDING_DEPOSITS_LIMIT]
    pending_partial_withdrawals: List[PendingPartialWithdrawal, PENDING_PARTIAL_WITHDRAWALS_LIMIT]
    pending_consolidations: List[PendingConsolidation, PENDING_CONSOLIDATIONS_LIMIT]
    proposer_lookahead: Vector[ValidatorIndex, (MIN_SEED_LOOKAHEAD + 1) * SLOTS_PER_EPOCH]
    # [New in Gloas:EIP7732]
    builders: List[Builder, BUILDER_REGISTRY_LIMIT]
    # [New in Gloas:EIP7732]
    next_withdrawal_builder_index: BuilderIndex
    # [New in Gloas:EIP7732]
    execution_payload_availability: Bitvector[SLOTS_PER_HISTORICAL_ROOT]
    # [New in Gloas:EIP7732]
    builder_pending_payments: Vector[BuilderPendingPayment, 2 * SLOTS_PER_EPOCH]
    # [New in Gloas:EIP7732]
    builder_pending_withdrawals: List[BuilderPendingWithdrawal, BUILDER_PENDING_WITHDRAWALS_LIMIT]
    # [New in Gloas:EIP7732]
    latest_block_hash: Hash32
    # [New in Gloas:EIP7732]
    payload_expected_withdrawals: List[Withdrawal, MAX_WITHDRAWALS_PER_PAYLOAD]

The BeaconState container is modified with the addition of:

builders, of type List[Builder, BUILDER_REGISTRY_LIMIT] to track the new in-protocol staked builders.
next_withdrawal_builder_index of type BuilderIndex to help tracking builder withdrawals.
execution_payload_availability, of type Bitvector[SLOTS_PER_HISTORICAL_ROOT] to track the presence of execution payloads on the canonical chain.
builder_pending_payments, of type Vector[BuilderPendingPayment, 2 * SLOTS_PER_EPOCH] to track pending payments from builders to proposers before the execution payload has been processed.
builder_pending_withdrawals, of type List[BuilderPendingWithdrawal, BUILDER_PENDING_WITHDRAWALS_LIMIT] to track pending withdrawals to the execution layer with the builders’ payments.
latest_block_hash, of type Hash32, to track the blockhash of the last execution payload in the blockchain.
payload_expected_withdrawals of type List[Withdrawal, MAX_WITHDRAWALS_PER_PAYLOAD] to track the latest withdrawals that were deducted in the consensus layer and need to still be honored in the Execution Layer.

The BeaconBlockBody is modified with the addition of:

signed_execution_payload_bid of type SignedExecutionPayloadBid with the builder’s commitment.
payload_attestations of type List[PayloadAttestation, MAX_PAYLOAD_ATTESTATIONS] a list of PTC attestations from the previous slot.

The ExecutionPayloadHeader object is changed (and renamed to ExecutionPayloadBid) to only track the minimum information needed to commit to a builder’s payload.

State transition logic is modified by:

A new beacon state getter get_ptc returns the PTC members for a given slot.
process_withdrawals is modified as follows. Withdrawals are obtained directly from the beacon state instead of the execution payload. They are deducted from the beacon chain. The beacon state latest_withdrawals_root is updated with the HTR of this list. The next execution payload MUST include withdrawals matching the state.latest_withdrawals_root.
process_execution_payload is removed from process_block. Instead a new function process_execution_payload_bid is included, this function validates the SignedExecutionPayloadBid included in the BeaconBlockBody, ensures the payment from the builder’s balance can be deducted and adds a BuilderPendingPayment object to the beacon state.
process_deposit_request is removed from process_operations and deferred until process_execution_payload. Special care is added for deposit requests from new validator pubkeys, with withdrawal credentials starting with the prefix BUILDER_WITHDRAWAL_PREFIX. These deposits are immediately added to the beacon chain and processed as new builders.
process_withdrawal_request is removed from process_operations and deferred until process_execution_payload.
process_consolidation_request is removed from process_operations and deferred until process_execution_payload.
A new process_payload_attestation is added to process_operations, this function validates the payload timeliness attestations broadcast by the PTC members.
process_execution_payload is now called as a separate helper when receiving a SignedExecutionPayloadEnvelope on the P2P layer. This function in particular checks that the HTR of the resulting beacon state coincides with the committed one in the payload envelope. On sucessful processing of the execution payload, the corresponding BuilderPendingPayment is removed from the beacon state and a BuilderPendingWithdrawal is queued.

Epoch processing is modified by addition of a new helper function process_builder_pending_payments, that processes the builder pending payments from those payloads that were not included in the canonical chain. Although there is no change in the AttestationData object, the index field which is unused since the Electra fork, is now repurposed to signal payload availability. The value of 0 is used when attesting to the current beacon block or a past beacon block without a payload present, and the value of 1 is used to attest to a past beacon block with a payload present.

Fork-Choice changes

Forkchoice is changed substantially to deal with the fact that forkchoice nodes can have different payload content.

P2P changes

A new global topic for broadcasting SignedExecutionPayloadBid messages (builder bids).
A new global topic for broadcasting PayloadAttestationMessage objects.
A new global topic for broadcasting ProposerPreferences objects.

Engine API

No changes needed.

Rationale

Staked builders

Being a builder is a new type of entity tracked in the beacon state. As such builders are staked in the beacon chain and they have their own withdrawal credential prefix. This allows for in-protocol trustless enforcement of the builder’s payment to the proposer. Alternatively, payment could be enforced in the Execution Layer (EL) at the cost of adding the corresponding EL consensus-changing logic. Payments in the EL have the advantage of not requiring the builder to periodically submit deposit transactions to replenish their validator balance. Both systems require availability of funds before the payload is revealed: in the Consensus Layer (CL) this is done by getting builders to stake. In the EL this is done with a balance check and a payment transaction. This transaction can be checked without executing the payload only if it the first transaction of the block.

Delayed validation

The Payload Timeliness Committee members do not need to validate the execution payload before attesting to it. They perform basic checks such as verifying the builder’s signature, and the correct blockhash is included. This takes away the full execution payload validation from the hot path of validation of an Ethereum block, giving the next proposer 6 seconds (SECONDS_PER_SLOT * 2 // INTERVALS_PER_SLOT) to validate the payload and every other validator 9 seconds (SECONDS_PER_SLOT * 3 // INTERVALS_PER_SLOT). From a user UX perspective, a transaction included in slot N by the builder is not widely validated until the proposer of slot N+1 releases their beacon block on top of block N first and the attesters of slot N+1 vote on this beacon block as the head of the chain.

Fork choice

The following features of fork choice are guaranteed under specified margins of security:

Proposer unconditional payment.
Builder reveal safety.
Builder withhold safety.

Proposer unconditional payment refers to the following. An Ethereum slot can be either:

Full: both the beacon block and the execution payload have been revealed and included on-chain.
Skipped: No beacon block (and therefore no execution payload) has been included on-chain for this slot.
Empty: The beacon block has been included on-chain, but the committed execution payload has not.

Proposer unconditional payment refers to the fact that in the third scenario the beacon block proposer received payment from the corresponding builder.

Builder reveal safety refers to the fact that if the builder acted honestly and revealed a payload in a timely fashion (as attested by the PTC) then the revealed payload will be included on-chain.

Builder withhold safety refers to the fact that if some beacon block containing a builder’s commitment is withheld and revealed late, the builder will not be charged the value of the bid. In particular, the payload does not even need to be revealed in this case.

The precise method by which these safety mechanisms are enforced is by allowing attestations to also signal their view of the slot as in either of the above options Full, Skipped or Empty. For this, the index field in the AttestationData is used as explained above.

PTC equivocations

There is no penalty for PTC nor payload equivocation (that is revealing the right payload and also a withheld message at the same time). A collusion of a builder controlling network partition with a single malicious PTC member could cause a split view by achieving consensus both on payload withheld and a payload present. This could be mitigated by setting PAYLOAD_TIMELY_THRESHOLD to be 2/3 of the PTC, in which case the malicious operator would have to control at least 33% of the PTC.

Another mitigation mechanism is to add new slashing conditions for payload equivocation or PTC equivocations (both are signed messages by validators).

Since this attack results in a split view at a cost for the builder (the payload is revealed and may not be included) this EIP opted for simplicity of implementation.

Withdrawals

Withdrawals from the beacon chain are complex in nature, they involve removing funds from one layer and crediting them on another, with different trigger mechanisms that can start from either layer. Before applying the consensus layer state transition function to a given beacon state pre_state and processing a given signed beacon block block, the set of withdrawals that are expected to be deducted from the beacon chain are completely determined by pre_state. Previous to this EIP the set of withdrawals that are credited on the execution layer are included in block. The block is deemed invalid if these withdrawals do not match. With the separation included in this EIP, these operations of deducting and crediting become asynchronous:

When processing the beacon block, the withdrawals are deducted from the beacon chain.
The set of withdrawals just deducted is committed to the beacon state post_state.
When processing any execution payload whose parent beacon state is post_state, the payload is deemed invalid if it doesn’t include precisely the list of withdrawals committed to post_state.

This asynchronous mechanism has some consequences as slots may be empty as defined above. In these cases, the consensus layer does not process any more withdrawals until an execution payload has fulfilled the outstanding ones. An alternative design would be to defer all of withdrawal processing to the execution payload validation phase (ie. process_execution_payload). This has the advantage of not needing to track the fulfilled withdrawals on the beacon chain. The logic changes when several payloads are missing, in which case balances on the beacon chain change and therefore a withdrawal that would be possible with the former mechanism may be different, or even impossible with the latter.

Three state transition functions

The current EIP adds an extra state transition function to the block processing in Ethereum. Processing a SignedBeaconBlock changes the consensus layer BeaconState. A SignedExecutionPayloadEnvelope changes both the execution layer state and the consensus layer one. As such, the envelope commits to the consensus layer post-state-transition beacon state root.

Compatible designs

Inclusion lists

This EIP is fully compatible with forkchoice enforced inclusion lists or similar.

Slot auctions

A simple change to this EIP is to remove the blockhash commitment from the SignedExecutionPayloadBid. This allows the builder to commit any payload to the slot. A preliminary security analysis shows that payload equivocation does not weaken fork choice’s FFG. Some advantages of Slot auctions include:

Better user experience as any submitted transaction can be included in the next block (with block auctions a transaction sent in the first half of the slot can only be included in the following block).
Longer continuous time to build blocks.
Better compatibility designs with fork choice enforced inclusion list proposals.

Backwards Compatibility

This EIP introduces backward incompatible changes to the block validation rule set on the consensus layer and must be accompanied by a hard fork.

Security Considerations

Free option problem

Economically rational but malicious (as defined by the honest builder guide) builders may chose to withhold their payload in the event that it would be profitable for them. This could result in missed slots and degradation of user experience of Ethereum. Some preliminary data in the form of simulation suggests that the number of these occurrences may be noticeable. Some mitigations were proposed in the form of variable penalties for builders that fail to include their payload envelopes in the canonical chain.

Builder safety

A colluding set of proposers and attesters controlling consecutive blocks and more than 20% of the total stake can reorg a builder’s payload and force it to pay the bid’s value.
There is no possible unbundling of the builder’s payload in the same slot, that is, if the builder reveals a payload for the head of the chain, no other payload is possible for the current slot.

Malicious PTC

The expected time for a malicious attacker, controlling 35% of the total stake, to have a majority control on the PTC is 205 000 years.

Copyright

Code Index

Tue, 16 Jul 2024 00:00:00 +0000

EIP #7744 - Code Index is in Last Call status. It is authored by Tim Pechersky (@peersky) and was originally created 2024-07-16. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/erc-7744-code-index/20569

Abstract

This EIP defines a standard interface for indexing smart contracts on Ethereum by their bytecode hash. This enables trustless discovery and verification of contract code, facilitating use cases like bytecode signing, whitelisting, and decentralized distribution mechanisms.

Motivation

Existing contract discovery relies on addresses, which are non-deterministic and can be obfuscated through proxies. Indexing by bytecode hash provides a deterministic and tamper-proof way to identify and verify contract code, enhancing security and trust in the Ethereum ecosystem.

Consider a security auditor who wants to attest to the integrity of a contract’s code. By referencing bytecode hashes, auditors can focus their audit on the bytecode itself, without needing to assess deployment parameters or storage contents. This method verifies the integrity of a contract’s codebase without auditing the entire contract state.

Additionally, bytecode referencing allows whitelist contracts before deployment, allowing developers to get pre-approval for their codebase without disclosing the code itself, or even pre-setup infrastructure that will change it behavior upon adding some determined functionality on chain.

For developers relying on extensive code reuse, bytecode referencing protects against malicious changes that can occur with address-based referencing through proxies. This builds long-term trust chains extending to end-user applications.

For decentralized application (dApp) developers, a code index can save gas costs by allowing them to reference existing codebases instead of redeploying them, optimizing resource usage. This can be useful for dApps that rely on extensive re-use of same codebase as own dependencies.

Why this registry needs to be an ERC

The Code Index is essential for trustless and secure smart contract development. By standardizing the interface for indexing contracts by their bytecode, developers can easily integrate this feature into their smart contracts, enhancing the security and trustworthiness of the Ethereum ecosystem.

Its simplicity and generic nature make it suitable for a wide range of applications. The ability to globally reference the same codebase makes it an ideal candidate for standardization.

Ultimately, this feature should be incorporated into EIP standards, as it is a fundamental building block for trustless and secure smart contract development. This standard is a step towards this goal.

Specification

// SPDX-License-Identifier: CC0-1.0
pragma solidity 0.8.28;
import {IERC7744} from "./IERC7744.sol";

/**
 * @title Byte Code Indexer Contract
 * @notice You can use this contract to index contracts by their bytecode.
 * @dev This allows to query contracts by their bytecode instead of addresses.
 * @author Tim Pechersky (@Peersky)
 */
contract ERC7744 is IERC7744 {
    mapping(bytes32 => address) private index;

    function isEIP7702(address account) public view returns (bool) {
        bytes3 prefix;
        assembly {
            extcodecopy(account, 0, mload(0x40), 3) // Copy first 3 bytes to memory
            prefix := mload(0x40) // Load the 3 bytes from memory
        }
        return prefix == bytes3(0xef0100);
    }

    function isValidContainer(address container) private view returns (bool) {
        bytes memory code = container.code;
        bytes32 codeHash = address(container).codehash;
        return (code.length > 0 && codeHash != bytes32(0) && !isEIP7702(container));
    }

    /**
     * @notice Registers a contract in the index by its bytecode hash
     * @param container The contract to register
     * @dev `msg.codeHash` will be used
     * @dev It will revert if the contract is already indexed or if returns EIP7702 delegated EOA
     */
    function register(address container) external {
        address etalon = index[container.codehash];
        require(isValidContainer(container), "Invalid container");
        if (etalon != address(0)) {
            if (isValidContainer(etalon)) revert alreadyExists(container.codehash, container);
        }
        index[container.codehash] = container;
        emit Indexed(container, container.codehash);
    }

    /**
     * @notice Returns the contract address by its bytecode hash
     * @dev returns zero if the contract is not indexed
     * @param id The bytecode hash
     * @return The contract address
     */
    function get(bytes32 id) external view returns (address) {
        return index[id];
    }
}

Deployment method

The CodeIndex contract is deployed at: 0xC0De1D1126b6D698a0073A4e66520111cEe22F62 using CREATE2 via the deterministic deployer at 0x4e59b44847b379578588920ca78fbf26c0b4956c with a salt of 0x9425035d50edcd7504fe5eeb5df841cc74fe6cccd82dca6ee75bcdf774bd88d9 is obtained by seeking a vanity address starting with meaningful name “Code ID (c0de1d) for a bytecode compiled with solc 0.8.28 as solc --input-file src/ERC7744.sol --bin --optimize --optimize-runs 2000 --metadata-hash none --via-ir --optimize-yul

Rationale

Bytecode over Addresses: Bytecode is deterministic and can be verified on-chain, while addresses are opaque and mutable.

Reverting on re-indexing: There is small, yet non-zero probability of hash collision attack. Disallowing updates to indexed location of bytecode coupes with this.

Simple Interface: The interface is minimal and focused to maximize composability and ease of implementation.

Library Implementation: Implementing this as a library would limit its impact, making code reuse more difficult and lacking a single, official source of truth. By establishing this as an ERC, we ensure standardization and widespread adoption, driving the ecosystem forward.

Reference Implementation

Reference implementation of the Code Index can be found in the assets folder. There you can find the interface and the implementation of the Code Index.

Security Considerations

Malicious Code: The index does NOT guarantee the safety or functionality of indexed contracts. Users MUST exercise caution and perform their own due diligence before interacting with indexed contracts.

Storage contents of registered contracts: The index only refers to the bytecode of the contract, not the storage contents. This means that the contract state is not indexed and may change over time.

EIP-7702: The index does not index the EIP-7702 delegated accounts. During attempt to register, it checks if contract code begins with reserved delegation designator 0xef0100 and if so, it will revert.

Self-Destruct Contracts: In case of indexed contract storage becomes empty, contracts may be re-indexed, During register function call, if contract is already indexed, we run isValidContainer check on the indexed address. It it fails, re-indexing is allowed with a newly specified address.

Copyright

Composable Security Middleware Hooks

Wed, 17 Jul 2024 00:00:00 +0000

EIP #7746 - Composable Security Middleware Hooks is in Last Call status. It is authored by Tim Pechersky (@peersky) and was originally created 2024-07-17. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/erc-7746-composable-security-middleware-hooks/19471

Abstract

This EIP proposes a standard interface, ILayer, for implementing composable security layers in smart contracts. These layers act as middleware, enabling runtime validation of function calls before and after execution, independent of the protected contract’s logic. This approach facilitates modular security, allowing independent providers to manage and upgrade security layers across multiple contracts.

Motivation

Current smart contract security practices often rely on monolithic validation logic within the contract itself. This can lead to tightly coupled code, making it difficult to isolate and address security concerns. Better structured architecture is needed, middleware like approach is widely used in the industry, allowing to wrap calls in other calls in generic and repeatable pattern with same call signatures.

The Security Layers Standard introduces a modular approach, enabling:

Independent Security Providers: Specialized security providers can focus on developing and maintaining specific security checks.
Composable Security: Layers can be combined to create comprehensive security profiles tailored to individual contract needs.
Upgradability: Security layers can be updated without requiring changes to the protected contract.
Flexibility: Layers can perform a wide range of validation checks, including access control, input sanitization, output verification, and more.

Having a generalized standard for such layers can help to build more secure and modular systems as well as enable security providers to build generic, service-oriented security oracle solutions.

Specification

A contract implementing the ILayer interface MUST provide two functions:

// SPDX-License-Identifier: CC0-1.0
pragma solidity 0.8.20;

interface ILayer {
    /// @notice Validates a function call before execution.
    /// @param configuration Layer-specific configuration data.
    /// @param selector The function selector being called.
    /// @param sender The address initiating the call.
    /// @param value The amount of ETH sent with the call (if any).
    /// @param data The calldata for the function call.
    /// @return beforeCallResult Arbitrary data to be passed to `afterCallValidation`.
    /// @dev MUST revert if validation fails.
    function beforeCall(
        bytes memory configuration,
        bytes4 selector,
        address sender,
        uint256 value,
        bytes memory data
    ) external returns (bytes memory);

    /// @notice Validates a function call after execution.
    /// @param configuration Layer-specific configuration data.
    /// @param selector The function selector being called.
    /// @param sender The address initiating the call.
    /// @param value The amount of ETH sent with the call (if any).
    /// @param data The calldata for the function call.
    /// @param beforeCallResult The data returned by `beforeCallValidation`.
    /// @dev MUST revert if validation fails.
    function afterCall(
        bytes memory configuration,
        bytes4 selector,
        address sender,
        uint256 value,
        bytes memory data,
        bytes memory beforeCallResult
    ) external;
}

A protected contract MAY integrate security layers by calling the beforeCallValidation function before executing its logic and the afterCallValidation function afterwards. Multiple layers can be registered and executed in a defined order. The protected contract MUST revert if any layer reverts.

Rationale

Flexibility: The layerConfig parameter allows for layer-specific customization, enabling a single layer implementation to serve multiple contracts with varying requirements.

non-static calls: Layers can maintain their own state, allowing for more complex validation logic (e.g., rate limiting, usage tracking).

Strict Validation: Reverts on validation failure ensure a fail-safe mechanism, preventing execution of potentially harmful transactions.

Gas Costs: Layers naturally will have gas costs associated with their execution. However, the benefits of enhanced security and modularity outweigh these costs, especially as blockchain technology continues to evolve and we expect gas costs to decrease over time.

Reference Implementation

A reference implementation of the ILayer interface and a sample protected contract can be found in the repository: In the ILayer.sol a reference interface is provided.

In this test, a Protected.sol contract is protected by a RateLimitLayer.sol layer. The RateLimitLayer implements the ILayer interface and enforces a rate which client has configured. The Drainer simulates a vulnerable contract that acts in a malicious way. In the test.ts The Drainer contract is trying to drain the funds from the Protected contract. It is assumed that Protected contract has bug that allows partial unauthorized access to the state. The RateLimitLayer is configured to allow only 10 transactions per block from same sender. The test checks that the Drainer contract is not able to drain the funds from the Protected contract.

Security Considerations

Layer Trust: Thoroughly audit and vet any security layer before integrating it into your contract. Malicious layers can compromise contract security.

Copyright

Block Gas Accounting without Refunds

Tue, 01 Oct 2024 00:00:00 +0000

EIP #7778 - Block Gas Accounting without Refunds is in Last Call status. It is authored by Ben Adams (@benaadams), Toni Wahrstätter (@nerolation) and was originally created 2024-10-01. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-7778-prevent-block-gas-smuggling/21234

Abstract

This EIP modifies the block gas accounting mechanism to prevent the circumvention of block gas limits. It proposes that gas refunds, particularly those from SSTORE operations setting storage slots to zero, should not reduce the gas counted toward the block gas limit, while still being applied to transaction gas costs for users.

Motivation

Currently, gas refunds from operations like clearing storage slots (setting to zero) reduce both the transaction gas cost for users and the gas counted toward the block gas limit. This creates a discrepancy between the computational work performed and the gas accounted for in the block.

Example: Block 20878522 shows a net usage of 28.5 MGas, but contains 4.01 MGas of refunds, bringing the gross usage to 32.51 MGas—exceeding the block gas limit by 2.51 MGas.

This mechanism can be exploited to perform more operations in a block than the gas limit intends to allow, potentially leading to:

Network instability due to oversized blocks
Denial-of-service vectors
Computational loads exceeding the intended block gas limit

Specification

Gas Accounting Changes

User Gas Accounting (Unchanged):
- Users continue to receive gas refunds for operations that qualify (e.g., setting storage to zero)
- Transaction gas: gas_spent = max(tx_gas_used - gas_refund, calldata_floor_gas_cost)
Block Gas Accounting (Modified):
- When calculating gas for block gas limit enforcement, refunds are not subtracted
- Block gas accounting becomes: block.gas_used += max(tx_gas_used, calldata_floor_gas_cost) (incorporating the calldata floor from EIP-7623)
- Storage discounts that reflect actual reduced computational work (e.g., warm storage access, reverting to original values) remain applied to block gas accounting

Rationale

Aligning Gas Limits with Computational Work

The block gas limit is designed to constrain the computational load per block. Gas refunds were introduced to incentivize “cleaning up” the state, not to allow exceeding computational limits. By excluding refunds from block gas accounting, we ensure the block gas limit effectively constrains computational load

Preserving User Incentives

Users still receive gas refunds, maintaining incentives for efficient state management. Only the accounting for block-level constraints changes, not the economics for individual users

Backwards Compatibility

This change is not backwards compatible and requires a hard fork
User and developer experience for individual transactions remains unchanged
Block producers need to adjust their transaction selection algorithms to account for the new gas accounting rules

Test Cases

SSTORE Operations:
- Setting storage to zero: User receives refund, but block gas accounting uses full cost
- Verify blocks containing many storage-clearing operations still adhere to gas limits
Block Gas Limit Edge Cases:
- Construct blocks with varying amounts of refundable operations
- Ensure blocks cannot exceed gas limits through refund mechanisms
Transaction Gas vs Block Gas:
- Verify that transaction costs for users remain unchanged
- Confirm block gas accounting properly excludes refunds

Security Considerations

Eliminates potential denial-of-service vectors that exploit gas refunds to exceed block computational limits
Improves predictability of block processing times by enforcing stricter limits on computational work
Prevents miners/validators from including transactions that collectively contain more computational work than intended

Copyright

SLOTNUM opcode

Fri, 06 Dec 2024 00:00:00 +0000

EIP #7843 - SLOTNUM opcode is in Last Call status. It is authored by Marc Harvey-Hill (@Marchhill) and was originally created 2024-12-06. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-7843-slotnum-opcode/22234

Abstract

This EIP proposes to add a new opcode SLOTNUM (0x4b), that returns the corresponding slot number for the current block.

Motivation

There are currently two ways to get the current slot number onchain:

1) Calculate from the block timestamp. This requires hardcoding the chain slot length into a smart contract.

2) Provide the slot number as calldata and prove it against the beacon block root (using EIP-4788).

Both of these approaches have significant drawbacks. (1) would break contracts in the event of a change to the slot length. (2) is expensive in terms of gas, encouraging approach (1) to be used instead.

A better approach is for the slot length to be abstracted away from applications, and instead the slot number can be calculated in the consensus layer client and exposed by an opcode. This paves the way for future changes to the slot length.

Specification

A new opcode SLOTNUM is introduced at 0x4b. It shall return one stack element.

Output

One element slotNumber is added to the stack; it is equal to the corresponding slot number for this block. slotNumber is a uint64 in big endian encoding.

Gas Cost

The gas cost for SLOTNUM is a fixed fee of 2.

RPC changes

The slot number is calculated in the consensus layer and passed to the execution layer through the engine API.

Header extension

The header encoding shall be extended to include a slotNumber field of type uint64.

Engine API changes

New objects ExecutionPayloadV4 and PayloadAttributesV4 are introduced, adding a slotNumber field of type uint64. The methods engine_newPayloadV5, engine_getPayloadV6, and engine_forkchoiceUpdatedV4 are added, to use the new objects.

Rationale

Gas Price

The opcode is priced to match similar opcodes in the W_base set.

Calculation in consensus layer

The slot number could alternatively be calculated in the execution layer using the timestamp, but it is more appropriate to calculate values pertaining to the beacon chain in the consensus layer. Additionally this avoids code duplication, as the slot number is already calculated in the consensus layer.

ZK-VM proving

The SLOTNUM opcode should not increase the complexity of proving EVM execution, as it is similar to existing opcodes such as TIMESTAMP. The slot number is included in the block header rather than as a engine_newPayload parameter, ensuring that the block is self-contained for proving; no extra inputs to the circuit are required.

Backwards Compatibility

No backward compatibility issues found.

Test Cases

N/A

Security Considerations

None.

Copyright

Compute Gas Cost Analysis

Wed, 05 Feb 2025 00:00:00 +0000

EIP #7904 - Compute Gas Cost Analysis is in Last Call status. It is authored by Jacek Glen (@JacekGlen), Lukasz Glen (@lukasz-glen), Maria Silva (@misilva73) and was originally created 2025-02-05. It is in the category of type Informational. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/gas-cost-repricing-to-reflect-computational-complexity/23067

Abstract

This document reports an empirical analysis of the runtime of EVM compute operations and precompiles across the major execution clients. Measurements were taken on clients that include the parallel-execution optimizations enabled by EIP-7928 (Block-Level Access Lists). Using a target throughput of 100 million gas per second (Mgas/s), the analysis finds that every compute operation and precompile examined already performs at or above that target under the current gas schedule. We therefore conclude that no compute operation or precompile requires a gas-cost increase, and this EIP recommends no changes to the gas schedule.

Motivation

Earlier revisions of this proposal were Standards Track and aimed to raise the gas cost of a set of compute operations and precompiles that empirical measurement had shown performing below the target throughput. The intent was to remove these operations as bottlenecks so that the block gas limit could be raised safely.

Since those measurements were taken, the client-side optimizations unlocked by Block-Level Access Lists (EIP-7928) — parallel disk reads, parallel transaction validation, and executionless state updates — have stabilized across all major execution clients. Re-running the benchmark and estimation pipeline against clients with these optimizations in place changes the picture entirely: the operations that previously appeared underpriced now clear the 100 Mgas/s target comfortably at their current gas costs.

Because the original motivation for repricing no longer holds, this EIP is recorded as Informational. Its purpose is to document the analysis, preserve the methodology and data for future repricing work, and state the conclusion that no compute gas cost needs to change.

Specification

This EIP specifies no changes to the Ethereum gas schedule. No opcode or precompile gas cost is modified.

The analysis examined the 18 gas parameters listed below — the opcodes and precompiles that earlier revisions had flagged as candidates for repricing. For each parameter, the table reports the current gas cost against the gas cost implied by the worst-performing client at the 100 Mgas/s target. A proposed value at or below the current value means the operation already meets the throughput target at its current price.

Gas param	Current gas	Measured at 100 Mgas/s	Diff	Diff %
OPCODE_DIV	5	2	-3	-60%
OPCODE_SDIV	5	2	-3	-60%
OPCODE_MOD	5	2	-3	-60%
OPCODE_SMOD	5	3	-2	-40%
OPCODE_ADDMOD	8	3	-5	-62%
OPCODE_MULMOD	8	4	-4	-50%
OPCODE_KECCAK256_BASE	30	12	-18	-60%
OPCODE_KECCAK256_PER_WORD	6	3	-3	-50%
PRECOMPILE_ECRECOVER	3000	841	-2159	-72%
PRECOMPILE_BLAKE2F_BASE	0	94	+94	n/a
PRECOMPILE_BLAKE2F_PER_ROUND	1	1	0	0%
PRECOMPILE_BLS_G1ADD	375	236	-139	-37%
PRECOMPILE_BLS_G2ADD	600	277	-323	-54%
PRECOMPILE_ECADD	150	108	-42	-28%
PRECOMPILE_ECPAIRING_BASE	45000	8247	-36753	-82%
PRECOMPILE_ECPAIRING_PER_POINT	34000	11712	-22288	-66%
PRECOMPILE_POINT_EVALUATION	50000	23825	-26175	-52%
PRECOMPILE_P256VERIFY	6900	3814	-3086	-45%

Sixteen of the eighteen parameters measure cheaper than the current schedule, and one (PRECOMPILE_BLAKE2F_PER_ROUND) is unchanged. The only parameter that measures higher than the current schedule is the BLAKE2F base cost, which is currently unpriced (0 gas); the measured value of 94 gas is negligible relative to typical block gas usage and does not constitute a throughput bottleneck. On this basis, no operation is underpriced to a degree that warrants a gas-cost increase.

The full proposal report, including per-client breakdowns and worst-case provenance, accompanies this EIP.

Rationale

Empirical Estimation of Gas Costs

Target Throughput

A performance target of 100 million gas per second is used as the anchor for the analysis. This target reflects the throughput that the optimized clients are expected to sustain, a substantial increase over the historical baseline. An operation is considered adequately priced if its measured runtime at the current gas cost meets or exceeds this rate.

Data Collection

The estimates are based on the actual time each operation takes to run on the various execution clients. Similar to the methodology used in the Gas Cost Estimator project, we generate synthetic blocks that isolate and stress individual EVM operations.

Concretely, to benchmark a single operation, different blocks are created by varying the number of times the target operation is executed and by changing the parameter values to the operation. The EEST benchmark suite contains the tests used to generate these blocks.

Then, the Benchmarkoor tool is used to collect the needed metrics. This tool returns the total execution time of the block and the number of times each operation was executed. Each test block is run multiple times on each client to account for variability in execution time. The clients measured in the latest run are Besu, Erigon, ethrex, Geth, Nethermind, and Reth.

What about dynamic costs?

Some operations have a dynamic component to their costs. For example, the KECCAK256 opcode has a gas cost that grows with the size of the input. In these cases, the test benchmarks the operation with a range of inputs to assess how the resource costs vary with different inputs.

What about differences between client implementations?

Ultimately, we require a single cost model that is independent of the client’s implementation. Although the decision may be different in a specific situation, the general rule is to take the worst client result that cannot be optimized. This means that the worst-performing client on a given operation and resource combination defines the cost of that operation for the entire network. This is the safer and most conservative choice, and it is the value reported in the table above.

Runtime Estimation

To estimate the runtime of a single operation from the total execution time of the corresponding synthetic blocks, a Non-Negative Least Squares (NNLS) Linear Regression is used. This model enforces that all coefficients are non-negative, thus ensuring execution time cannot be negative. The model estimates runtime as a linear combination of:

Constant term (intercept): Base overhead for executing the test, which includes setup and teardown time
Operation count (slope): Number of times the operation is executed in the test. This parameter is the one that allows us to estimate the per-operation runtime.
Operation-specific parameters: Variables like number of rounds, message size, or number of pairs

For simple operations (i.e., without additional parameters), the model estimates: runtime = intercept + slope × operation_count

For variable operations, the model estimates: runtime = intercept + slope × operation_count + param1_coef × operation_count × param1 + param2_coef × operation_count × param2 + ...

Independent models are created for each client and operation. Only operations and parameters with good model fits (R² > 0.5 and p-value < 0.05) are relied upon for the conclusion, to ensure the reliability of the estimates.

The model-performance report breaks down the fit by operation and client, while the key model outputs are available as a CSV.

Conversion to gas costs

The measured gas costs in the table are calculated using the target performance of 100 Mgas/s. The formula used is:

gas = (anchor_rate * runtime_ms) / 1000

Where runtime_ms is the estimated runtime in milliseconds from the regression models and anchor_rate is 100 Mgas/s.

The full details of this step are in the proposal report.

Other Projects

Several initiatives have explored the real gas costs of EVM operations, providing valuable context for this analysis. Notable examples include:

The Gas Cost Estimator project did a similar empirical analysis. It conducted extensive testing across seven widely-used EVM implementations to measure the actual computational effort required by various opcodes and operations. Conducted in a controlled environment to eliminate external variables, the tests produced accurate and reproducible results. The findings highlight the relationship between the current gas cost schedule and the real-world computational complexity of EVM operations.
EIP-7883 - ModExp Gas Cost Increase: This EIP specifically analyzed ModExp and proposed a revised pricing scheme, consistent with the measuring approach used here.
Nethermind’s Gas Benchmarks: This project takes a different approach to measuring gas costs. It uses standalone clients rather than isolated EVM implementations. Despite the methodological difference, its results mirror those of the Gas Cost Estimator, reinforcing our conclusions.
EVM Memory Analysis by @raxhvl: This project focuses on memory-related costs, providing valuable insights into the memory access and expansion costs.

These projects collectively provide context for reassessing gas costs and demonstrate broad alignment with our measurements.

Interaction with EIP-7928

EIP-7928 introduces Block-Level Access Lists, which enable parallel disk reads, parallel transaction validation, and executionless state updates through client optimizations. The latest benchmarks were run on clients that have these optimizations implemented and stabilized. This is the central reason the analysis reaches a no-repricing conclusion: with the optimizations in place, the compute operations previously identified as bottlenecks now clear the target throughput at their current gas costs.

Computational Complexity Only

This analysis intentionally focuses on computational complexity—measured as execution time on a bare CPU — while excluding network-related costs like state persistency. This ensures the findings remain implementation-agnostic, applicable across diverse EVM clients regardless of their technological stack. By leveraging empirical data from multiple EVM implementations, we establish a universal, verifiable benchmark for computational effort. This focus simplifies estimation and enhances the analysis’s clarity and applicability within Ethereum’s varied ecosystem.

Why No Repricing Is Recommended

The original proposal adopted a conservative strategy: prioritize gas increases only for operations that empirical data showed as underpriced, so that the base throughput of the chain could be raised without changing the costs of the majority of operations. Applying that same standard to the latest data yields no candidates for repricing — the measured runtimes of all examined operations are consistent with, or cheaper than, their current gas costs at the 100 Mgas/s target. Lowering gas costs is out of scope for this analysis, which was concerned only with identifying and removing underpriced bottlenecks. Consequently, the gas schedule is left unchanged.

Consideration of ZK-SNARK Proof Generation

This analysis focuses on general computational complexity, using a bare CPU as the reference point. Therefore, it does not specifically address the unique demands of ZK-SNARK proof generation. Since the analysis recommends no gas-cost changes, it has no effect on proving times for EVM blocks.

Security Considerations

This is an Informational EIP that recommends no changes to the Ethereum protocol or gas schedule. It introduces no consensus changes and therefore no direct security implications.

The analysis itself is conservative: it relies on the worst-performing client for each operation and only draws conclusions from regression models with good statistical fits. Should client performance characteristics change in the future — for example, if an optimization is reverted or a new operation is introduced — the analysis should be re-run before relying on its conclusion that the current compute gas costs are adequate.

Copyright

Block-Level Access Lists

Mon, 31 Mar 2025 00:00:00 +0000

EIP #7928 - Block-Level Access Lists is in Last Call status. It is authored by Toni Wahrstätter (@nerolation), Dankrad Feist (@dankrad), Francesco D`Amato (@fradamt), Jochem Brouwer (@jochem-brouwer), Ignacio Hagopian (@jsign), Felipe Selmo (@fselmo), Rahul (@raxhvl), Stefan (@qu0b) and was originally created 2025-03-31. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-7928-block-level-access-lists/23337

Abstract

This EIP introduces Block-Level Access Lists (BALs) that record all accounts and storage locations accessed during block execution, along with their post-execution values. BALs enable parallel disk reads, parallel transaction validation, parallel state root computation and executionless state updates.

Motivation

Transaction execution cannot be parallelized without knowing in advance which addresses and storage slots will be accessed. While EIP-2930 introduced optional transaction access lists, they are not enforced.

This proposal enforces access lists at the block level, enabling:

Parallel disk reads and transaction execution
Parallel post-state root calculation
State reconstruction without executing transactions
Reduced execution time to parallel IO + parallel EVM

Specification

Block Structure Modification

We introduce a new field to the block header, block_access_list_hash, which contains the Keccak-256 hash of the RLP-encoded block access list. For an empty block access list, this is keccak256(rlp.encode([])) = 0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347.

class Header:
    # Existing fields
    ...
    
    block_access_list_hash: Hash32 = keccak256(rlp.encode(block_access_list))

The BlockAccessList is not included in the block body. The EL stores BALs separately and transmits them as a field in the ExecutionPayload via the engine API. The BAL is RLP-encoded as a list of AccountChanges. An empty block access list encodes as 0xc0, i.e. rlp.encode([]).

RLP Data Structures

BALs use RLP encoding following the pattern: address -> field -> block_access_index -> change.

# Type aliases for RLP encoding
Address = bytes20  # 20-byte Ethereum address
StorageKey = uint256  # Storage slot key
StorageValue = uint256  # Storage value
Bytecode = bytes  # Variable-length contract bytecode
BlockAccessIndex = uint32  # Block access index (0 for pre-execution, 1..n for transactions, n+1 for post-execution)
Balance = uint256  # Post-transaction balance in wei
Nonce = uint64  # Account nonce

# Core change structures (RLP encoded as lists)
# StorageChange: [block_access_index, new_value]
StorageChange = [BlockAccessIndex, StorageValue]

# BalanceChange: [block_access_index, post_balance]
BalanceChange = [BlockAccessIndex, Balance]

# NonceChange: [block_access_index, new_nonce]
NonceChange = [BlockAccessIndex, Nonce]

# CodeChange: [block_access_index, new_code]
CodeChange = [BlockAccessIndex, Bytecode]

# SlotChanges: [slot, [changes]]
# All changes to a single storage slot
SlotChanges = [StorageKey, List[StorageChange]]

# AccountChanges: [address, storage_changes, storage_reads, balance_changes, nonce_changes, code_changes]
# All changes for a single account, grouped by field type
AccountChanges = [
    Address,                    # address
    List[SlotChanges],          # storage_changes (slot -> [block_access_index -> new_value])
    List[StorageKey],           # storage_reads (read-only storage keys)
    List[BalanceChange],        # balance_changes ([block_access_index -> post_balance])
    List[NonceChange],          # nonce_changes ([block_access_index -> new_nonce])
    List[CodeChange]            # code_changes ([block_access_index -> new_code])
]

# BlockAccessList: List of AccountChanges
BlockAccessList = List[AccountChanges]

Scope and Inclusion

BlockAccessList is the set of all addresses accessed during block execution.

It MUST include:

Addresses with state changes (storage, balance, nonce, or code).
Addresses accessed without state changes, including:
- Targets of BALANCE, EXTCODESIZE, EXTCODECOPY, EXTCODEHASH opcodes
- Targets of CALL, CALLCODE, DELEGATECALL, STATICCALL (even if they revert; see Gas Validation Before State Access for inclusion conditions)
- Target addresses of CREATE/CREATE2 only once the EVM accesses the computed address: on post-access out-of-gas, on creation collision, or when creation setup increments the new account’s nonce; not on address computation alone, nor when creation fails before access (e.g. insufficient sender balance for the endowment, nonce overflow, or call stack depth limit)
- Deployed contract addresses from creation transactions, i.e. transactions with an empty to field, which are always included since the deployment address is unconditionally accessed during transaction setup
- Transaction sender and recipient addresses (even for zero-value transfers), unless the transaction halts before the recipient is loaded (see Exceptional halts)
- Beneficiary addresses for SELFDESTRUCT
- System contract addresses accessed during pre/post-execution; the system caller address, SYSTEM_ADDRESS (0xfffffffffffffffffffffffffffffffffffffffe), MUST NOT be included unless it experiences state access itself
- Withdrawal recipient addresses, regardless of whether the withdrawal amount is non-zero
- Precompiled contracts when called or accessed

Addresses with no state changes MUST still be present with empty change lists.

Entries from an EIP-2930 access list MUST NOT be included automatically. Only addresses and storage slots that are actually touched or changed during execution are recorded.

Block Access List Size Constraint

The block access list is constrained by the block gas limit rather than a fixed maximum number of items. The constraint is defined as:

bal_items <= block_gas_limit // ITEM_COST

Where:

bal_items = storage_keys + addresses
ITEM_COST = 2000

The storage_keys is the total number of storage keys across all accounts, and addresses is the total number of unique addresses accessed in the block. With EIP-7981, the cheapest way to add an item to the BAL is a cold SLOAD at COLD_SLOAD_COST (2100, as defined in EIP-2929). ITEM_COST is set deliberately below this minimum to create a buffer of approximately block_gas_limit / 42000 extra items, which absorbs BAL entries from system contract execution (e.g., EIP-2935, EIP-4788, EIP-7002, EIP-7251) and withdrawal recipients (EIP-4895) that do not consume block gas.

Gas Validation Before State Access

State-accessing opcodes perform gas validation in two phases:

Pre-state validation: Gas costs determinable without state access (memory expansion, base opcode cost, warm/cold access cost)
Post-state validation: Gas costs requiring state access (account existence, EIP-7702 delegation resolution)

Pre-state validation MUST pass before any state access occurs. If pre-state validation fails, the target resource (address or storage slot) is never accessed and MUST NOT be included in the BAL.

Once pre-state validation passes, the target is accessed and included in the BAL. Post-state costs are then calculated; their order is implementation-defined since the target has already been accessed.

The following table specifies pre-state validation costs in addition to the base opcode cost (gas constants as defined in EIP-2929):

Instruction	Pre-state Validation
`BALANCE`	`access_cost`
`SELFBALANCE`	None (accesses current contract, always warm)
`EXTCODESIZE`	`access_cost`
`EXTCODEHASH`	`access_cost`
`EXTCODECOPY`	`access_cost` + `memory_expansion` + `GAS_COPY`
`CALL`	`access_cost` + `memory_expansion` + `GAS_CALL_VALUE` (if value > 0)
`CALLCODE`	`access_cost` + `memory_expansion` + `GAS_CALL_VALUE` (if value > 0)
`DELEGATECALL`	`access_cost` + `memory_expansion`
`STATICCALL`	`access_cost` + `memory_expansion`
`CREATE`	`memory_expansion` + `INITCODE_WORD_COST` + `GAS_CREATE`
`CREATE2`	`memory_expansion` + `INITCODE_WORD_COST` + `GAS_KECCAK256_WORD` + `GAS_CREATE`
`SLOAD`	`access_cost`
`SSTORE`	`access_cost`, and more than `GAS_CALL_STIPEND` available
`SELFDESTRUCT`	`GAS_SELF_DESTRUCT` + `access_cost`

Where:

access_cost: For account-accessing opcodes, COLD_ACCOUNT_ACCESS_COST if cold and WARM_STORAGE_READ_COST if warm, except for a warm SELFDESTRUCT beneficiary, which has zero access cost as specified by EIP-2929. For storage-accessing opcodes (SLOAD and SSTORE), COLD_SLOAD_COST if cold and WARM_STORAGE_READ_COST if warm.
memory_expansion: Gas cost to expand memory for input/output regions

Post-state costs (e.g., GAS_NEW_ACCOUNT for calls to empty accounts, GAS_SELF_DESTRUCT_NEW_ACCOUNT if beneficiary does not exist) do not affect BAL inclusion since the target has already been accessed.

EIP-7702 Delegation

When a call target has an EIP-7702 delegation, the target is accessed to resolve the delegation, which also accesses the delegated address. The delegated address requires its own access_cost check before being accessed; if that gas check fails, the delegated address MUST NOT appear in the BAL. Otherwise both the original call target and the delegated address MUST appear in the BAL, including when the call subsequently fails its sender-balance (sender_balance >= value) or call-stack-depth check, since the delegation is resolved before those checks.

Note: Delegated accounts cannot be empty, so GAS_NEW_ACCOUNT never applies when resolving delegations.

SSTORE

SSTORE performs an implicit read of the current storage value for gas calculation. Before this read, the frame MUST cover the storage slot’s access_cost and MUST also satisfy the GAS_CALL_STIPEND sentry (gas_left > GAS_CALL_STIPEND); because the access cost can exceed GAS_CALL_STIPEND after repricing, the stipend sentry alone is no longer sufficient. If SSTORE fails this check, the storage slot MUST NOT appear in storage_reads or storage_changes.

Ordering, Uniqueness and Determinism

The following ordering rules MUST apply:

Accounts: Lexicographic by address
storage_changes: Slots by storage key value (ascending); within each slot, changes by block access index (ascending)
storage_reads: By storage key value (ascending)
balance_changes, nonce_changes, code_changes: By block access index (ascending)

The following uniqueness constraints MUST hold:

Each address MUST appear exactly once in BlockAccessList.
Each storage key MUST appear at most once in storage_changes per account.
Each storage key MUST appear at most once in storage_reads per account.
A storage key MUST NOT appear in both storage_changes and storage_reads for the same account.
Each block_access_index MUST appear at most once per change list (balance_changes, nonce_changes, code_changes, and per-slot StorageChange list).
Each SlotChanges entry MUST contain at least one StorageChange.

BlockAccessIndex Assignment

BlockAccessIndex values MUST be assigned as follows:

0 for pre‑execution system contract calls.
1 … n for transactions (in block order).
n + 1 for post‑execution system contract calls.

Recording Semantics by Change Type

Storage

Writes include:
- Any value change (post‑value ≠ pre‑value).
- Zeroing a slot (pre‑value exists, post‑value is zero).
Reads include:
- Slots accessed via SLOAD that are not written.
- Slots written with unchanged values (i.e., SSTORE where post-value equals pre-value, also known as “no-op writes”).

Note: Implementations MUST compare each write against the storage value as of immediately before the current block_access_index (i.e., the cumulative state from all prior indices, falling back to the pre-block state) to correctly distinguish between actual writes and no-op writes. A no-op write MUST NOT remove storage_changes entries from earlier indices for the same slot.

Balance (`balance_changes`)

Record post‑transaction balances (uint256) for:

Transaction senders (gas + value).
Transaction recipients (only if value > 0).
CALL/CALLCODE senders (value).
CALL/CALLCODE recipients (only if value > 0).
CREATE/CREATE2 recipients (only if value > 0).
COINBASE (rewards + fees).
SELFDESTRUCT/SENDALL beneficiaries.
Withdrawal recipients (system withdrawals, EIP-4895).

For unaltered account balances:

If an account’s balance changes during a transaction, but its post-transaction balance is equal to its pre-transaction balance, then the change MUST NOT be recorded in balance_changes. The sender and recipient address MUST still be included in AccountChanges.

The following special cases require addresses to be included with empty changes if no other state changes occur:

Zero-value transfer recipients
Calling a same-transaction SELFDESTRUCT on an address that had a zero pre-transaction balance

A zero-value block reward MUST NOT trigger a balance change in the block access list and MUST NOT, by itself, cause the recipient address to be included. The recipient MUST still be included if it is accessed for other reasons (e.g., transaction fee accounting).

Code

Track post‑transaction runtime bytecode for deployed or modified contracts, and delegation indicators for successful delegations as defined in EIP-7702.

Nonce

Record post‑transaction nonces for:

EOA senders.
Contracts that performed a successful CREATE or CREATE2.
Deployed contracts.
EIP-7702 authorities.

Edge Cases (Normative)

COINBASE / Fee Recipient: The COINBASE address follows the same inclusion rules as any other account. It is included when accessed (e.g., during transaction fee accounting) and excluded when not accessed (e.g., empty blocks with no relevant withdrawals).
Precompiled contracts: Precompiles MUST be included when accessed. If a precompile receives value, it is recorded with a balance change. Otherwise, it is included with empty change lists.
SENDALL: For positive-value selfdestructs, the sender and beneficiary are recorded with a balance change.
SELFDESTRUCT (in-transaction): Accounts destroyed within a transaction MUST be included in AccountChanges without nonce or code changes. However, if the account had a positive balance pre-transaction, the balance change to zero MUST be recorded. Storage keys within the self-destructed contracts that were modified or read MUST be included as a storage_reads entry.
Accessed but unchanged: Include the address with empty changes (e.g., targets of EXTCODEHASH, EXTCODESIZE, BALANCE, STATICCALL, etc.).
Zero‑value transfers / Unchanged balance in transaction: Include the address; omit from balance_changes.
Gas refunds: Record the final balance of the sender after each transaction.
Block rewards: Record the final balance of the fee recipient after each transaction.
Exceptional halts: Record the final nonce and balance of the sender, and the final balance of the fee recipient after each transaction. State changes from the reverted call are discarded, but all accessed addresses MUST be included. If no changes remain, addresses are included with empty lists; if storage was read, the corresponding keys MUST appear in storage_reads. A transaction can halt on a runtime gas charge before the recipient is loaded (e.g., during EIP-7702 authorization processing); the recipient is then never accessed and MUST NOT be included unless accessed for another reason.
Pre‑execution system contract calls: All state changes MUST use block_access_index = 0.
Post‑execution system contract calls: All state changes MUST use block_access_index = len(transactions) + 1.
EIP-7702 Delegations: The authority address MUST be included with nonce and code changes after any successful delegation set, update, or clear. If authorization fails after the authority address has been loaded and added to accessed_addresses (per EIP-2929), it MUST still be included with an empty change set; if authorization fails before the authority is loaded, it MUST NOT be included. The delegation target MUST NOT be included during delegation creation or modification and MUST only be included once it is actually loaded as an execution target (e.g., via CALL/CALLCODE/DELEGATECALL/STATICCALL under authority execution).
EIP‑4895 (Consensus layer withdrawals): Recipients are recorded with their final balance after the withdrawal.
EIP‑2935 (block hash): Record system contract storage diffs of the single updated storage slot in the ring buffer.
EIP‑4788 (beacon root): Record system contract storage diffs of the two updated storage slots in the ring buffer.
EIP‑7002 (withdrawals): Record system contract storage diffs of storage slots 0–3 (4 slots) after the dequeuing call. The dequeue also reads up to 3 × MAX_WITHDRAWAL_REQUESTS_PER_BLOCK queue data slots (from slot 4 onward), which appear as storage_reads.
EIP‑7251 (consolidations): Record system contract storage diffs of storage slots 0–3 (4 slots) after the dequeuing call. The dequeue also reads up to 4 × MAX_CONSOLIDATION_REQUESTS_PER_BLOCK queue data slots (from slot 4 onward), which appear as storage_reads.

Engine API

The Engine API is extended with new structures and methods to support block-level access lists:

ExecutionPayloadV4 extends ExecutionPayloadV3 with:

blockAccessList: RLP-encoded block access list

engine_newPayloadV5 validates execution payloads:

Accepts ExecutionPayloadV4 structure
Validates that computed access list matches provided blockAccessList
Returns INVALID if access list is malformed or doesn’t match

engine_getPayloadV6 builds execution payloads:

Returns ExecutionPayloadV4 structure
Collects all account accesses and state changes during transaction execution
Populates blockAccessList field with RLP-encoded access list

Block processing flow:

When processing a block:

The EL receives the BAL in the ExecutionPayload
The EL computes block_access_list_hash = keccak256(blockAccessList) and includes it in the block header
The EL executes the block and generates the actual BAL
If the generated BAL doesn’t match the provided BAL, the block is invalid (the hash in the header would be wrong)

The execution layer provides the RLP-encoded blockAccessList to the consensus layer via the Engine API. The consensus layer stores it as a field in the SSZ ExecutionPayload container. For long-term storage, the full blockAccessList bytes MAY be pruned and replaced by the field’s SSZ hash_tree_root, preserving the Merkle commitment within the ExecutionPayload tree.

Retrieval methods for historical BALs:

engine_getPayloadBodiesByHashV2: Returns ExecutionPayloadBodyV2 objects containing transactions, withdrawals, and blockAccessList
engine_getPayloadBodiesByRangeV2: Returns ExecutionPayloadBodyV2 objects containing transactions, withdrawals, and blockAccessList

The blockAccessList field contains the RLP-encoded BAL or null for pre-Amsterdam blocks or when data has been pruned.

The EL MUST retain BALs for at least the duration of the weak subjectivity period (=3533 epochs) to support synchronization with re-execution after being offline for less than the WSP.

State Transition Function

The state transition function must validate that the provided BAL matches the actual state accesses.

Implementation Note: The BAL itself does not need to enter the state transition function. Implementations MAY validate by generating a virtual BAL during execution, hashing it, and comparing against the block_access_list_hash in the header. This is the approach used in the execution-specs reference implementation.

def validate_block(execution_payload, block_header):
    # 1. Compute hash from received BAL and set in header
    block_header.block_access_list_hash = keccak(execution_payload.blockAccessList)
    
    # 2. Execute block and collect actual accesses
    actual_bal = execute_and_collect_accesses(execution_payload)
    
    # 3. Verify actual execution matches provided BAL
    # If this fails, the block is invalid (the hash in the header would be wrong)
    assert rlp.encode(actual_bal) == execution_payload.blockAccessList

def execute_and_collect_accesses(block):
    """Execute block and collect all state accesses into BAL format"""
    accesses = {}
    
    # Pre-execution system contracts (block_access_index = 0)
    track_system_contracts_pre(block, accesses, block_access_index=0)
    
    # Execute transactions (block_access_index = 1..n)
    for i, tx in enumerate(block.transactions):
        execute_transaction(tx)
        track_state_changes(tx, accesses, block_access_index=i+1)
    
    # Withdrawals and post-execution (block_access_index = len(txs) + 1)
    post_index = len(block.transactions) + 1
    for withdrawal in block.withdrawals:
        apply_withdrawal(withdrawal)
        track_balance_change(withdrawal.address, accesses, post_index)
    track_system_contracts_post(block, accesses, post_index)
    
    # Convert to BAL format and sort
    return build_bal(accesses)

def track_state_changes(tx, accesses, block_access_index):
    """Track all state changes from a transaction"""
    for addr in get_touched_addresses(tx):
        if addr not in accesses:
            accesses[addr] = {
                'storage_writes': {},  # slot -> [(index, value)]
                'storage_reads': set(),
                'balance_changes': [],
                'nonce_changes': [],
                'code_changes': []
            }
        
        # Track storage changes
        for slot, value in get_storage_writes(addr).items():
            if slot not in accesses[addr]['storage_writes']:
                accesses[addr]['storage_writes'][slot] = []
            accesses[addr]['storage_writes'][slot].append((block_access_index, value))
        
        # Track reads (slots accessed but not written)
        for slot in get_storage_reads(addr):
            if slot not in accesses[addr]['storage_writes']:
                accesses[addr]['storage_reads'].add(slot)
        
        # Track balance, nonce, code changes
        if balance_changed(addr):
            accesses[addr]['balance_changes'].append((block_access_index, get_balance(addr)))
        if nonce_changed(addr):
            accesses[addr]['nonce_changes'].append((block_access_index, get_nonce(addr)))
        if code_changed(addr):
            accesses[addr]['code_changes'].append((block_access_index, get_code(addr)))

def build_bal(accesses):
    """Convert collected accesses to BAL format"""
    bal = []
    for addr in sorted(accesses.keys()):  # Sort addresses lexicographically
        data = accesses[addr]
        
        # Format storage changes: [slot, [[index, value], ...]]
        storage_changes = [[slot, sorted(changes)] 
                          for slot, changes in sorted(data['storage_writes'].items())]
        
        # Account entry: [address, storage_changes, reads, balance_changes, nonce_changes, code_changes]
        bal.append([
            addr,
            storage_changes,
            sorted(list(data['storage_reads'])),
            sorted(data['balance_changes']),
            sorted(data['nonce_changes']),
            sorted(data['code_changes'])
        ])
    
    return bal

The BAL MUST be complete and accurate. Missing or spurious entries invalidate the block. Spurious entries MAY be detected by validating BAL indices, which MUST never be higher than len(transactions) + 1.

Clients MAY invalidate immediately if any transaction exceeds declared state.

Clients MUST store BALs separately from blocks and make them available via the engine API.

Concrete Example

Example block:

Pre-execution:

EIP-2935: Store parent hash at block hash contract (0x0000F90827F1C53a10cb7A02335B175320002935)
EIP-7002: Omitted for simplicity.

Transactions:

Alice (0xaaaa…) sends 1 ETH to Bob (0xbbbb…), checks balance of 0x2222…
Charlie (0xcccc…) calls factory (0xffff…) deploying contract at 0xdddd…

Post-execution:

Withdrawal of 100 ETH to Eve (0xabcd…)
EIP-7002 and EIP-7251 omitted for simplicity.

Note: Pre-execution system contract uses block_access_index = 0. Post-execution withdrawal uses block_access_index = 3 (len(transactions) + 1)

Resulting BAL (RLP structure):

[
    # Addresses are sorted lexicographically
    [ # AccountChanges for 0x0000F90827F1C53a10cb7A02335B175320002935 (Block hash contract)
        0x0000F90827F1C53a10cb7A02335B175320002935,
        [ # storage_changes
            [b'\x00...\x0f\xa0', [[0, b'...']]]  # slot, [[block_access_index, parent_hash]]
        ],
        [],  # storage_reads
        [],  # balance_changes
        [],  # nonce_changes
        []   # code_changes
    ],
    [ # AccountChanges for 0x2222... (Address checked by Alice)
        0x2222...,
        [],  # storage_changes
        [],  # storage_reads
        [],  # balance_changes (no change, just checked)
        [],  # nonce_changes
        []   # code_changes
    ],
    [ # AccountChanges for 0xaaaa... (Alice - sender tx 0)
        0xaaaa...,
        [],  # storage_changes
        [],  # storage_reads
        [[1, 0x...29a241a]],  # balance_changes: [[block_access_index, post_balance]]
        [[1, 10]],  # nonce_changes: [[block_access_index, new_nonce]]
        []  # code_changes
    ],
    [ # AccountChanges for 0xabcd... (Eve - withdrawal recipient)
        0xabcd...,
        [],  # storage_changes
        [],  # storage_reads
        [[3, 0x...5f5e100]],  # balance_changes: 100 ETH withdrawal
        [],  # nonce_changes
        []   # code_changes
    ],
    [ # AccountChanges for 0xbbbb... (Bob - recipient tx 0)
        0xbbbb...,
        [],  # storage_changes
        [],  # storage_reads
        [[1, 0x...b9aca00]],  # balance_changes: +1 ETH
        [],  # nonce_changes
        []   # code_changes
    ],
    [ # AccountChanges for 0xcccc... (Charlie - sender tx 1)
        0xcccc...,
        [],  # storage_changes
        [],  # storage_reads
        [[2, 0x...bc16d67]],  # balance_changes: after gas
        [[2, 5]],  # nonce_changes
        []  # code_changes
    ],
    [ # AccountChanges for 0xdddd... (Deployed contract)
        0xdddd...,
        [],  # storage_changes
        [],  # storage_reads
        [],  # balance_changes
        [[2, 1]],  # nonce_changes: new contract nonce
        [[2, b'\x60\x80\x60\x40...']]  # code_changes: deployed bytecode
    ],
    [ # AccountChanges for 0xeeee... (COINBASE)
        0xeeee...,
        [],  # storage_changes
        [],  # storage_reads
        [[1, 0x...05f5e1], [2, 0x...0bebc2]],  # balance_changes: after tx fees
        [],  # nonce_changes
        []   # code_changes
    ],
    [ # AccountChanges for 0xffff... (Factory contract)
        0xffff...,
        [ # storage_changes
            [b'\x00...\x01', [[2, b'\x00...\xdd\xdd...']]]  # slot 1, deployed address
        ],
        [],  # storage_reads
        [],  # balance_changes
        [[2, 5]],  # nonce_changes: after CREATE
        []  # code_changes
    ]
]

RLP-encoded and compressed: ~400-500 bytes.

Rationale

BAL Design Choice

This design variant was chosen for several key reasons:

Size vs parallelization: BALs include all accessed addresses (even unchanged) for complete parallel IO and execution.
Storage values for writes: Post-execution values enable state reconstruction during sync without individual proofs against state root.
Overhead analysis: Historical data shows ~90 KiB average BAL size.
Transaction independence: 60-80% of transactions access disjoint storage slots, enabling effective parallelization. The remaining 20-40% can be parallelized by having post-transaction state diffs.
RLP encoding: Native Ethereum encoding format, maintains compatibility with existing infrastructure.

BAL Size Considerations (60m block gas limit)

Average BAL size: ~92.1 KiB (compressed)

Storage writes: ~36.1 KiB (39.2%)
Storage reads: ~25.8 KiB (28.0%)
Balance diffs: ~9.2 KiB (10.0%)
Nonce diffs: ~1.9 KiB (2.1%)
Code diffs: ~1.4 KiB (1.5%)
Account addresses (with diffs): ~12.5 KiB (13.6%)
Touched-only addresses: ~3.3 KiB (3.6%)
RLP encoding overhead: ~1.8 KiB (1.9%)

Smaller than current worst-case calldata blocks.

An empirical analysis has been done here. An updated analysis for a 60 million block gas limit can be found here, and a refreshed one over more recent blocks (October 2026) here.

Asynchronous Validation

BAL verification occurs alongside parallel IO and EVM operations without delaying block processing.

Backwards Compatibility

This proposal requires changes to the block structure and engine API that are not backwards compatible and require a hard fork.

Security Considerations

Validation Overhead

Validating access lists and balance diffs adds validation overhead but is essential to prevent acceptance of invalid blocks.

Block Size

Increased block size impacts propagation but overhead (~70 KiB average) is reasonable for performance gains.

Spurious Storage Reads

Since storage_reads entries are not mapped to specific transaction indices, their validity can only be confirmed after executing all transactions. A malicious proposer could exploit this by declaring spurious storage reads that are never accessed, forcing clients into unnecessary I/O prefetching and data download while the block remains unrejectable until completion. The bal_items constraint bounds the number of such entries. Clients SHOULD additionally consider mechanisms to detect infeasible storage_reads during execution and reject the block before it completes. Any such mechanism MUST NOT reject a valid block; in particular, the storage reads performed by system calls are not paid for by block gas and cannot be bounded by it.

Copyright

Increase Maximum Contract Size

Mon, 09 Jun 2025 00:00:00 +0000

EIP #7954 - Increase Maximum Contract Size is in Last Call status. It is authored by Giulio Rebuffo (@Giulio2002), Ben Adams (@benaadams) and was originally created 2025-06-09. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/increase-maximum-contract-size-to-48kb/24509

Abstract

This EIP proposes to raise the maximum allowed size for contract code deployed on Ethereum from 24,576 bytes to 65,536 bytes, and to raise the initcode size limit from 49,152 bytes to 131,072 bytes.

Motivation

The current 24KiB contract size limit can be restrictive for complex contracts and applications. Increasing the limit to 64KiB allows for more feature-rich contracts while maintaining reasonable constraints on block and state growth.

Specification

Update the EIP-170 contract code size limit of 24KiB (0x6000 bytes) to 64KiB (0x10000 bytes).
Update the EIP-3860 initcode size limit of 48KiB (0xC000 bytes) to 128KiB (0x20000 bytes).

Rationale

Developer Flexibility: Enables more complex contracts and features.
Backward Compatibility: Existing contracts are unaffected.
Simplicity: Only the size limit is changed, with no other protocol modifications.

Backwards Compatibility

This change is not backwards compatible and must be activated via a network upgrade (hard fork). Contracts larger than 24KiB, up to 64KiB, will be deployable after activation.

Security Considerations

A higher contract size limit may marginally increase the risk of denial-of-service attacks via large contracts, but the new limit remains conservative.

Copyright

eth/70 - partial block receipt lists

Mon, 16 Jun 2025 00:00:00 +0000

EIP #7975 - eth/70 - partial block receipt lists is in Last Call status. It is authored by Felix Lange , Jochem Brouwer (@jochem-brouwer), Giulio Rebuffo (@Giulio2002) and was originally created 2025-06-16. It is in the Networking category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-7975-eth-70-partial-block-receipt-lists/24658

Abstract

This EIP modifies the ‘eth’ p2p protocol to allow requesting partial block receipt lists.

Motivation

As Ethereum moves toward a higher block gas limit on mainnet, the worst-case total size of a block receipts list also becomes larger, and may eventually exceed the 10MiB message size limit commonly applied in clients. This can lead to sync failures.

Specification

Modify the encoding for receipts in the Receipts (0x10) message as follows:

(eth/69): [request-id: P, [[receipt₁, receipt₂], ...]]
(eth/70): [request-id: P, lastBlockIncomplete: {0,1}, [[receipt₁, receipt₂], ...]]

If the lastBlockIncomplete flag is set to true (1), the last receipt list does not contain all receipts of the block, and the client will have to request the remaining receipts of that block in a new request.

To support such partial queries, we also modify the GetReceipts (0x0f) message:

(eth/69): [request-id: P, [blockhash₁: B_32, blockhash₂: B_32, ...]]
(eth/70): [request-id: P, firstBlockReceiptIndex: P, [blockhash₁: B_32, blockhash₂: B_32, ...]]

For the first block in the list of requested block hashes, the server shall omit receipts up to the firstBlockReceiptIndex from the response.

Downloading block receipts across multiple messages creates new attack surface. Partial receipt lists cannot be verified against the block header, so in responses with lastBlockIncomplete = 1, the last receipts list must be validated in a different way:

Verify the total number of delivered receipts matches the count of transactions.
Verify the size of each receipt against the gas limit of the corresponding transaction, i.e. reject if it is larger than gaslimit/8.
Verify the total downloaded receipts size is no larger than allowed by the block gas limit.

Rationale

Since EIP-7825 caps the gas limit of a single transaction to ~16.7M gas, a single transaction receipt will always be limited in size. Specifically, a transaction can produce at most 16777216/8 = 2MiB of log data.

However, a block can contain multiple transactions, and thus the entire block receipts list can be much larger. At a block gas limit of ~83M, the Receipts message could exceed 10MiB. Clients typically reject messages above this size because their validity can only be determined after fetching the complete message.

For a Receipts message, each block receipts list is validated by checking the full list against the tree root stored in the block header. When downloading a paginated list across multiple requests, the client must potentially buffer more than 10MB of unvalidated input. This cannot be avoided, since the protocol allows receipt lists of such size at a high block gas limit. However, we can at least bound the input size by applying sanity checks as recommended in the specification section.

Backwards Compatibility

This EIP changes the eth protocol and requires rolling out a new version, eth/70. Supporting multiple versions of a wire protocol is possible. Rolling out a new version does not break older clients immediately, since they can keep using protocol version eth/69.

This EIP does not change consensus rules of the EVM and does not require a hard fork.

Security Considerations

None

Copyright

Increase Calldata Floor Cost

Wed, 18 Jun 2025 00:00:00 +0000

EIP #7976 - Increase Calldata Floor Cost is in Last Call status. It is authored by Toni Wahrstätter (@nerolation) and was originally created 2025-06-18. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-7976-further-increase-calldata-cost/24597

Abstract

This EIP proposes an adjustment to calldata pricing by raising the floor cost from 10/40 to 64/64 gas per calldata byte. This reduces the worst-case block size by ~37% with minimal impact.

Motivation

While EIP-7623 successfully reduced the maximum possible block size by introducing a floor cost of 10/40 gas per byte for data-heavy transactions, continued increases in gas limit demands further optimization. The current floor cost still permits relatively large data-heavy payloads that contribute to block size variance. With 64/64 pricing, a 10 MiB uncompressed execution payload would require ~671M gas instead of ~105M gas under 10/40 pricing, providing significant headroom for gas limit increases.

By increasing the floor cost to 64/64 gas per byte, this proposal aims to:

Further reduce the maximum possible block size for data-heavy transactions
Create additional headroom for potential block gas limit increases
Maintain the same exemption for transactions with significant EVM computation
Have minimal impact on users

Specification

Parameter	Value
`STANDARD_TOKEN_COST`	`4`
`TOTAL_COST_FLOOR_PER_TOKEN`	`16`

Let tokens_in_calldata = zero_bytes_in_calldata + nonzero_bytes_in_calldata * 4.

Let floor_tokens_in_calldata = (zero_bytes_in_calldata + nonzero_bytes_in_calldata) * 4.

Equivalently, the floor cost is 64 gas per calldata byte (both zero and non-zero), since TOTAL_COST_FLOOR_PER_TOKEN * 4 = 64. The token abstraction is retained only for consistency with EIP-7623.

Let isContractCreation be a boolean indicating the respective event.

Let execution_gas_used be the gas used for EVM execution with the gas refund subtracted.

Let INITCODE_WORD_COST be 2 as defined in EIP-3860.

The formula for determining the gas used per transaction changes from EIP-7623’s implementation to:

tx.gasUsed = (
    21000
    +
    max(
        STANDARD_TOKEN_COST * tokens_in_calldata
        + execution_gas_used
        + isContractCreation * (32000 + INITCODE_WORD_COST * words(calldata)),
        TOTAL_COST_FLOOR_PER_TOKEN * floor_tokens_in_calldata
    )
)

Any transaction with a gas limit below 21000 + TOTAL_COST_FLOOR_PER_TOKEN * floor_tokens_in_calldata or below its intrinsic gas cost (take the maximum of these two calculations) is considered invalid. This limitation exists because transactions must cover the floor price of their calldata without relying on the execution of the transaction. There are valid cases where gasUsed will be below this floor price, but the floor price needs to be reserved in the transaction gas limit.

Rationale

With EIP-7623’s implementation, data-heavy transactions cost 10/40 gas per zero/non-zero byte, reducing the maximum possible EL payload size to approximately 1.07 MB (45_000_000/40). This EIP further reduces this to approximately 0.67 MB (45_000_000/64).

By increasing calldata costs from 10/40 to 64/64 gas per byte for data-heavy transactions, this EIP provides:

Enhanced block size reduction: Maximum data-heavy payload size drops by ~37%.
Maintained user experience: Regular users engaging in DeFi, token transfers, and other EVM-heavy operations remain unaffected
Better blob incentivization: Higher calldata costs further encourage migration to blob usage for data availability

The floor cost mechanism ensures that transactions involving significant EVM computation continue to pay the standard 4/16 gas per byte for calldata, preserving the user experience for regular Ethereum operations.

Analyzing the block range 20644414 - 23272414 (Sept. 2024 - Sept. 2025), 1.5% of all transactions would have been affected.

An empirical analysis summarizing the impact of this EIP can be found in this report.

Backwards Compatibility

This is a backwards incompatible gas repricing that requires a scheduled network upgrade.

Wallet developers and node operators MUST update gas estimation handling to accommodate the new calldata cost rules. Specifically:

Wallets: Wallets using eth_estimateGas MUST be updated to ensure that they correctly account for the updated TOTAL_COST_FLOOR_PER_TOKEN parameter of 16. Failure to do so could result in underestimating gas, leading to failed transactions.
Node Software: RPC methods such as eth_estimateGas MUST incorporate the updated formula for gas calculation with the new floor cost values.

Users can maintain their usual workflows without modification, as wallet and RPC updates will handle these changes.

Test Cases

Testing for this EIP should verify the correct application of the new calldata cost floor of 64/64 gas per byte:

Data-heavy transactions: Verify transactions with minimal EVM execution pay the floor cost of 64 gas per calldata byte
EVM-heavy transactions: Confirm transactions with significant computation continue using standard 4/16 gas per byte
Edge cases: Test transactions at the boundary where execution gas equals or exceeds the floor cost
Gas estimation: Validate that eth_estimateGas correctly accounts for the new TOTAL_COST_FLOOR_PER_TOKEN value
Invalid transactions: Ensure transactions with insufficient gas limits are properly rejected

Security Considerations

As the maximum possible block size is further reduced compared to EIP-7623, no additional security concerns are introduced beyond those already addressed in the original proposal.

The same transaction bundling considerations from EIP-7623 apply:

Transaction bundling was already possible and remains so
Bundling does not compromise the block size reduction objectives
Practical limitations (trust, coordination) continue to limit widespread bundling

The increased floor cost strengthens the incentive structure for appropriate data availability method selection without introducing new attack vectors.

Copyright

Increase Access List Cost

Fri, 27 Dec 2024 00:00:00 +0000

EIP #7981 - Increase Access List Cost is in Last Call status. It is authored by Toni Wahrstätter (@nerolation) and was originally created 2024-12-27. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-7981-increase-access-list-cost/24680

Abstract

This EIP charges access lists for their data footprint, preventing the circumvention of the EIP-7623 floor pricing. This effectively reduces the worst-case block size by ~21% with minimal impact on users.

Motivation

Access lists are only priced for storage but not for their data.

Furthermore, access lists can circumvent the EIP-7623 floor pricing by contributing to EVM gas while still leaving a non-negligible data footprint. This enables achieving the maximal possible block size by combining access lists with calldata at a certain ratio.

Specification

Parameter	Value	Source
`ACCESS_LIST_ADDRESS_COST`	`2400`	EIP-2930
`ACCESS_LIST_STORAGE_KEY_COST`	`1900`	EIP-2930
`TOTAL_COST_FLOOR_PER_TOKEN`	`16`	EIP-7976

Let access_list_bytes be the total byte count of addresses (20 bytes each) and storage keys (32 bytes each) in the access list.

Let access_list_data_cost = 64 * access_list_bytes (i.e. 1280 gas per address and 2048 gas per storage key). The 64 gas-per-byte rate matches the EIP-7976 calldata floor.

The access list data cost is added as a flat surcharge to the gas used calculation, leaving the EIP-2930 access_list_cost and the EIP-7976 floor calculation unchanged:

tx.gasUsed = (
    21000
    + access_list_data_cost
    +
    max(
        STANDARD_TOKEN_COST * tokens_in_calldata
        + execution_gas_used
        + isContractCreation * (32000 + INITCODE_WORD_COST * words(calldata))
        + access_list_cost,
        TOTAL_COST_FLOOR_PER_TOKEN * floor_tokens_in_calldata
    )
)

Any transaction with a gas limit below tx.gasUsed evaluated with execution_gas_used = 0 is considered invalid.

Rationale

Access list data is always charged at floor rate (added to access_list_cost), and access list tokens are included in the floor calculation. This ensures:

Access list data always pays floor rate regardless of execution level
Access lists cannot be used to bypass the calldata floor pricing
Consistent pricing across all transaction data sources

Backwards Compatibility

This is a backwards incompatible gas repricing that requires a scheduled network upgrade.

Requires updates to gas estimation in wallets and nodes. Normal usage patterns remain largely unaffected.

Reference Implementation

def calculate_access_list_data_cost(access_list):
    """EIP-7981: flat 64 gas per byte of access list data."""
    # Each access entry: 20-byte address + 32 bytes per storage key
    total_bytes = sum(20 + 32 * len(access.slots) for access in access_list)
    return total_bytes * 64


def calculate_intrinsic_cost(tx):
    """
    Calculate intrinsic gas cost and floor gas cost.
    Both include the EIP-7981 access list data surcharge, so that
    tx.gasUsed = max(intrinsic_gas + execution_gas_used, floor_gas).
    """
    # Calldata tokens (EIP-7976)
    zero_bytes = count_zero_bytes(tx.data)
    nonzero_bytes = len(tx.data) - zero_bytes
    tokens_in_calldata = zero_bytes + nonzero_bytes * 4
    floor_tokens_in_calldata = len(tx.data) * 4

    # Access list cost (EIP-2930, unchanged) and EIP-7981 data surcharge
    access_list_cost = 0
    access_list_data_cost = 0
    if has_access_list(tx):
        for access in tx.access_list:
            access_list_cost += (
                ACCESS_LIST_ADDRESS_COST
                + len(access.slots) * ACCESS_LIST_STORAGE_KEY_COST
            )
        access_list_data_cost = calculate_access_list_data_cost(tx.access_list)

    # EIP-7976 floor (calldata only) plus EIP-7981 surcharge
    floor_gas = (
        TX_BASE_COST
        + floor_tokens_in_calldata * TOTAL_COST_FLOOR_PER_TOKEN
        + access_list_data_cost
    )

    # Intrinsic gas plus EIP-7981 surcharge
    calldata_cost = tokens_in_calldata * STANDARD_TOKEN_COST
    create_cost = TX_CREATE_COST + init_code_cost(tx.data) if is_create(tx) else 0
    intrinsic_gas = (
        TX_BASE_COST
        + calldata_cost
        + create_cost
        + access_list_cost
        + access_list_data_cost
    )

    return intrinsic_gas, floor_gas

Security Considerations

This EIP closes a loophole that allows circumventing EIP-7623 floor pricing. Without this fix, attackers can achieve larger blocks than intended by combining access lists with calldata. All transaction data sources now contribute to the floor calculation consistently.

Copyright

Deterministic Factory Contract

Sun, 03 Aug 2025 00:00:00 +0000

EIP #7997 - Deterministic Factory Contract is in Last Call status. It is authored by Francisco Giordano (@frangio), Toni Wahrstätter (@nerolation), Nick Johnson (@Arachnid), Jochem Brouwer (@jochem-brouwer) and was originally created 2025-08-03. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-7997-deterministic-factory-predeploy/24998

Abstract

The availability of a well-known CREATE2 factory at 0x4e59b44847b379578588920cA78FbF26c0B4956C is made a formal requirement to enable deterministic deployments at identical addresses across EVM chains. This benefits developer experience, user experience, and security, in particular for multi-chain and cross-chain applications, including account abstraction.

Motivation

There are now a large number of EVM chains where users want to transact and developers want to deploy applications, and we can expect this number to continue to grow in line with Ethereum’s rollup-centric roadmap and the general adoption of programmable blockchains. Most applications support multiple chains and aspire to support as many as possible, and their developers widely prefer to deploy contracts at identical addresses across all chains as a multi-chain deterministic deployment. This kind of deployment reduces the number of addresses that must be distributed to use the application, so that it no longer scales with the number of supported chains. This simplification has many benefits throughout the stack: interfaces and SDKs need to embed and trust fewer addresses, and other contracts that depend on them can be implemented without chain-specific customization (which in turn makes them amenable to multi-chain deployment).

This kind of deployment is also highly desirable and important for account abstraction. Without it, a user’s smart contract accounts are deployed at different addresses on different chains, and each account is tied to a single chain. This limitation is difficult to explain to users and has caused loss of funds. If smart contract accounts cannot be multi-chain like EOAs, they offer downgraded UX and are more prone to error.

There is currently no native or fully robust way to perform multi-chain deterministic deployments. While CREATE2 enables deterministic deployments, the created address is computed from that of the contract that invokes the instruction, so a factory that is itself multi-chain is required for bootstrapping. Four workarounds are currently known to deploy such a factory:

A keyless transaction crafted using Nick’s method that can be posted permissionlessly to new chains.
Private keys held by some party used to sign creation transactions for each chain as needed.
A private key intentionally leaked so that any party can permissionlessly create an EIP-7702 signed delegation and deploy a factory from the leaked account.
Factories already deployed on other chains (by any of the previous methods) inserted in a new chain at genesis or via a hard fork.

Keyless transactions have been the most successful approach. However, since such transactions have a fixed gas price and limit, they have often been impossible to deploy on chains where those gas parameters are insufficient or invalid. The same issue has begun to affect Ethereum itself and its devnets due to changes to the gas schedule. This EIP formalizes the guarantee that an already widely used keyless CREATE2 factory should be available on EVM chains, whether deployed by an ordinary transaction (including its keyless transaction), or included in genesis.

Specification

FACTORY_ADDRESS = 0x4e59b44847b379578588920cA78FbF26c0B4956C

The chain’s state MUST include FACTORY_ADDRESS with nonzero nonce and this runtime code:

0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe03601600081602082378035828234f58015156039578182fd5b8082525050506014600cf3

A chain may satisfy this requirement by either of the following means that results in the account above: deploying the factory with an ordinary transaction (for example, its keyless creation transaction) where the chain’s gas parameters permit it, or including the account in the genesis state with a nonce equal to 1. Regardless of the method used, the resulting FACTORY_ADDRESS account MUST have the runtime code specified above. If the chain is already running with gas parameters that no longer allow deployment via the keyless transaction, the only way to add the contract at the expected address is a coordinated irregular state transition, which is outside the scope of this EIP. Client software MUST NOT check for the existence of the contract at the fork boundary.

This is a contract that invokes the CREATE2 instruction (EIP-1014) with a salt equal to the first 32 bytes of the call’s input data, init code equal to the remaining data, and value equal to the call’s value. If input data is smaller than 32 bytes, the contract will attempt to copy close to 2^256 bytes of calldata and should revert as a result. If contract creation fails (CREATE2 outputs 0), the call reverts with empty return data. When successful, the address is returned in exactly 20 bytes of data with no padding.

The above runtime bytecode disassembles to the following:

push32 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe0
calldatasize
add

push1 0x00
dup2
push1 0x20
dup3
calldatacopy

dup1
calldataload

dup3
dup3
callvalue
create2
dup1
iszero
iszero
push1 0x39
jumpi

dup2
dup3
revert

jumpdest
dup1
dup3
mstore
pop
pop
pop
push1 0x14
push1 0x0c
return

Rationale

Choice of factory

The factory at 0x4e59b44847b379578588920cA78FbF26c0B4956C has been used close to 25000 times on Ethereum Mainnet, deployed to hundreds of chains using its keyless transaction, included in multiple L2s by default, and used as the default factory for deterministic deployments in developer tools.

The bytecode is compatible with any EVM chain that has activated EIP-1014, which Ethereum included in Constantinople. In particular, it does not depend on the more recent PUSH0 (EIP-3855).

Two known downsides of this factory were considered. First, the address of the created account is returned with no padding, and may need to be decoded differently to other address-returning calls. Second, returndata is not propagated in case of revert, and an EVM trace may be required for obtaining a diagnostic error message. Both issues were considered non-blocking due to the existence of workarounds, including the possibility of using this factory to deploy further improved factories. Notably, if such factories are fully deterministic and permissionlessly deployable (and only require baseline EVM features), they are guaranteed to exist or be deployable at the same address on the same set of chains.

Backwards Compatibility

No backwards compatibility issues are introduced. On chains that already have the factory at FACTORY_ADDRESS (Ethereum Mainnet and most others), satisfying this requirement is a no-op. No other contract is expected at this address.

Security Considerations

Frontrunnable deployments

The deployment of contracts that read the environment (ORIGIN, NUMBER, etc.) may be frontrun and created with attacker-chosen parameters. It’s recommended to use this factory to deploy fully deterministic contracts only.

Copyright

Backward compatible SWAPN, DUPN, EXCHANGE

Sat, 16 Aug 2025 00:00:00 +0000

EIP #8024 - Backward compatible SWAPN, DUPN, EXCHANGE is in Last Call status. It is authored by Francisco Giordano (@frangio), Charles Cooper (@charles-cooper), Alex Beregszaszi (@axic), Paweł Bylica (@chfast) and was originally created 2025-08-16. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-8024-backward-compatible-swapn-dupn-exchange/25486

Abstract

Currently, SWAP* and DUP* instructions are limited to a stack depth of 16. Introduce three new instructions, SWAPN, DUPN and EXCHANGE which lift this limitation and allow accessing the stack at higher depths.

Motivation

While the stack is 1024 items deep, easy access is only possible for the top 16 items. Supporting more local variables is possible via manually keeping them in memory or through a “stack to memory elevation” in a compiler. This can result in complex and inefficient code.

Furthermore, implementing higher level constructs, such as functions, on top of EVM will result in a list of input and output parameters as well as an instruction offset to return to.

The number of these arguments (or stack items) can easily exceed 16 and thus will require extra care from a compiler to lay them out in a way that all of them are still accessible.

Lastly, swapping items besides the 1st and Nth items in the stack is very important for compilers implementing stack scheduling algorithms (the analog of register allocation for stack machines), which try to minimize stack traffic given a set of variables and usage analysis.

Introducing SWAPN, DUPN, and EXCHANGE will provide an option to compilers to simplify accessing deep stack items.

Specification

We introduce three new instructions:

DUPN (0xe6)
SWAPN (0xe7)
EXCHANGE (0xe8)

Each instruction carries one or two immediate operands. Informally, using 1-based indexing, the semantics are:

DUPN n: The n‘th stack item is duplicated at the top of the stack.
SWAPN n: The n + 1‘th stack item is swapped with the top of the stack.
EXCHANGE n m: The n + 1‘th stack item is swapped with the m + 1‘th stack item.

Formally, when code[pc] is one of these opcodes, the VM executes as follows:

DUPN:
1. Charge 3 gas.
2. Let x = code[pc + 1].
3. If 90 < x < 128, halt with exceptional failure.
4. Let n = decode_single(x).
5. If n > len(stack), halt with exceptional failure.
6. Push stack[top - n + 1] on the stack.
7. Set pc = pc + 2.
SWAPN:
1. Charge 3 gas.
2. Let x = code[pc + 1].
3. If 90 < x < 128, halt with exceptional failure.
4. Let n = decode_single(x).
5. If n + 1 > len(stack), halt with exceptional failure.
6. Swap stack[top - n] and stack[top].
7. Set pc = pc + 2.
EXCHANGE:
1. Charge 3 gas.
2. Let x = code[pc + 1].
3. If 81 < x < 128, halt with exceptional failure.
4. Let n, m = decode_pair(x).
5. If m + 1 > len(stack), halt with exceptional failure.
6. Swap stack[top - n] and stack[top - m].
7. Set pc = pc + 2.

code[pc + 1] evaluates to 0 if beyond the end of the code, matching PUSH behavior.

top denotes the index of the value at the top of the stack.

JUMPDEST analysis is unchanged. In particular, if code[i] is at an instruction boundary and is one of these opcodes, and code[i + 1] is 0x5b (JUMPDEST), then code[i + 1] is a valid jump target. Note that in this case the execution of code[i] would halt at step 2 above (because x = code[i + 1] = 0x5b = 91). Disassemblers must decode such code[i] as INVALID (or INVALID_DUPN, etc.) and code[i + 1] as JUMPDEST.

The auxiliary functions decode_single and decode_pair are defined by the following Python code:

def decode_single(x: int) -> int:
    """Returns n with 17 <= n <= 235."""
    assert 0 <= x <= 90 or 128 <= x <= 255
    return (x + 145) % 256

def decode_pair(x: int) -> tuple[int, int]:
    """Returns (n, m) with 1 <= n <= 14 and n < m <= 30 - n."""
    assert 0 <= x <= 81 or 128 <= x <= 255
    k = x ^ 143
    q, r = divmod(k, 16)
    if q < r:
        return q + 1, r + 1
    else:
        return r + 1, 29 - q

Assemblers and compilers must emit a 1-byte immediate after each of these opcodes that decodes to the required n, m operands. For reference, this can be done by encode_single and encode_pair:

def encode_single(n: int) -> int:
    assert 17 <= n <= 235
    return (n + 111) % 256

def encode_pair(n: int, m: int) -> int:
    assert 1 <= n < m and n + m <= 30
    if m <= 16:
        q, r = n - 1, m - 1
    else:
        q, r = 29 - m, n - 1
    k = 16 * q + r
    return k ^ 143

Rationale

Use of an immediate operand

Allowing dynamic selection of the arguments to swap or dup could be used to prevent static analysis of the contents of the stack. Since static analysis is an important tool for security auditors we want to do what we can to make their jobs easier. Hence, the operands require an immediate operand that is not dynamic in nature.

Disallowed immediate range

A property the EVM has is that it’s not possible to jump to the middle of an instruction. In order to guarantee this property, the immediate operands of PUSH* instructions are masked from jumpdest analysis so that the occurrence of 0x5b in them is not mistaken for a JUMPDEST instruction, which should be considered a valid jump target elsewhere.

The new instructions in this EIP preserve this property without changing jumpdest analysis by making it invalid for their immediates to contain 0x5b, in addition to 0x60 to 0x7f (PUSH1 to PUSH32) since those would cause the subsequent instructions to be masked.

The alternative, changing jumpdest analysis to introduce new masked opcodes, would create a backwards incompatibility if done without bytecode versioning (EOF). Consider the bytecode sequence e6 5b that decodes to INVALID JUMPDEST prior to this EIP, and thus contains a valid jump target. If an instruction DUPN x were introduced with encoding e6 {x} (opcode immediately followed by operand), and jumpdest analysis changed to mask the operand to e6, the same bytecode sequence e6 5b would then decode to DUPN 0x5b. As a result of the upgrade, 5b would become an invalid jump target, breaking contracts that include this sequence. The opposite can happen with push opcodes, for example, e6 60 5b would transform from INVALID PUSH1 0x5b to DUPN 0x60 JUMPDEST, creating a new valid jump target. Furthermore, this may have a cascading effect on arbitrarily many subsequent instructions.

Since the EVM doesn’t offer a dedicated section for data, arbitrary data may be embedded in code and serve as immutable data storage accessed via CODECOPY. Therefore, we must assume that arbitrary byte sequences may be found in contracts that have been deployed or are included in transactions yet to be published on chain.

This EIP is designed to uphold the following backwards compatibility guarantee: every possible execution trace on a given bytecode that does not attempt to execute an undefined opcode must continue to produce the same effect after the introduction of an instruction. No new JUMPDESTs must be created in a given bytecode by the introduction of an instruction and none may be removed.

This encoding can be reused in future instructions with immediate operands, although it is not necessary if the range of the operand naturally does not include the bytes 0x5b (JUMPDEST) or 0x60 (PUSH1) to 0x7f (PUSH32), in which case masking is not necessary.

`EXCHANGE` immediate

A previous formulation of EXCHANGE allowed swapping stack elements only if they were within some distance. As a result, it would be possible to swap the elements at indices 30 and 29, but not possible to move an element from index 30 to 2 with a single instruction. The current formulation prioritizes the latter, on the assumption that it is more valuable to move elements closer to the top of the stack than it is to rearrange elements deeper in the stack.

In addition, the exact formulation was chosen to make decode_pair a simple function using only basic arithmetic, bitwise operations (division by 16), and few branches. A small trade-off in the number of addressable pairs was made to reduce the number of necessary branches; this implies some of the immediate range is not allocated, and it could be used to add a dozen more addressable pairs at the cost of more decoding complexity, potentially in a future network upgrade.

Finally, note that the operands in the assembly instruction EXCHANGE n m appear “off by one”, i.e. it operates on the stack elements at depths n + 1 and m + 1. These offsets were chosen to match the SWAP and SWAPN opcodes such that EXCHANGE n m has an effect equivalent to the sequence SWAP{n} SWAP{m} SWAP{n}.

Size of immediate operand

For DUPN and SWAPN a 16-bit size was considered to accommodate the full stack space of 1024 items, however:

that would require an additional restriction/check (n < 1024)
the 256 depth is a large improvement over the current 16 and the overhead of an extra byte would make it less useful

Similarly for EXCHANGE, the proposed scheme allows addressing of 30 items.

Gas cost

The gas cost for these operations is the same as for existing DUP* and SWAP* instructions, because they are just implemented as pointer swaps and immediate decoding is negligible.

`EXCHANGE` vs `SWAPN`

As mentioned before, EXCHANGE is important to compilers implementing stack scheduling algorithms. Specifically, in the case that a stack item is scheduled to be consumed deeper in the stack (for instance, the 3rd item in the stack needs to be moved into 2nd position in order to be consumed by the next operation), that currently takes three instructions, SWAP2 SWAP3 SWAP2. However, in the EVM implementation, the implementation is just a pointer swap, so it could be implemented in a single instruction at no extra runtime cost to the client.

Backwards Compatibility

This has no effect on contracts that would never attempt to execute the opcodes allocated by this EIP. The jump targets of existing contracts are preserved.

Test Cases

Assembly/Disassembly

e680 is [DUPN 17]
e7db is [SWAPN 108]
e6805b is [DUPN 17, JUMPDEST]
e75b is [INVALID_SWAPN, JUMPDEST]
e6605b is [INVALID_DUPN, PUSH1 0x5b]
e7610000 is [INVALID_SWAPN, PUSH2 0x0000]
e65f is [INVALID_DUPN, PUSH0]
e89d is [EXCHANGE 2 3]
e82f is [EXCHANGE 1 19]
e850 is [EXCHANGE 14 16]
e851 is [EXCHANGE 14 15]
e852 is [INVALID_EXCHANGE, MSTORE]

Execution

60016000808080808080808080808080808080e680 results in 18 stack items, the top of the stack valued 1, the bottom of the stack valued 1, the rest valued 0
600160008080808080808080808080808080806002e780 results in 18 stack items, the top of the stack valued 1, the bottom of the stack valued 2, the rest valued 0
600260008080808080600160008080808080808080e8 at the end of code results in 17 stack items, the bottom of the stack valued 1, the 10th stack item from the top valued 2, the rest valued 0
600060016002e88e results in 3 stack items, from top to bottom: [2, 0, 1]
600080808080808080808080808080808080808080808080808080808060016002e88f results in 30 stack items, the top of the stack valued 2, the bottom of the stack valued 1, the rest valued 0
e75b reverts
600456e65b executes successfully (PUSH 04 JUMP INVALID_DUPN JUMPDEST)
60008080e88e15 results in 3 stack items, the top of the stack valued 1, the rest valued 0
e852 reverts
6000808080808080808080808080808080e680 results in exceptional halt

Security Considerations

The authors are not aware of any additional risks introduced here. The EVM stack is fixed at 1024 items and most implementations keep that in memory at all times. This change will increase the number of stack items accessible via single instruction.

Copyright

State Creation Gas Cost Increase

Wed, 01 Oct 2025 00:00:00 +0000

EIP #8037 - State Creation Gas Cost Increase is in Last Call status. It is authored by Maria Silva (@misilva73), Carlos Perez (@CPerezz), Jochem Brouwer (@jochem-brouwer), Ansgar Dietrichs (@adietrichs), Łukasz Rozmej (@LukaszRozmej), Anders Elowsson (@anderselowsson), Francesco D'Amato (@fradamt), Dragan Rakita (@rakita), Paweł Bylica (@chfast), Spencer Taylor-Brown (@spencer-tb), Gary Rong (@rjl493456442) and was originally created 2025-10-01. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-8037-state-creation-gas-cost-increase/25694

Abstract

This proposal increases the cost of state creation operations, thus avoiding excessive state growth under increased block gas limits. It introduces a new variable, CPSB (cost per state byte), and sets this unit of gas costs per new state byte by targeting an average state growth of 120 GiB per year at a reference block gas limit of 150M gas units. It also introduces an independent metering for state creation costs, thus allowing for increased throughput and for larger contract deployments without being limited by the single transaction gas limit.

Motivation

State creation does not have a harmonized cost, with different methods incurring varied costs for creating the same size of new state. For instance, while contract deployment only costs ~200 gas units per new byte created, new storage slots cost ~313 gas units per new byte created. Also, deploying duplicated bytecode costs the same as deploying new bytecode, even though clients don’t store duplicated code in the database. This proposal establishes a standard to harmonize all state creation operations.

Additionally, state growth will become a bottleneck for scaling under higher block limits. As of January 2026, the current database size in a Geth node dedicated to state is ~390 GiB. After the increase in gas limit from 30M to 60M gas units, the average size of new state created each day more than tripled, from ~105 MiB to ~326 MiB. This results in an annual growth of ~116 GiB.

The state-growth response we observe is not linear in the gas limit increase: a 2× bump (30M → 60M) produced a roughly 3× jump in daily new state, suggesting a one-off shift in user behavior rather than a steady-state ratio. Treating the post-bump rate as the new baseline and extrapolating proportionally to the new gas limit, at a 200M gas limit, the state would grow at a rate of ~387 GiB per year. Starting from 390 GiB, this rate would breach the 650 GiB threshold (at which point nodes begin experiencing performance degradation) in less than a year.

Specification

New parameters

Parameter	Value
`CPSB`	1530
`STATE_BYTES_PER_STORAGE_SET`	64
`STATE_BYTES_PER_NEW_ACCOUNT`	120
`STATE_BYTES_PER_AUTH_BASE`	23
`SYSTEM_MAX_SSTORES_PER_CALL`	16
`TX_MAX_TOTAL_GAS_LIMIT`	4,294,967,295 (2^32 - 1)

Parameter changes

Upon activation of this EIP, the following parameters of the gas model are updated. The “New State Gas” column shows the state gas cost (charged to the state-gas dimension), while the “New Execution Gas” column shows additional execution gas costs that accompany the state gas charge.

Parameter	Current	New State Gas	New Execution Gas	Operations affected
`GAS_CREATE`	32,000	`STATE_BYTES_PER_NEW_ACCOUNT x CPSB`	`CREATE_ACCESS`	`CREATE`, `CREATE2`
`GAS_CODE_DEPOSIT`	200/byte	`CPSB` per byte	`6 × ceil(len/32)` (hash cost)	`CREATE`, `CREATE2`
`GAS_NEW_ACCOUNT`	25,000	`STATE_BYTES_PER_NEW_ACCOUNT x CPSB`	0	`CALL`, `SELFDESTRUCT`
`GAS_STORAGE_SET`	20,000	`STATE_BYTES_PER_STORAGE_SET x CPSB`	0	`SSTORE`
`PER_EMPTY_ACCOUNT_COST`	25,000	`STATE_BYTES_PER_NEW_ACCOUNT x CPSB`	`ACCOUNT_WRITE`	EOA delegation
`PER_AUTH_BASE_COST`	12,500	`STATE_BYTES_PER_AUTH_BASE x CPSB`	`EXECUTION_PER_AUTH_BASE_COST`	EOA delegation

The EXECUTION_PER_AUTH_BASE_COST is defined as the sum of:

Calldata cost: 1,616 (101 bytes × 16), where 101 is the byte size of an EIP-7702 authorization tuple (chain_id 8 + address 20 + nonce 8 + y_parity 1 + r 32 + s 32). This is a representative size, not a worst case, since chain_id is a uint256 and may exceed 8 bytes.
Recovering authority address (ecRecover): PRECOMPILE_ECRECOVER
Reading nonce and code of authority (cold access): COLD_ACCOUNT_ACCESS (is updated by EIP-8038)
Storing values in an already warm account: 2 x WARM_ACCESS

COLD_ACCOUNT_ACCESS, ACCOUNT_WRITE and CREATE_ACCESS are defined and updated in EIP-8038. The values are not yet final.

Multidimensional metering for state creation costs

Besides the parameter changes, this proposal introduces an independent metering for state creation costs. Two gas dimensions are introduced, execution-gas and state-gas. For state creation operations, the “new state costs” are charged to state-gas, while the “new execution costs” are charged to execution-gas. The costs of all other operations are charged to execution-gas.

At transaction level, the user pays for both execution-gas and state-gas. The total gas cost of a transaction is the sum of both dimensions. In addition, the transaction gas limit set in EIP-7825 only applies to execution-gas, while state-gas is capped by tx.gas, which this proposal in turn caps at TX_MAX_TOTAL_GAS_LIMIT.

At the block level, only the gas used in the bottleneck resource is considered when checking if the block is full and when updating the base fee for the next block. This gives a new meaning to the block’s gas limit and the block’s gas target: each now bounds the bottleneck resource (the dimension with the highest cumulative gas used) rather than a single combined gas counter.

Transaction validation

Before transaction execution, inclusion of a transaction in a block requires that:

The transaction’s gas limit is not higher than TX_MAX_TOTAL_GAS_LIMIT. Concretely, tx.gas <= TX_MAX_TOTAL_GAS_LIMIT. Unlike EIP-7825’s TX_MAX_GAS_LIMIT, which this proposal applies to execution-gas only, this bound applies to tx.gas as a whole and therefore to the sum of both dimensions.
The transaction’s intrinsic gas is not higher than EIP-7825’s transaction cap. Concretely, max(intrinsic_gas, calldata_floor_gas_cost) <= TX_MAX_GAS_LIMIT. Under EIP-2780, intrinsic_gas is state-independent and charged entirely in execution-gas; there is no intrinsic state-gas component.
For each gas dimension, the cumulative gas used of all previous transactions added to the transaction’s contribution does not exceed the block gas limit. Concretely, min(TX_MAX_GAS_LIMIT, tx.gas) <= execution_gas_available and tx.gas <= state_gas_available, where execution_gas_available = block_env.block_gas_limit - block_output.block_execution_gas_used and state_gas_available = block_env.block_gas_limit - block_output.block_state_gas_used.

This check is performed before transaction inclusion in a block.

intrinsic_gas is the state-independent intrinsic cost defined by EIP-2780, charged entirely in execution-gas (base transaction cost, calldata, access lists, the recipient touch, value costs, and per-authorization base costs). It is the sole input to the transaction-validity check.

All state-dependent charges — new account creation and EIP-7702 delegation costs — are no longer part of intrinsic gas. Per EIP-2780, they are runtime charges applied in the pre-execution phase, after the transaction is deemed valid but before the first EVM frame is entered.

Transaction-level gas accounting (reservoir model)

Since transactions have a single gas limit parameter (tx.gas), gas accounting is enforced through a reservoir model. The gas is split into gas_left and state_gas_reservoir, and all gas counters are initialized, during the pre-execution phase defined by EIP-2780. This phase occurs after the transaction has passed the intrinsic gas check but before the first EVM frame is entered.

This EIP defines how the split and the counters are computed. The remaining accounting rules of the pre-execution phase (authorization processing, recipient warming, and the runtime account-creation and access charges) is specified in EIP-2780.

gas_left and state_gas_reservoir are initialized as follows:

evm_gas = tx.gas - intrinsic_gas
execution_gas_budget = TX_MAX_GAS_LIMIT - intrinsic_gas
gas_left = min(execution_gas_budget, evm_gas)
state_gas_reservoir = evm_gas - gas_left

Because EIP-2780 makes intrinsic gas state-independent, no state-gas component is subtracted from tx.gas here and none is seeded into the reservoir. The state-dependent costs are applied as runtime charges — later in the pre-execution phase and during execution — drawing from state_gas_reservoir first and from gas_left once the reservoir is exhausted.

This means that the state_gas_reservoir holds gas that exceeds EIP-7825’s budget. Additionally, four new counters are introduced:

evm_state_gas_used encodes the total state-gas used by the transaction, and it is initialized as evm_state_gas_used = 0.
state_gas_from_gas_left encodes how much of the current frame’s gas_left has been drawn for state-gas charges and not yet credited back (i.e., the state-gas not covered by the reservoir). Like gas_left, it is frame-local: it is initialized to 0 at the start of each call frame and is used to refill state-gas in last-in, first-out (LIFO) order.
state_gas_baseline records the value of state_gas_reservoir at the start of the state changes a frame’s rollback undoes, which for a call frame is its entry. Like gas_left, it is frame-local.
state_gas_committed records the part of state_gas_from_gas_left that a frame’s rollback must not credit back to gas_left, because the state it paid for is not rolled back. Like gas_left, it is frame-local. Only the top-level frame uses it; in other frames it is always 0.

The gas counters operate as follows:

Execution-gas charges deduct from gas_left only.
State-gas charges deduct from state_gas_reservoir first. When the reservoir is exhausted, the remainder deducts from gas_left and increments state_gas_from_gas_left by that remainder. State-gas charges increment evm_state_gas_used.
If a state creation is undone during execution, the corresponding amount of state-gas is refilled in last-in, first-out (LIFO) order: because charges deduct from state_gas_reservoir first and from gas_left last, refills credit the pool charged last (gas_left) first. It is credited to gas_left first (decrementing state_gas_from_gas_left by the same amount) up to the current value of state_gas_from_gas_left, and any remainder is credited to state_gas_reservoir. State-gas refills decrement evm_state_gas_used. Throughout this specification, “refilling state-gas” refers to this LIFO operation.
state_gas_reservoir is passed to a child frame in full: the 63/64 rule applies to gas_left only. The parent keeps none of it while the child runs. On the child’s exit it becomes the parent’s again. Note: a refill in the child may have raised it above the amount passed in.
The GAS opcode returns gas_left only (excluding the reservoir).
State-gas is metered at the end of all state-mutating opcodes, call-frame boundaries (in case of exceptional halts and reverts) and at the end of the transaction.

Gas accounting for SSTORE (opcode-level)

Original value	Current value	New value	Description	State-gas charges/refills
0	x	0	Cleared slot, zero at transaction start	`STATE_BYTES_PER_STORAGE_SET × CPSB` refilled
0	0	x	New slot	`STATE_BYTES_PER_STORAGE_SET × CPSB` charged
x	x	0	Cleared slot, non-zero at transaction start	no state-gas adjustments
x	0	x	Cleared slot restored to its original non-zero value	no state-gas adjustments
x or 0	y	z	All other writes to an existing slot	no state-gas adjustments

State-gas accounting for SSTORE is performed at the end of the opcode execution.

Gas accounting for new accounts

Operation	State-gas charges/refills
`CALL*` with value to non-existent account	`STATE_BYTES_PER_NEW_ACCOUNT × CPSB` charged
`CREATE`/`CREATE2` with bytecode size of `L` to existent account	`L × CPSB` charged
`CREATE`/`CREATE2` with bytecode size of `L` to non-existent account	`(STATE_BYTES_PER_NEW_ACCOUNT + L) × CPSB` charged
`SELFDESTRUCT` where balance transfer creates a new account	`STATE_BYTES_PER_NEW_ACCOUNT × CPSB` charged

Here, an account is existent if it already has a leaf in the state trie, i.e., it has a nonzero balance, a nonzero nonce, or non-empty code (per EIP-161).

In particular, an address that holds a balance but has no code and a zero nonce is existent and is a valid CREATE/CREATE2 target under EIP-684. Creating a contract at such an address updates the existing leaf rather than adding a new one, so only the code-deposit cost (L × CPSB) applies and the STATE_BYTES_PER_NEW_ACCOUNT × CPSB account-creation charge does not.

State-gas accounting for CALL* and CREATE/CREATE2 operations is performed right before the respective call frame. In both families the STATE_BYTES_PER_NEW_ACCOUNT × CPSB account-creation charge is applied conditionally: only when the operation is about to create a new account. The families differ only in when the destination account may be read, which EIP-7928 constrains (see Account-creation charging and EIP-7928).

CALL* family (conditional charge). The STATE_BYTES_PER_NEW_ACCOUNT × CPSB account-creation charge is applied conditionally right before entering the child frame: only when the target account does not exist and a positive value is transferred. If the operation is unsuccessful before entering the call frame (e.g., due to insufficient balance or due to the stack depth), or if the child frame reverts or halts exceptionally, the charged state-gas is refilled in LIFO order and evm_state_gas_used decreases by the same amount.

CREATE/CREATE2 family (conditional charge). EIP-7928 defers reading the computed destination address until creation has passed the checks that precede any state access: sender balance for the endowment, nonce overflow, and the call-stack depth limit. A creation failing those checks never reads the destination, and no account-creation state-gas is charged. Once the checks pass, the destination is accessed — a single read that also performs the EIP-684 collision check:

If the destination is non-existent (per the existence rule above), STATE_BYTES_PER_NEW_ACCOUNT × CPSB is charged in the creating frame, before 63/64 of the remaining gas is forwarded: a portion drawn from gas_left reduces the gas forwarded to the create frame, and a failed charge exceptionally halts the creating frame — exactly as for CALL*. If the destination pre-exists (e.g., it holds a balance), nothing is charged. The charge is decided by existence alone, independently of the collision outcome below.
On an address collision (EIP-684) the creation fails as an exceptional halt of the create frame, consuming the forwarded gas. A colliding destination has a nonzero nonce or non-empty code, so it is existent and no account-creation state-gas was charged. A nonzero balance or non-empty storage alone does not cause a collision.
If the create frame reverts or halts exceptionally (including an address collision and a failed code deposit), the account creation is rolled back and any charged account-creation state-gas is refilled in LIFO order, decreasing evm_state_gas_used by the same amount — exactly as for CALL*.

The code-deposit portion (L × CPSB) is unaffected by this rule and is charged at code-deposit time as usual.

The same conditional rule applies to top-level contract-creation transactions. Under EIP-2780 the STATE_BYTES_PER_NEW_ACCOUNT × CPSB account-creation charge is not part of intrinsic gas and is not reserved up front; it is applied as a runtime charge in the pre-execution phase, when transaction setup accesses the deployment address (an access EIP-7928 always records), only if the destination does not already exist. Like any other state charge, it draws from state_gas_reservoir first and from gas_left once the reservoir is exhausted. If the transaction reverts or halts (including an address collision), any charged portion is undone by the frame’s rollback, and the unspent reservoir is returned to the sender by the normal end-of-transaction settlement.

Charges for account creation with SELFDESTRUCT are charged at the point where it executes.

Gas refills for `SELFDESTRUCT`

SELFDESTRUCT for accounts created in the same transaction does not produce increases in state size as the account, its data and its storage is not included in the state trie. However, this operation does not produce any state-gas refills and there are no changes to evm_state_gas_used.

For an account that existed before the transaction, SELFDESTRUCT only transfers its balance and the account is not removed. Thus, no state-gas refill applies and no changes to evm_state_gas_used. This is consistent with the behavior of EIP-6780.

Gas accounting for halts and reverts

A call frame’s state changes are rolled back on both reverts and exceptional halts. In both cases the frame’s state-gas is restored to its baseline rather than refilled:

net_state_gas = state_gas_baseline - state_gas_reservoir + state_gas_from_gas_left
evm_state_gas_used -= net_state_gas
gas_left += state_gas_from_gas_left
state_gas_from_gas_left = 0
state_gas_reservoir = state_gas_baseline

net_state_gas is negative for a frame that refilled more than it charged, so evm_state_gas_used increases: the rollback also restores the state whose removal the refill credited. The restore assigns state_gas_reservoir where a refill credits it, so it is applied before any refill its parent makes for the failed operation. The two cases differ only in how the frame’s gas_left is treated, exactly as in existing EVM semantics.

Only the top-level frame can have a baseline that is not its entry, and only when the transaction has EIP-7702 authorizations. Its rollback does not undo the authorizations applied in the pre-execution phase (EIP-2780), so the state-gas charged for them must not be refilled. The baseline is taken after the authorization charges and before the account-creation charge for the transaction’s target, so that charge is refilled. At this point the frame commits the state-gas charged so far:

state_gas_committed += state_gas_from_gas_left
state_gas_baseline = state_gas_reservoir
state_gas_from_gas_left = 0

Note: A commit moves no gas and does not change evm_state_gas_used. It marks the state-gas as not refillable, so the rollback above does not credit it to gas_left.

If the transaction fails before the top-level frame is entered, the pre-execution phase is rolled back, including the authorizations (EIP-2780). All state-gas charged in that phase is refilled: state_gas_from_gas_left and state_gas_committed are both credited to gas_left, and state_gas_baseline and state_gas_reservoir are set back to the values they had at the start of the transaction.

When a child frame succeeds, its remaining gas_left is returned to the parent and its state_gas_from_gas_left is added to the parent’s state_gas_from_gas_left (the state-gas it funded from gas_left persists and is now backed by the merged gas_left). Then, with the child’s state_gas_reservoir merged in, the frame returns state-gas to gas_left, up to the amount it has outstanding:

d = min(state_gas_reservoir, state_gas_from_gas_left)
gas_left += d
state_gas_reservoir -= d
state_gas_from_gas_left -= d

Note: this undoes no state creation, so evm_state_gas_used is unchanged. It only moves gas between the two pools.

This step is needed because a refill may happen in a different frame than the matching charge. The original value in the SSTORE table above is the value at transaction start, not at frame entry. A frame may therefore clear a slot allocated by an earlier frame. Its state_gas_from_gas_left may be smaller than the refill, and the rest goes to state_gas_reservoir, although the charge drew from gas_left. The step moves it up on every merge, to the first frame with an outstanding state_gas_from_gas_left. If it reaches the top-level frame, it stays in state_gas_reservoir and is returned to the sender by the end-of-transaction settlement.

The step applies to successful children only. This requires that a frame that reverts or halts exceptionally returns no state-gas to its parent; the restore to the frame’s baseline above provides that. Otherwise the parent receives state-gas for a slot the rollback restored, and a later merge moves it to gas_left.

When a child frame reverts, all of its state changes are rolled back, its state-gas is restored as above, and its resulting gas_left (including the credited state_gas_from_gas_left) is returned to the parent.

When a child frame halts exceptionally, the same restore is applied, but the child’s gas_left is consumed (set to zero) rather than returned, so the credited state_gas_from_gas_left is consumed with it.

The same rules apply when the top-level call frame reverts or halts, treating the frame as a child of the transaction boundary. In particular, for address collisions in contract-creation transactions, gas_left is consumed in full. The colliding destination has a nonzero nonce or non-empty code (EIP-684), so no account-creation state-gas was charged. The state_gas_reservoir is returned to the sender by the normal end-of-transaction settlement.

Gas accounting for EIP-7702 authorizations

Gas charges for EIP-7702 authorizations follow the specification in EIP-2780.

Pre-state and post-state gas validation

EIP-7928 defines two-phase gas validation for state-accessing opcodes: pre-state costs (determinable without state access) and post-state costs (requiring state access). Under this EIP, the execution-gas portion of these opcodes follows the EIP-7928 rules unchanged and is charged at opcode time against gas_left. The state-gas portion is also charged at the opcode level, with the timing given for each opcode above.

For SSTORE, the GAS_CALL_STIPEND pre-state check (EIP-7928) applies to gas_left only, excluding the state_gas_reservoir.

Transaction gas used

At the end of transaction execution, the gas used before and after refunds is defined as:

tx_gas_used_before_refund = tx.gas - tx_output.gas_left - tx_output.state_gas_reservoir
tx_gas_refund = min(tx_gas_used_before_refund // 5, tx_output.refund_counter)
tx_gas_used_after_refund = tx_gas_used_before_refund - tx_gas_refund
tx_gas_used = max(tx_gas_used_after_refund, calldata_floor_gas_cost) 

The refund cap remains at 20% of gas used. tx_gas_used applies the EIP-7623 calldata floor after refunds, so the floor can effectively negate part of a refund when calldata_floor_gas_cost > tx_gas_used_after_refund. The receipt cumulative_gas_used uses this post-floor value.

Block-level gas accounting

At block level, instead of tracking a single gas_used counter, we keep track of two counters, one for state-gas and one for execution-gas:

tx_state_gas = tx_output.evm_state_gas_used
tx_execution_gas = max(tx_gas_used_after_refund - tx_state_gas, calldata_floor_gas_cost)

block_output.block_execution_gas_used += tx_execution_gas
block_output.block_state_gas_used += tx_state_gas

Since all state-gas charges are now applied as runtime or execution-time charges (per EIP-2780), the transaction’s total state-gas is fully captured by evm_state_gas_used; there is no separate intrinsic state-gas term to add.

The EIP-7623 calldata floor participates in block accounting through the max term, applied to the execution-gas dimension: calldata is an execution-gas resource, and the floor’s bound on worst-case block size holds only if a data-heavy transaction contributes at least the floor to the block’s gas accounting. The floor is compared against the transaction’s execution-gas portion alone — not the transaction total — so execution gas may absorb the floor exactly as under EIP-7623, while state-gas spending cannot (see Calldata floor in block accounting).

The block header gas_used field is set to:

gas_used = max(block_output.block_execution_gas_used, block_output.block_state_gas_used)

The block validity condition uses this value:

assert gas_used <= block.gas_limit, 'invalid block: too much gas used'

The base fee update rule is also modified accordingly:

gas_used_delta = parent.gas_used - parent.gas_target

Integration with EIP-7778

EIP-7778 excludes transaction refunds from block gas accounting. The refunds in question are those of the transaction refund counter — a execution-gas quantity. State-gas refills are not refunds in this sense: a refill reverses a charge for state that was never durably created (a reverted or exceptionally halted frame, a failed CALL*/CREATE, or a slot set and reset within the same transaction), so the resource metered by the state-gas dimension was never consumed. Refills therefore remain netted into evm_state_gas_used regardless of EIP-7778, and only the execution-gas dimension changes (see State-gas refills under EIP-7778). If implemented together with EIP-7778, the block level would be updated to:

tx_state_gas = tx_output.evm_state_gas_used
tx_execution_gas = max(tx_gas_used_before_refund - tx_state_gas, calldata_floor_gas_cost)

block_output.block_execution_gas_used += tx_execution_gas
block_output.block_state_gas_used += tx_state_gas

The max term preserves EIP-7778’s block accounting rule block.gas_used += max(tx_gas_used, calldata_floor_gas_cost), applied here to the execution-gas dimension.

Receipt semantics

Receipt cumulative_gas_used tracks the cumulative sum of tx_gas_used (post-refund, post-floor) across transactions, instead of the block’s gas_used. This means receipt[i].cumulative_gas_used - receipt[i-1].cumulative_gas_used equals the gas paid by transaction i.

System contracts and system transactions

The gas limit of system contracts (e.g., EIP-2935, EIP-4788, EIP-7002, EIP-7251) that are invoked at the start of every block via a system call is updated from 30M to:

SYSTEM_CALL_GAS_LIMIT = 30_000_000 + STATE_BYTES_PER_STORAGE_SET × CPSB × SYSTEM_MAX_SSTORES_PER_CALL

This ensures preservation of the existing execution margin for system contracts under higher state creation costs.

Here, SYSTEM_MAX_SSTORES_PER_CALL = 16 is the upper bound on the number of new storage slots a single system call is expected to write. It is a margin rather than a bound derived from any particular system contract, and must be re-derived if a system call can write more new slots.

The additional STATE_BYTES_PER_STORAGE_SET × CPSB × SYSTEM_MAX_SSTORES_PER_CALL is placed in state_gas_reservoir while the rest of the system call’s gas is placed in gas_left. System calls remain not subject to the EIP-7825 TX_MAX_GAS_LIMIT cap, do not count against the block gas limit, and do not contribute to either block_execution_gas_used or block_state_gas_used.

Rationale

Deriving the cost per state byte (`CPSB`)

CPSB is a fixed parameter derived from a reference block gas limit. The derivation pins the cost so that, at the reference block gas limit and under expected average utilization, total state growth stays at the target rate. If a future block gas limit increase materially changes the expected state growth rate, CPSB can be re-derived in a subsequent EIP.

Inputs

Target state growth: 120 GiB per year, i.e., 120 × 2^30 = 128,849,018,880 bytes.
Reference block gas limit: 150M gas units.
Slot time: 12 seconds, giving 86400 / 12 = 7,200 blocks per day and 7,200 × 365 = 2,628,000 blocks per year.
Average state-gas utilization: 50% of the block gas limit. Under multidimensional metering, the base fee converges to the target, which is half of the gas limit. On average, half of each block’s gas budget can therefore be consumed by state-gas charges before the base fee starts pushing back.

Derivation

The total state gas available for state creation in a year is:

total_state_gas_per_year = (gas_limit / 2) × blocks_per_year
                         = (150,000,000 / 2) × 2,628,000
                         = 75,000,000 × 2,628,000
                         = 1.971 × 10^14 gas

Dividing by the target byte count gives the cost per state byte:

CPSB = total_state_gas_per_year / target_state_growth
     = 1.971 × 10^14 / 128,849,018,880
     ≈ 1530 gas/byte

Why target a `150M` block limit?

The reference block gas limit of 150M is chosen as a middle ground between the current 60M and the expected future 300M. This allows us to set a CPSB that is not too high (which would cause a large immediate increase in state creation costs) nor too low (which would require a more aggressive increase in a future EIP when the block limit increases further).

With this target, we expect state growth will slow down significantly compared to the current trajectory and then increase again as we slowly increase the block gas limit.

Why target 120 GiB per year?

By targeting a state growth of 120 GiB per year with a 150M block limit, we achieve the following worst-case growth rate at different block limits:

Block limit	Worst-case growth rate
`100M`	80 GiB/year
`150M`	120 GiB/year
`200M`	160 GiB/year
`250M`	200 GiB/year
`300M`	240 GiB/year

These rates are computed assuming blocks are fully utilized with state creation operations, which is a worst-case scenario. Assuming a smooth increase in block limit from 100M to 300M over the next year, we would expect a worst-case average growth rate of around 160 GiB per year, which is a significant improvement over the current trajectory.

Harmonization across state creation

With the current pricing, the gas cost of creating 1 byte of state varies depending on the method used. The following table shows the various methods and their gas cost per byte. The calculation ignores the transaction intrinsic cost (21,000 gas units) and the costs of additional opcodes and scaffolding needed to execute such a transaction.

Method	What is written	Intrinsic gas	Bytes → state	Gas / byte
Deploy 24 kB contract (EIP-170 limit)	Runtime code + account trie node	32,000 CREATE + 200 × 24,576 code deposit = 4,947,200 gas	24,696 B	~200 gas
Fund fresh EOA with 1 wei	Updated account leaf	25,000 new account	~120 B	~208 gas
Add delegate flag to funded EOA (EIP-7702)	23 B (0xef0100‖address) + updated account leaf	25,000 PER_EMPTY_ACCOUNT + 12,500 PER_AUTH_BASE + 1,616 calldata - 7,823 refund = ~31,300 gas	~143 B	~219 gas
EIP-7702 authorization to empty address	23 B (0xef0100‖address) + updated account leaf	25,000 PER_EMPTY_ACCOUNT + 12,500 PER_AUTH_BASE + 1,616 calldata = 39,116 gas	~143 B	~274 gas
Fill new storage slots (SSTORE 0→x)	Slot in storage trie	20,000 gas/slot	64 B	~313 gas

To harmonize costs, we first set the gas cost of a single state byte, CPSB, as explained above. Now that we have a standardized cost per byte, we can derive the various costs parameters by multiplying the unit cost by the increase in bytes any given operation creates in the database (i.e., 64 bytes per slot, 120 bytes per account and 23 bytes per authorization).

Note that the fixed cost GAS_CREATE for contract deployments assumes the same cost as a new account creation.

Deriving byte size for new slots and accounts

The byte sizes used in this proposal correspond to the on-disk footprint of a new account or storage slot, taking into account both the leaf data and the key under which it is stored.

A new account adds 120 bytes:

Field	Size
Account hash (key)	32 bytes
Nonce	8 bytes
Balance	16 bytes
Code hash	32 bytes
Storage root	32 bytes
Total	120 bytes

A new storage slot adds 64 bytes:

Field	Size
Slot hash (key)	32 bytes
Value	32 bytes
Total	64 bytes

For EIP-7702 authorizations on an already-existing account, no new account leaf is created. The only new state written is the delegation indicator stored in the authority’s code field. As specified in EIP-7702, this indicator is the 3-byte magic prefix 0xef0100 concatenated with the 20-byte delegate address, for a total of 23 bytes:

Field	Size
Delegation magic (`0xef0100`)	3 bytes
Delegate address	20 bytes
Total	23 bytes

When the authorization targets a non-existent account, the full STATE_BYTES_PER_NEW_ACCOUNT is charged in addition to STATE_BYTES_PER_AUTH_BASE, since both a new account leaf and the delegation indicator are written.

These figures account only for the leaf payload and its keccak256 key. They do not include the additional trie overhead (intermediate nodes, encoding, etc.) incurred when the new entry is inserted. The values are therefore a lower bound on the actual state growth per operation.

Multidimensional metering

EIP-7825 limit on contract size

EIP-7825 introduces TX_MAX_GAS_LIMIT (16.7M) as the maximum gas for a single transaction, in particular stipulating tx.gas <= TX_MAX_GAS_LIMIT as a validity condition. Were we to continue enforcing this validity condition, with CPSB = 1530, this proposal would limit the maximum contract size that can be deployed to roughly 7.5kB. Assuming a representative constructor execution budget of 5M execution gas on top of the 21,000 base transaction cost and the STATE_BYTES_PER_NEW_ACCOUNT × CPSB account-creation cost, the remaining budget for code-deposit state gas yields $\frac{16,777,216 - 21,000 - 5,000,000 - 120 \times 1530}{1530} \approx 7{,}564$ bytes. This maximum size would only decrease if CPSB is re-derived upward in a future EIP.

To solve this issue, we only apply this gas limit to execution gas, not state gas. Doing so does not weaken the intended scaling effect of EIP-7825, because execution gas meters all resources that benefit from parallelization. In particular, state growth does not: growing the state always requires writing to disk, an operation that can be parallelized, but crucially this part of the cost of a state growth operation has to be metered in execution gas, not state gas. In other words, any operation that grows the state should consume both execution gas and state gas, and the execution gas should fully account for all costs other than the long term effect of growing the state.

However, we cannot statically enforce an execution gas consumption of TX_MAX_GAS_LIMIT, while still allowing a higher state gas consumption, because transactions only have a single gas limit parameter, tx.gas. This is solved through a reservoir model: at transaction start, evm_gas is split into gas_left (capped at TX_MAX_GAS_LIMIT - intrinsic_gas) and a state_gas_reservoir (the overflow). State gas charges draw from the reservoir first, then from gas_left when the reservoir is empty. Execution gas charges draw from gas_left only. Exceeding the execution gas budget behaves identically to running out of gas — no special error is needed.

State-gas refills are applied in last-in, first-out (LIFO) order: because charges draw from the reservoir first and from gas_left last, refills credit gas_left first (up to the gas it borrowed, tracked by the frame-local state_gas_from_gas_left counter), then the reservoir. Undoing a state creation therefore restores the exact pools the charge drew from, as long as both happen in the same frame. Because the original value in the SSTORE table above is the value at transaction start rather than at frame entry, a refill may land in a frame other than the one that was charged; the counter is frame-local, so the gas then stays in the reservoir while the gas_left that funded the charge stays reduced. Returning it to gas_left on the merge keeps the two pools from drifting into one another: gas_left is never inflated beyond TX_MAX_GAS_LIMIT - intrinsic_gas, and state-gas is not left in the reservoir while a frame is still owed it. The same mismatch is why LIFO order alone does not make a frame’s rollback correct: a frame may credit a refill it never funded, so rollback is specified as a restore to the frame’s baseline (see Gas accounting for halts and reverts).

Keeping an absolute transaction gas limit

Applying EIP-7825’s cap to execution-gas alone would leave tx.gas itself bounded only by the block gas limit. That is not the intent of this proposal: a per-transaction gas limit is worth keeping. EIP-7825 introduced one so that the work a single transaction can represent stays a small and predictable unit for proving, parallel execution, and scheduling, and so that this bound is fixed by the protocol rather than drifting upward with every block gas limit increase. This proposal raises that limit for the state dimension; it does not abolish it.

tx.gas is therefore capped at TX_MAX_TOTAL_GAS_LIMIT, which keeps every transaction’s gas limit within an unsigned 32-bit integer. The bound is chosen to sit far above the deployments this proposal sets out to enable. Reusing the figures above (the 21,000 base transaction cost, a representative 5M execution gas constructor budget, and the STATE_BYTES_PER_NEW_ACCOUNT × CPSB account-creation cost), the code-deposit budget it leaves is $\frac{2^{32} - 1 - 21,000 - 5,000,000 - 120 \times 1530}{1530} \approx 2{,}803{,}766$ bytes, roughly 2.8 MB and about 43 times EIP-7954’s 65,536-byte contract size limit, so a single transaction can still deploy dozens of maximum-size contracts. While the block gas limit stays below TX_MAX_TOTAL_GAS_LIMIT, the per-dimension block checks are the tighter bound and the cap rejects nothing that could be included today; what it adds is a ceiling that no later block gas limit increase can lift.

Higher throughput

Another advantage of metering contract creation separately is that increasing the cost of state creation operation in line with the block limit will not affect the available gas for other operations. This allows for higher throughput.

Calldata floor in block accounting

The EIP-7623 calldata floor (raised further by EIP-7976) bounds worst-case block size only because it participates in block gas accounting: a data-heavy transaction must occupy at least the floor’s worth of the block gas limit, which is also what EIP-7778 preserves with max(tx_gas_used, calldata_floor_gas_cost). Omitting the floor from the two-dimensional accounting would let such a transaction pay the floor while contributing only its pre-floor gas to block_execution_gas_used, re-expanding the maximum bytes per block by the ratio of floor to standard calldata pricing and hiding the difference from the base-fee update. The transaction-validity check max(intrinsic_gas, calldata_floor_gas_cost) <= TX_MAX_GAS_LIMIT does not provide this bound: it caps a single transaction’s calldata against the EIP-7825 transaction limit but contributes nothing to the block’s cumulative counters, so a block could otherwise be filled with individually valid transactions whose floors were paid but never counted.

The floor is compared against the transaction’s execution-gas portion (tx_gas_used_after_refund - tx_state_gas, or the before-refund equivalent under EIP-7778) rather than the transaction total. This is the per-dimension restatement of EIP-7623’s existing rule, not a new restriction. Under single-dimensional accounting, gas spent on execution may absorb the floor, and this is sound because the absorbing gas occupies the very block budget the floor protects: with or without the floor binding, a transaction carrying B calldata bytes occupies at least the floor’s worth of block gas, which is the invariant that bounds bytes per block. Execution gas retains exactly this absorbing role here.

What the per-dimension comparison rules out is absorption across dimensions. State-gas occupies the state dimension’s separate budget, so under a transaction-total comparison (max(tx_gas_used_after_refund, calldata_floor_gas_cost) - tx_state_gas) a transaction padded with state creation would enter its calldata into the execution dimension below the floor rate. The bytes-per-block bound would then no longer be a property of the execution dimension: it would hold only to the extent that the padding fills the state dimension, making the effective calldata bound a function of the state-gas schedule (CPSB and the per-item byte sizes) and silently weakening it whenever that schedule is re-derived. The per-dimension comparison keeps the bound unconditional and independent of state-gas pricing.

A consequence of the per-dimension comparison is that the sum of a transaction’s block-accounted gas across dimensions can exceed the gas its sender pays; this is intentional — block accounting bounds resource consumption per dimension, while the payment rule remains the transaction-level floor of EIP-7623.

State-gas refills under EIP-7778

EIP-7778 counts refunds toward block gas because a refund rebates work that was actually performed: a refunded SSTORE executed and its computational cost was real, so the rebate is an incentive, not evidence of less work. A state-gas refill is the opposite case. State-gas meters durable state growth, and a refill fires only when that growth is undone — the resource the dimension meters was never consumed. Counting gross (pre-refill) state-gas would make block_state_gas_used overstate actual state growth and invalidate the CPSB derivation, which assumes the block’s state-gas approximates bytes written to state. There is no smuggling vector in excluding refills: the transient computation of rolled-back operations remains fully counted, since their execution-gas charges stay consumed and, under EIP-7778, are counted before refunds.

Account-creation charging and EIP-7928

EIP-7928 (Block-Level Access Lists) constrains when the target address of CREATE/CREATE2 may be accessed: only once the EVM reaches the computed address (on post-access out-of-gas, on creation collision, or when creation setup increments the new account’s nonce), and not on address computation alone, nor when creation fails before access (e.g., insufficient sender balance for the endowment, nonce overflow, or the call-stack depth limit).

The conditional account-creation charge is compatible with this by construction. The existence read that decides the charge is the same single access that performs the EIP-684 collision check, and it happens after the pre-access failure checks — exactly the access EIP-7928 already sanctions and records. Creations that fail before access charge nothing and appear nowhere in the block access list; creations that reach the access point are recorded and pay exactly for the state they are about to create. The recorded access set is identical to that of an unconditional-charge design: the charge decision introduces no additional read.

An earlier revision of this EIP instead charged the account-creation portion unconditionally before the create frame (before the balance, nonce, and depth checks) and refilled it on frame exit when the destination pre-existed or creation failed. The conditional model was adopted because it removes the pre-existing-destination refill and the pre-access-failure refills (nothing was charged), aligns CREATE/CREATE2 with the CALL* family (state-dependent charges are applied when the state is read, conditionally on what is actually created), and avoids temporarily under-budgeting the create frame of a deployment onto a pre-existing account (e.g., a pre-funded deterministic-deployment address). The remaining refill — on failure of the create frame — is shared with CALL*. At the transaction level the account-creation charge is not part of intrinsic gas at all: per EIP-2780 it is a runtime charge, so transaction validity remains decidable without any state access while the charge is metered only when the state is actually accessed.

Placement of the charge among the remaining alternatives:

Why not charge after the create frame exits? Up to 63/64 of the parent’s execution gas is forwarded to the child, and deployment code may legitimately consume nearly all of it. Deferring the charge until the frame returns could make an otherwise-successful deployment fail with out-of-gas at frame exit, introducing semantic uncertainty.
Why not charge inside the create frame? That would silently move the out-of-gas condition from the parent frame (the pre-existing behavior for account-creation charges) to the child frame. Charging in the creating frame, right after the destination access and before the 63/64 split, keeps the out-of-gas locus and the forwarded-gas computation identical to the CALL* family.

For the CALL* family the charge remains conditional and is unchanged: the callee is already resolved (including EIP-7702 delegation resolution) before the child frame, so there is no deferred-access conflict, and unconditionally pre-charging every call would create significant compatibility concerns (e.g., Solidity’s address.transfer() forwards no gas to the child frame).

A remaining gap is value-bearing normal transactions to an empty account, which trigger account creation but are not currently charged for it. This is addressed by EIP-2780, which adds the account-creation cost to the intrinsic gas of such transactions (see Pricing mismatch with respect to ETH transfers).

Backwards Compatibility

This is a backwards-incompatible gas repricing that requires a scheduled network upgrade.

Wallet developers and node operators MUST update gas estimation handling to accommodate the new state creation costs and the two-dimensional metering model. Specifically:

Wallets: Wallets using eth_estimateGas MUST be updated to ensure they correctly account for the updated state creation costs and report tx.gas covering both the execution-gas and state-gas dimensions. Failure to do so could result in underestimating gas, leading to failed transactions.
Node Software: RPC methods such as eth_estimateGas MUST incorporate the new state-gas charges, the reservoir-model accounting, and the two-dimensional block accounting when computing gas estimates.

Users can maintain their usual workflows without modification, as wallet and RPC updates will handle these changes.

Contracts and tools measuring work as the difference between two GAS reads can get a negative result. This EIP makes it possible both within a frame and across a call (see gas_left can increase). Contracts already deployed with such metering cannot be fixed.

Deterministic deployment factories

Some well-known deterministic deployment factories are deployed via pre-signed transactions with a hardcoded gas limit. The classic Nick’s method factory, for instance, uses a pre-signed transaction with a 100,000 gas limit. Under this EIP, the state creation cost of deploying these factories increases beyond their hardcoded gas limit, so the original pre-signed deployment transactions will no longer execute successfully. The same applies to other deterministic deployer contracts such as SingletonFactory, Create2Deployer, ImmutableCreate2Factory, and CreateX.

This does not affect existing networks where these factories are already deployed, including mainnet and L2s (which maintain their own gas schedules). The impact is limited to new networks (e.g., devnets and testnets) that activate this EIP from genesis and have not yet deployed these factories. On such networks, the pre-signed deployment transactions must be regenerated with an updated gas limit, or the factories must be pre-deployed at genesis. Tooling that relies on these factories being available at their canonical addresses SHOULD ensure they are deployed before use.

Estimated price impacts

Users and dApp developers will experience an increase in transaction costs associated with creating a new state. The next table summarizes the state-gas portion of state creation costs for common operations under the proposed CPSB of 1,530. Additional execution-gas charges (e.g., ACCOUNT_WRITE, STORAGE_WRITE, hash cost) defined in EIP-8038 apply on top.

Case	Current gas cost	Proposed gas cost	Gas cost increase	Proposed cost (ETH)
New account	25,000	183,600	~7×	0.0000147
New slot	20,000	97,920	~5×	0.00000783
24 kB contract deployment	4,947,200	37,784,880	~8×	0.00302

The “Proposed cost (ETH)” column assumes a base fee of 0.08 Gwei, which corresponds to the average base fee observed after the 60M gas increase in December 2025 and January 2026.

Security Considerations

Increasing the cost of state creation operations could impact the usability of certain applications. More analysis is needed to understand the potential effects on various dApps and user behaviors.

Pricing mismatch with respect to ETH transfers

One potential concern is the cost of creating a new account (STATE_BYTES_PER_NEW_ACCOUNT × CPSB gas units, e.g., 183,600 at the proposed CPSB), compared to transferring ETH to a fresh account (21,000 gas units). With this mismatch, users wishing to create a new account are incentivized to first send a normal transaction (costing 21,000) to this account to create it, thus avoiding the GAS_NEW_ACCOUNT charge.

EIP-2780 solves this mismatch by adding a new component to the intrinsic gas cost of transactions. If a non-create transaction has value > 0 and targets a non-existent account, the GAS_NEW_ACCOUNT is added to intrinsic cost.

Added complexity in block building

Optimal block construction becomes more complex, since builders must now balance resource usage across multiple dimensions rather than a single gas metric. Sophisticated builders may gain an advantage by applying advanced optimization techniques, raising concerns about further builder centralization. However, practical heuristics (e.g., greedily filling blocks until one resource dimension saturates) remain effective for most use cases. These heuristics limit centralization pressure by keeping block construction feasible for local and less sophisticated builders.

`gas_left` can increase

Refills credit gas_left before state_gas_reservoir, so a frame’s gas_left can be higher after an operation than before it. A contract measuring work as the difference between two GAS reads then gets a negative value. This reverts under checked arithmetic and wraps under unchecked arithmetic.

A negative result requires the charge to have drawn from gas_left, i.e. the reservoir to be empty. That is the case for every transaction with tx.gas up to TX_MAX_GAS_LIMIT.

This is already possible in a single frame. Allocating a storage slot that was zero at transaction start and clearing it again refills STATE_BYTES_PER_STORAGE_SET × CPSB to gas_left. SSTORE(k, 1); GAS; SSTORE(k, 0); GAS shows it: the two reads differ by the refill less the cost of the clear. Reads around both stores do not, because the charge and the refill cancel between them.

Returning state-gas on a merge extends this across a call boundary, which no call does today. Metering a sub-call this way is the more common pattern. The amount is not limited to one slot: a merge returns up to the whole state_gas_from_gas_left the frame has accumulated. The bound is that gas_left + state_gas_from_gas_left never exceeds the frame’s gas_left at entry.

Interaction with ERC-4337 bundles

The GAS opcode returns gas_left only and cannot observe state_gas_reservoir. Bundling protocols that meter sub-call consumption via gasleft() deltas (e.g., the ERC-4337 EntryPoint) therefore cannot accurately attribute state-gas usage when it is funded by the reservoir. Because all user operations in a bundle share the transaction’s reservoir, one user operation’s state-gas refunds can subsidize another’s state-gas charges without appearing in either’s gasleft() delta. Bundlers and EntryPoint implementations MUST account for state-gas charges and refunds explicitly rather than relying on gasleft() differences alone.

Copyright

State-access gas cost update

Fri, 03 Oct 2025 00:00:00 +0000

EIP #8038 - State-access gas cost update is in Last Call status. It is authored by Maria Silva (@misilva73), Wei Han Ng (@weiihann), Ansgar Dietrichs (@adietrichs) and was originally created 2025-10-03. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-8038-state-access-gas-cost-update/25693

Abstract

This EIP updates the gas cost of state-access operations to reflect Ethereum’s larger state and the consequent slowdown of these operations. It dissects the cost of state-touching operations into three components — access, write, and state creation: the cold account access cost (COLD_ACCOUNT_ACCESS) is raised, explicit write surcharges (ACCOUNT_WRITE, STORAGE_WRITE) are introduced, state-creation costs are left to EIP-8037, and EXTCODESIZE and EXTCODECOPY are charged for their second database read.

Motivation

The gas price of accessing state has not been updated for quite some time. EIP-2929 was included in the Berlin fork in March 2021 and raised the costs of state-accessing opcodes. Yet, since then, Ethereum’s state has grown significantly, thus deteriorating the performance of these operations. This proposal further raises state access costs to better align them with the current performance of state access operations, in relation to other operations.

Additionally, EXTCODESIZE and EXTCODECOPY have the same access cost as BALANCE and EXTCODEHASH. However, EXTCODESIZE and EXTCODECOPY require two database reads - first to load the account object (which includes the nonce, balance, codeHash and storageRoot), and second to collect the required information (the code size and bytecode respectively). Therefore, the access cost of EXTCODESIZE and EXTCODECOPY should be higher when compared with the other account read operations.

Specification

Cost components

The gas cost of a state-touching operation is the sum of up to three independent components:

Access — the cost of loading an account or storage slot from the database: COLD_ACCOUNT_ACCESS, COLD_STORAGE_ACCESS and WARM_ACCESS, renamed by this EIP from the EIP-2929 parameters. This EIP raises COLD_ACCOUNT_ACCESS, while COLD_STORAGE_ACCESS and WARM_ACCESS are unchanged; the EIP-2929 rules that determine whether an access is cold or warm are unchanged.
Write — the cost of writing an object’s leaf values when they change, whether or not the leaf already exists: STORAGE_WRITE for a storage slot and ACCOUNT_WRITE for an account’s leaf values (nonce, balance, code hash), both introduced by this EIP. The pre-existing schedule has no standalone constant for this component; it is fused into composites such as GAS_STORAGE_UPDATE (EIP-2200’s SSTORE_RESET_GAS), CALL_VALUE (the Yellow Paper’s G_callvalue) and GAS_CREATE (G_create). The two write surcharges follow different charging disciplines, stated once here and applying everywhere below:
- STORAGE_WRITE is net-metered within a transaction: it is charged by each SSTORE that moves a slot away from its transaction-start value and credited back by each later SSTORE that restores that value (refund rule 3 below), so a slot that ends the transaction with a changed value pays it exactly once and a slot that ends unchanged pays only access costs, subject to the refund cap.
- ACCOUNT_WRITE is charged per operation that writes an account’s leaf values. For every operation specified in this EIP there is no per-account tracking and no refund: a value-bearing CALL to the same recipient pays it on each call. (EIP-2780 charges it at most once per authority per transaction when processing EIP-7702 authorizations; that first-write rule is defined there and applies only to authorization processing.)
State creation — the cost of adding a new leaf to the state: GAS_STORAGE_SET for a new storage slot and GAS_NEW_ACCOUNT for a new account. This EIP does not reprice these constants; they are repriced by EIP-8037 and charged to its state-gas dimension. This EIP states where the component applies so that each operation’s complete cost is visible in one place.

The sections below specify each operation as a consumer of this model: which access cost applies, whether and when a write surcharge applies, and which state-creation charge accompanies it.

Parameters

Upon activation of this EIP, the following parameters of the gas model are introduced/updated:

Parameter	Component	Description	Current value	New value	Increase	Operations affected
`COLD_ACCOUNT_ACCESS`	Access	Cold touch of an account. Renamed from `COLD_ACCOUNT_ACCESS_COST` (EIP-2929)	2,600	3,000	+15%	`CALL` opcodes, `BALANCE`, `SELFDESTRUCT`, `EXT` opcodes, EOA delegation resolution, EOA delegation setting (5), contract creation txs / `CREATE` / `CREATE2` (4), and ETH transfers
`COLD_STORAGE_ACCESS`	Access	Cold touch of a storage slot. Renamed from `COLD_SLOAD_COST` (EIP-2929)	2,100	2,100	+0%	`SSTORE` and `SLOAD`
`WARM_ACCESS`	Access	Touch of an already-warm account or storage slot. Renamed from `WARM_STORAGE_READ_COST` (EIP-2929)	100	100	+0%	`SSTORE`, `SLOAD`, `CALL` opcodes, `BALANCE`, `EXT` opcodes, EOA delegation resolution, EOA delegation setting (5)
`ACCOUNT_WRITE`	Write	Write to an account’s leaf values (nonce, balance, code hash); charged per operation. New named parameter (previously embedded in `CALL_VALUE`, see footnote 1)	6,700 (1)	9,000	+34%	value-transferring `*CALL` opcodes, `SELFDESTRUCT`, contract creation txs / `CREATE` / `CREATE2` (4), EOA delegation setting
`STORAGE_WRITE`	Write	Write that changes a storage slot’s value; net-metered per transaction. New named parameter (previously derived, see footnote 2)	2,800 (2)	10,000	+257%	`SSTORE`
`CREATE_ACCESS`	Access + write	Combined access-and-write cost of contract deployment: `ACCOUNT_WRITE` + `COLD_ACCOUNT_ACCESS`. New named parameter (previously derived, see footnote 3)	7,000 (3)	12,000	+71%	contract creation txs / `CREATE` / `CREATE2`
`STORAGE_CLEAR_REFUND`	Refund	Refund for clearing a storage slot. Renamed from `SSTORE_CLEARS_SCHEDULE` (EIP-3529)	4,800	11,616	+142%	`SSTORE`
`ACCESS_LIST_STORAGE_KEY_COST`	Access (prepaid)	Gas charged per storage key included in a transaction’s access list. Unchanged name from EIP-2930	1,900	2,000	+5%	`SSTORE` and `SLOAD`
`ACCESS_LIST_ADDRESS_COST`	Access (prepaid)	Gas charged per address included in a transaction’s access list. Unchanged name from EIP-2930	2,400	2,900	+21%	`CALL` opcodes, `BALANCE`, `SELFDESTRUCT` and `EXT` opcodes

(1): 6,700 = CALL_VALUE (the Yellow Paper’s G_callvalue, 9,000) - CALL_STIPEND (G_callstipend, 2,300)

(2): 2,800 = GAS_STORAGE_UPDATE (EIP-2200’s SSTORE_RESET_GAS, 5,000) - GAS_COLD_SLOAD (2,100) - GAS_WARM_ACCESS (100)

(3): 7,000 = GAS_CREATE (the Yellow Paper’s G_create, 32,000) - GAS_NEW_ACCOUNT (G_newaccount, 25,000)

(4): Charged only as part of CREATE_ACCESS, not separately — these operations pay CREATE_ACCESS once, and never COLD_ACCOUNT_ACCESS or ACCOUNT_WRITE on top of it. The CREATE/CREATE2 charge is specified in the CREATE/CREATE2 section below; the contract-creation transaction charge is specified in EIP-2780.

(5): Charged only as part of EIP-8037’s EXECUTION_PER_AUTH_BASE_COST. Setting a delegation is distinct from resolving one: resolution loads the delegation target’s code at runtime and is charged the standard cold or warm access directly.

ACCOUNT_WRITE, STORAGE_WRITE and CREATE_ACCESS are new parameters with no pre-existing counterpart; their “Current value” column shows the equivalent cost extracted from the pre-existing composite constants per the footnotes above. The pre-existing schedule is not exactly separable into these components, so these equivalents are approximate: footnote 2 yields the write component of the current warm-case SSTORE charge exactly (2,900 = GAS_WARM_ACCESS + 2,800), while the cold-case charge of 5,000 exceeds the sum of its components by 100; footnote 3 is discussed in the CREATE/CREATE2 section below.

`SSTORE` pricing

In addition, the SSTORE cost formula is updated. As in EIP-2200, the original value is the slot’s value at the start of the current transaction and the current value is its value just before the SSTORE executes. The complete SSTORE charge is the sum of its three cost components:

Access component: COLD_STORAGE_ACCESS or WARM_ACCESS, depending on whether the storage slot is cold or warm.
Write component: additionally charge STORAGE_WRITE if the new value is different from the current value and the current value equals the original value (the write moves the slot away from its transaction-start value).
State-creation component: additionally charge GAS_STORAGE_SET (per EIP-8037, metered in state-gas) if the original value is zero, the current value is zero, and the new value is non-zero.

Refunds are also updated as follows. Each rule is an adjustment to the transaction’s refund counter and is evaluated on every SSTORE:

STORAGE_CLEAR_REFUND is added if the original value is non-zero, the current value is non-zero and the new value is zero (a slot is cleared).
STORAGE_CLEAR_REFUND is subtracted if the original value is non-zero, the current value is zero and the new value is non-zero (a slot that was cleared earlier in the same transaction is set to a non-zero value again, whether or not that value is its original one). This reverses the refund granted by rule 1, so that clearing and then re-setting a slot within the same transaction is never net-profitable.
STORAGE_WRITE is refunded if the new value equals the original value and differs from the current value (a change made earlier in the same transaction is undone, restoring the slot’s transaction-start value).

Rules 2 and 3 mirror the refund accounting of EIP-2200 and EIP-3529 for slots that are modified more than once within a transaction: a STORAGE_WRITE charge or STORAGE_CLEAR_REFUND granted on an earlier SSTORE to the same slot is undone when a later SSTORE returns the slot to its original value. Without these reversals, a round trip such as x → 0 → x would yield a net refund even though the slot ends the transaction unchanged. Net over the whole transaction, a slot that ends at a changed value pays its write and state-creation components exactly once, and a slot that ends at its original value pays only its access costs — in both cases regardless of how often the slot was written, and subject to the refund cap.

These refunds go to the transaction’s refund counter and are capped to 20% of the total gas used by the transaction, as per the current refund mechanism.

The rules for state creation cost charges and refills are addressed in EIP-8037.

Cases and their corresponding costs are detailed in the table below:

Original value	Current value	New value	Access status	Description	Execution-gas charges/refunds	State-gas charges/refills
0	0	x	Cold	New slot	`COLD_STORAGE_ACCESS` + `STORAGE_WRITE` charged	`GAS_STORAGE_SET` charged
0	0	x	Warm	New slot	`WARM_ACCESS` + `STORAGE_WRITE` charged	`GAS_STORAGE_SET` charged
x	x	y	Cold	Existing slot, first change	`COLD_STORAGE_ACCESS` + `STORAGE_WRITE` charged	no state-gas adjustments
x	x	y	Warm	Existing slot, first change	`WARM_ACCESS` + `STORAGE_WRITE` charged	no state-gas adjustments
x	x	0	Cold	Cleared slot, non-zero at transaction start	`COLD_STORAGE_ACCESS` + `STORAGE_WRITE` charged, `STORAGE_CLEAR_REFUND` refunded	no state-gas adjustments
x	x	0	Warm	Cleared slot, non-zero at transaction start	`WARM_ACCESS` + `STORAGE_WRITE` charged, `STORAGE_CLEAR_REFUND` refunded	no state-gas adjustments
0	x	0	Warm	Set slot reset to zero (zero at transaction start)	`WARM_ACCESS` charged, `STORAGE_WRITE` refunded	`GAS_STORAGE_SET` refilled
0	x	y	Warm	Slot set earlier in the transaction written to a different non-zero value	`WARM_ACCESS` charged	no state-gas adjustments
x	y	x	Warm	Previously-modified slot reset to original value	`WARM_ACCESS` charged, `STORAGE_WRITE` refunded	no state-gas adjustments
x	y	0	Warm	Previously-modified slot cleared, non-zero at transaction start	`WARM_ACCESS` charged, `STORAGE_CLEAR_REFUND` refunded	no state-gas adjustments
x	0	x	Warm	Cleared slot restored to original value	`WARM_ACCESS` charged, `STORAGE_WRITE` refunded, `STORAGE_CLEAR_REFUND` reversed	no state-gas adjustments
x	0	y	Warm	Cleared slot written to a new non-zero value	`WARM_ACCESS` charged, `STORAGE_CLEAR_REFUND` reversed	no state-gas adjustments
x	y	z	Warm	Previously-modified slot written to another non-zero value	`WARM_ACCESS` charged	no state-gas adjustments

Account access pricing

The EIP-2929 rules that determine whether an account access is cold or warm are unchanged; this EIP raises the cold access cost and states explicitly, per operation below, where the write and state-creation components apply.

`CALL`/`CALLCODE`

For CALL and CALLCODE operations, CALL_VALUE (the Yellow Paper’s G_callvalue) is redefined as ACCOUNT_WRITE + CALL_STIPEND, where CALL_STIPEND (G_callstipend, 2,300) is unchanged. ACCOUNT_WRITE here prices the write to the recipient’s balance leaf and, per its charging discipline, is paid on every value-transferring call. The state-creation component of a value-transferring CALL to a dead account (as defined in EIP-161) is GAS_NEW_ACCOUNT, which this EIP does not reprice; it is repriced and metered in state gas by EIP-8037. CALLCODE never incurs it: its recipient is the calling account itself, which already exists.

`CREATE`/`CREATE2`

CREATE and CREATE2 operations don’t have explicit warm/cold pricing. Instead, the flat GAS_CREATE (the Yellow Paper’s G_create, 32,000) is replaced by CREATE_ACCESS, charged in execution gas, plus GAS_NEW_ACCOUNT, charged in state gas (per EIP-8037). CREATE_ACCESS, defined as ACCOUNT_WRITE + COLD_ACCOUNT_ACCESS, is the combined access-and-write component of the deployment; GAS_NEW_ACCOUNT is its state-creation component and is not repriced by this EIP.

Note: this definition does not exactly match the legacy decomposition shown in footnote 3 of the Parameters table (GAS_CREATE - GAS_NEW_ACCOUNT = 7,000). The pre-existing accounting in the protocol is not internally consistent here, and this EIP keeps the discrepancy rather than attempting to reconcile it.

`SELFDESTRUCT`

For SELFDESTRUCT, charge COLD_ACCOUNT_ACCESS in execution gas if the beneficiary is cold, regardless of the balance being transferred. A warm beneficiary incurs no access charge: the EIP-2929 exemption from WARM_ACCESS is preserved, including when the beneficiary is the executing account itself or a precompile. The opcode base cost and the rules for determining and updating the beneficiary’s cold or warm status are unchanged.

For SELFDESTRUCT, an additional charge of ACCOUNT_WRITE is added if a positive balance is sent to a dead account (as defined in EIP-161) — the write component of creating the beneficiary’s leaf. The state-creation component in this same case is GAS_NEW_ACCOUNT, which remains in place alongside the new ACCOUNT_WRITE charge and is metered in state-gas by EIP-8037.

`EXT*` family update

Besides the current access costs, EXTCODESIZE and EXTCODECOPY are charged an additional WARM_ACCESS.

Overview

The cases for account-related operations and their corresponding cost components are summarized in the table below. The state-creation column is charged in state-gas and is not repriced by this EIP (see EIP-8037).

Operation	Access component	Write component (`ACCOUNT_WRITE`)	State-creation component
`CALL` / `CALLCODE`	`COLD_ACCOUNT_ACCESS` or `WARM_ACCESS`	when value is transferred (via `CALL_VALUE` = `ACCOUNT_WRITE` + `CALL_STIPEND`)	`GAS_NEW_ACCOUNT` when `CALL` transfers value to a dead account; never for `CALLCODE`, whose recipient is the calling account
`DELEGATECALL` / `STATICCALL`	`COLD_ACCOUNT_ACCESS` or `WARM_ACCESS`	never (no value transfer)	—
`CREATE` / `CREATE2`	folded into `CREATE_ACCESS`	always (folded into `CREATE_ACCESS` = `ACCOUNT_WRITE` + `COLD_ACCOUNT_ACCESS`, replacing `GAS_CREATE`)	`GAS_NEW_ACCOUNT`, plus the per-byte code-deposit cost
`SELFDESTRUCT`	`COLD_ACCOUNT_ACCESS` if cold; zero if warm	when a positive balance is sent to a dead account	`GAS_NEW_ACCOUNT` in the same case
`BALANCE` / `EXTCODEHASH`	`COLD_ACCOUNT_ACCESS` or `WARM_ACCESS`	never	—
`EXTCODESIZE` / `EXTCODECOPY`	`COLD_ACCOUNT_ACCESS` or `WARM_ACCESS`, plus `WARM_ACCESS` for the second database read	never	—

Rationale

Empirical Estimation of Gas Costs

Selecting which Operations to Reprice

The parameters selected for repricing in this EIP were chosen based on the estimated million gas per second (Mgas/s) performance of their respective operations. For this EIP, a performance target of 100 million gas per second is chosen. With this performance target, we will be able to increase the base throughput of the chain by a factor of 5 from our current 20 Mgas/s performance.

Data Collection

The gas costs proposed in this EIP are based on the actual time each execution client takes to run a specific set of benchmarks. Similar to the methodology used in the Gas Cost Estimator project, we generate synthetic blocks that isolate and stress individual EVM operations and use them to derive the various gas parameters.

Concretely, to benchmark a single operation/parameter, different blocks are created by varying the number of times the target operation is executed and by changing the parameter values to the operation. The EEST benchmark suite contains the tests used to generate these blocks.

Then, the Benchmarkoor tool is used to collect the needed metrics. This tool returns the total execution time of the block and the number of times each operation was executed. Each test block is run multiple times on each client to account for variability in execution time.

All benchmarks were run on top of a snapshot with the same size as mainnet in March 2026, so they reflect the current performance of state access operations.

What about differences between client implementations?

Ultimately, we require a single cost model that is independent of the client’s implementation. Although the decision may be different in a specific situation, the general rule is to take the worst client result that cannot be optimized. This means that the worst-performing client on a given operation and resource combination will define the cost of that operation for the entire network. This is the safer and most conservative choice.

Runtime Estimation

To estimate the runtime of a single operation from the total execution time of the corresponding synthetic blocks, a Non-Negative Least Squares Linear Regression is used. This model enforces that all coefficients are non-negative, thus ensuring execution time cannot be negative. The model estimates runtime as a linear combination of:

Constant term (intercept): Base overhead for executing the test, which includes setup and tear-down time
Operation count (slope): Number of times the operation is executed in the test. This parameter is the one that allows us to estimate the per-operation runtime.
Operation-specific parameters (e.g., update): Extra per-operation runtime contributed by an additional, operation-specific binary or numeric input (e.g., whether a CALL is made with value, or whether the SSTORE writes a new value). The update coefficient gives the marginal runtime added per execution for storage writes.

For simple operations (i.e., without additional parameters), the model estimates: runtime = intercept + slope × operation_count

For variable operations, the model estimates: runtime = intercept + slope × operation_count + param1_coef × operation_count × param1 + param2_coef × operation_count × param2 + ...

Independent models are created for each client, operations, and configuration. Only operations and parameters with good model fits (R-squared > 0.5 and p-value < 0.05) are included in the gas cost proposal to ensure the reliability of the estimates.

Glue opcode adjustment

Each benchmark test includes auxiliary “glue” opcodes that scale linearly with the main opcode count. The regression slope captures the combined runtime of both the target opcode and its glue opcodes, so we subtract the estimated glue opcode runtime to isolate the true per-execution cost:

adjusted_slope = slope - sum(ratio_i * glue_runtime_i)

Where, for each glue opcode i:

ratio_i is the number of executions of glue opcode i per execution of the target opcode in the benchmark test.
glue_runtime_i is the estimated per-execution runtime of glue opcode i, taken from its own regression model.

Only glue opcodes with a statistically significant fit (p-value < 0.05) are included. The adjusted slope is clipped to a minimum of zero.

Parameter mapping

Each gas parameter is derived from one or more benchmark models by selecting a specific regression coefficient (slope or update) after applying the relevant filters (test name, cache strategy, account mode). The two coefficients correspond directly to the two cost components this EIP prices: the slope measures the cost of loading the object from the database (the access component), while the update coefficient measures the marginal cost of changing its value (the write component). The state-creation component is not estimated from runtime at all — it prices durable state growth rather than execution time — which is why it is derived separately in EIP-8037 and left unchanged here.

For each parameter and client, the worst-case value across all matching model configurations is used. The final proposal takes the worst case across clients.

The following table lists the directly estimated parameters and their mapping to the regression models:

Test name	Configuration	Model	Parameter mapping
`test_account_access`	`CacheStrategy = NO_CACHE`	runtime = intercept + slope × operation_count + update × value_sent x operation_count	`slope` → `COLD_ACCOUNT_ACCESS`; `update` → `ACCOUNT_WRITE`
`test_sload_bloated`	`CacheStrategy = NO_CACHE`	runtime = intercept + slope × operation_count	`slope` → `COLD_STORAGE_ACCESS`
`test_sstore_bloated`	`CacheStrategy = NO_CACHE`	runtime = intercept + slope × operation_count + update × write_new_value x operation_count	`slope` → `COLD_STORAGE_ACCESS`; `update` → `STORAGE_WRITE`
`test_sload_same_key_benchmark`	—	runtime = intercept + slope × operation_count	`slope` → `WARM_ACCESS`
`test_ext_account_query_warm`	—	runtime = intercept + slope × operation_count	`slope` → `WARM_ACCESS`

test_sstore_bloated and test_sload_bloated targeted a bespoke contract with a storage size of 10 gigabytes, which is the size of the largest mainnet contract.

Conversion to gas costs

New gas costs are calculated using the same target performance of 100 Mgas/s. The formula used is:

new_gas = (anchor_rate * runtime_ms) / 1000

Where:

anchor_rate is the target performance expressed in gas per second (e.g., 100_000_000 for a 100 Mgas/s target).
runtime_ms is the estimated runtime per operation, in milliseconds, taken from the regression models (the adjusted_slope defined above).
The factor 1000 converts runtime_ms from milliseconds to seconds, so that the product with anchor_rate (gas/second) yields a result in gas units.

Derived parameters are computed from the directly estimated ones:

STORAGE_CLEAR_REFUND         = (STORAGE_WRITE + COLD_STORAGE_ACCESS) * (4800/5000)
ACCESS_LIST_STORAGE_KEY_COST = COLD_STORAGE_ACCESS - WARM_ACCESS
ACCESS_LIST_ADDRESS_COST     = COLD_ACCOUNT_ACCESS - WARM_ACCESS
CREATE_ACCESS                = ACCOUNT_WRITE + COLD_ACCOUNT_ACCESS

The two access-list parameters price the same database load as their cold counterparts, so they are derived from those cold costs. WARM_ACCESS is subtracted because a slot or account named in the access list is already warm when the transaction touches it and is therefore still charged WARM_ACCESS at that point: prepaying via the access list must not cost more in access gas than taking the cold access. Without the subtraction, an access-list entry that is used exactly once would cost COLD_ACCESS + WARM_ACCESS in access gas, making the list strictly more expensive than not using it. The invariant covers the access component only; charges that other EIPs levy on the access list’s bytes, such as floor costs, fall outside it.

Interaction with EIP-7928

EIP-7928 introduces Block-Level Access Lists, which enable parallel disk reads, parallel transaction validation, and state updates without execution through client optimizations. Our benchmarks already consider these optimization gains by running on clients with the optimizations implemented.

Special case for `EXTCODESIZE` and `EXTCODECOPY`

Differently from other account read operations, EXTCODESIZE and EXTCODECOPY make two reads to the database. The first read is the same, where the object of the target account is loaded. This object includes the account’s nonce, balance, codeHash and storageRoot. Then, these operations do another read to collect either the code size or the bytecode of the account. This second read is to an already warmed account, and thus we propose to price it as WARM_ACCESS for consistency.

Backwards Compatibility

This is a backwards-incompatible gas repricing that requires a scheduled network upgrade.

Wallet developers and node operators MUST update gas estimation handling to accommodate the new state access cost rules. Specifically:

Wallets: Wallets using eth_estimateGas MUST be updated to ensure that they correctly account for the updated gas parameters. Failure to do so could result in underestimating gas, leading to failed transactions.
Node Software: RPC methods such as eth_estimateGas MUST incorporate the updated formula for gas calculation with the new state access cost values.

Users can maintain their usual workflows without modification, as wallet and RPC updates will handle these changes.

Security Considerations

Changing the cost of state access operations could impact the usability of certain applications. More analysis is needed to understand the potential effects on various dApps and user behaviors.

Copyright

Exclude slashed validators from proposing

Thu, 16 Oct 2025 00:00:00 +0000

EIP #8045 - Exclude slashed validators from proposing is in Last Call status. It is authored by Francesco D'Amato (@fradamt), Barnabas Busa (@barnabasbusa) and was originally created 2025-10-16. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-8045-exclude-slashed-validators-from-proposing/25850

Abstract

This EIP proposes a modification to the beacon chain proposer selection process to exclude slashed validators from being selected as proposers.

Motivation

Currently, slashed validators can still be selected as proposers, though their blocks are considered invalid by the state transition function, resulting in missed slots. This is in particular problematic after a mass slashing event, at which point there can be a long period with degraded chain performance, until all slashed validators are exited. If mass slashing also comes with general network disruption, the missed slots can also significantly complicate the recovery process. This change filters out slashed validators during proposer selection, reducing disruption and increasing resilience in such scenarios.

Specification

The get_beacon_proposer_indices function in the consensus specifications is modified to exclude slashed validators from the proposer selection process, effectively going from considering all active validators to all active and unslashed validators.

def get_beacon_proposer_indices(
    state: BeaconState, epoch: Epoch
) -> Vector[ValidatorIndex, SLOTS_PER_EPOCH]:
    """
    Return the proposer indices for the given ``epoch``.
    """
    # Modified to exclude slashed validators
    indices = [i for i in get_active_validator_indices(state, epoch) if not state.validators[i].slashed]
    seed = get_seed(state, epoch, DOMAIN_BEACON_PROPOSER)
    return compute_proposer_indices(state, epoch, seed, indices)

Rationale

Why exclude slashed validators?

Slashed validators are already prevented from successfully proposing blocks through the state transition validation. The process_block function checks that the proposer is not slashed, and blocks from slashed proposers are considered invalid. Therefore, selecting slashed validators as proposers serves no purpose and only results in missed slots.

Design decision: upfront filtering

The chosen approach is to simply filter out slashed validators from the candidate pool, before doing any shuffling computation. An alternative design would be to still use the whole active validator set as the candidate pool, and then only filter out slashed validators once their index has been selected by the shuffle. The exact selection is not identical, but it achieves the same goal, i.e., a balance-weighted selection from the set of active-and-unslashed validators. The complexity is low in either design.

Backwards Compatibility

This EIP introduces a backwards-incompatible change to the consensus rules and MUST be activated as part of a scheduled network upgrade.

Test Cases

Test cases should verify that:

Slashed validators are not selected as proposers
A complete proposer_lookahead is generated even in the presence of slashed validators
Slashings do not affect the existing proposer_lookahead

Security Considerations

Slashed validators are already prevented from successfully proposing blocks through the state transition validation, for good reason, as they are considered to be unreliable participants (malicious or faulty). However, they have historically still been eligible to be selected as proposers in order to ensure stability of the proposer selection mechanism, because excluding them would have severely impacted the stability of the proposer selection mechanism. In fact, any slashing processed on chain would have caused the sequence of future proposers to completely change, even within the lookahead window. However, with EIP-7917, the proposer selection is fixed in advance by storing in the Beacon state, so it would not be affected by slashings processed after the fact.

Impact on proposer selection distribution

This change does not affect the randomness or fairness of proposer selection among non-slashed validators. The selection algorithm remains the same, with the only difference being that slashed validators are excluded from the candidate pool.

Mass slashing scenarios

During mass slashing events, this change is purely beneficial to the resilience of the network, as well as to general quality of service. Instead of having many slashed validators selected as proposers (resulting in many missed slots), the network will continue to operate normally with only non-slashed validators being selected.

Copyright

Increase exit and consolidation churn

Fri, 17 Oct 2025 00:00:00 +0000

EIP #8061 - Increase exit and consolidation churn is in Last Call status. It is authored by Francesco D'Amato (@fradamt), Anders Elowsson (@anderselowsson) and was originally created 2025-10-17. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-8061-increase-churn-limits/25991

Abstract

This EIP roughly doubles the consolidation churn, as well as quadrupling the exit churn and restoring its proportionality to total stake (though maintaining the existing cap on activations). The choice of parameters balances maintaining a sufficiently long weak subjectivity period (~7 days, roughly halving the current period) with achieving two goals: allowing for faster consolidation of the validator set, in turn accelerating the timeline to faster finality, and relieving exit queue congestion, improving staking liquidity.

Motivation

EIP-7514 introduced an activation cap of 8 validators per epoch (now 256 ETH per epoch) to prevent overly rapid validator set growth. EIP-7251 extended this cap to exits, to make room for the newly introduced consolidation operations, without increasing the weak subjectivity period. However, the fixed cap prevents the exit churn limit from being proportional to total stake, which, all else being equal, leads to longer queues as stake grows. Moreover, the CHURN_LIMIT_QUOTIENT is set quite conservatively in the first place, requiring more than 3 months for 1/3 of the validator set to exit, a time which is now be more than doubled due to the cap. Recent episodes have stressed for more headroom to improve liquidity and staking user experience, as the exit queue has stretched beyond forty days as a consequence of the mass exit of Kiln validators. Long queues degrade user experience, and slow operator response to market or operational events. They also reduce the network’s ability to reconfigure stake more quickly after adverse events, for example to regain finality by having a large amount of stake exit (a double-edged sword, as preventing double finality is the reason these queues exist in the first place, as discussed in the security section). Finally, centralized forms of staking are those that (in relative terms) benefit the most from a lack of liquidity today, as they have the ability to issue a liquid staking token, maintain liquidity reserves or more generally build products that get around the limitations of the protocol.

The conservative setting of the CHURN_LIMIT_QUOTIENT affects consolidations as well. Increasing the consolidation churn limit can shorten the path to a smaller validator set and, in turn, the path to a protocol with much faster finality. Under today’s parameters, even the best-case timelines are long: using only activations and exits, fully saturated around the clock, shrinking the roughly 32M ETH of 0x01 stake would take on the order of ~1.5 years; a fully saturated consolidation queue would still take ~1.3 years. Moreover, deposit capacity is also needed for new stake and is thus far from guaranteed to be available for consolidations, as evidenced by the recent inflow of > 1M ETH, fully occupying the queue for ~20 days.

The EIP proposes to address these issues by:

removing the cap on exits, restoring the proportionality of exit churn limit to total stake
increasing the churn limit on exits
introducing a separate consolidation churn limit, since there is no more “excess churn” from having an exit cap, and increase it compared to the current (implicitly defined) one. This also lets us more independently adjust it in the future, for example to increase it if we want to allow for faster consolidation of the validator set or decrease it when this process has already run its course.

The EIP does not propose to lift the cap on the deposit churn, as part of the motivation for introducing it in EIP-7514 still holds today: though active validator set growth is mostly solved by EIP-7251, the validator array in the BeaconState (including inactive validators) is very large and still growing, and too rapid stake growth continues to be a concern as well.

Specification

The CHURN_LIMIT_QUOTIENT is halved, from 2**16 to 2**15, and fully dedicated to activations and exits. However, the cap on activations introduced in EIP-7514 is maintained via MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT, while exits are freed from this cap. Consolidations now have their own dedicated churn, determined by CONSOLIDATION_CHURN_LIMIT_QUOTIENT. This is set here to 2**16, so that consolidations are allocated half as much churn as activations and exits combined, and a third of the total churn. Finally, compute_weak_subjectivity_period is adjusted to account for the asymmetry between exit and activation churn: a unit of exit churn has twice the weak subjectivity effect ($\frac{4}{3}$) of a unit of activation churn $\frac{2}{3}$, and a unit of consolidation churn has an effect equivalent to the sum of the other two ($2$).

Configuration

MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT replaces the existing MAX_PER_EPOCH_ACTIVATION_EXIT_CHURN_LIMIT, also 256, as the cap now only applies to activations. We introduce the new CONSOLIDATION_CHURN_LIMIT_QUOTIENT and update the CHURN_LIMIT_QUOTIENT.

Name	Value
`CHURN_LIMIT_QUOTIENT_GLOAS`	`uint64(2**15)` (= 32,768)
`CONSOLIDATION_CHURN_LIMIT_QUOTIENT`	`uint64(2**16)` (= 65,536)
`MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT`	`uint64(2**8)` (=256)

Churn computations

Due to the intended asymmetry in activation and exit churn, we replace get_activation_exit_churn_limit with get_activation_churn_limit, capped at MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT, and get_exit_churn_limit, uncapped. get_consolidation_churn_limit uses the new CONSOLIDATION_CHURN_LIMIT_QUOTIENT, without either a minimum or a maximum value.

def get_activation_churn_limit(state: BeaconState) -> Gwei:
    """
    Per-epoch churn limit for activations, rounded to EFFECTIVE_BALANCE_INCREMENT.
    """
    churn = max(
        MIN_PER_EPOCH_CHURN_LIMIT_ELECTRA,
        get_total_active_balance(state) // CHURN_LIMIT_QUOTIENT_GLOAS
    )
    churn = churn - churn % EFFECTIVE_BALANCE_INCREMENT
    return min(MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT, churn)

def get_exit_churn_limit(state: BeaconState) -> Gwei:
    """
    Per-epoch churn limit for activations, rounded to EFFECTIVE_BALANCE_INCREMENT.
    """
    churn = max(
        MIN_PER_EPOCH_CHURN_LIMIT_ELECTRA,
        get_total_active_balance(state) // CHURN_LIMIT_QUOTIENT_GLOAS
    )
    return churn - churn % EFFECTIVE_BALANCE_INCREMENT

def get_consolidation_churn_limit(state: BeaconState) -> Gwei:
    """
    Per-epoch churn limit for consolidations (EIP-7521), rounded to EFFECTIVE_BALANCE_INCREMENT.
    """
    churn = get_total_active_balance(state) // CONSOLIDATION_CHURN_LIMIT_QUOTIENT
    return churn - churn % EFFECTIVE_BALANCE_INCREMENT

In compute_weak_subjectivity_period we only replace delta = get_balance_churn_limit(state) with an explicit calculation taking into account the different weak subjectivity effect of each type of operation.

def compute_weak_subjectivity_period(state: BeaconState) -> uint64:
    """
    Returns the weak subjectivity period for the current ``state``.
    This computation takes into account the effect of validator set churn, 
    bounded by the three churn_limit functions used below.
    """
    t = get_total_active_balance(state)
    delta = (
        2 * get_exit_churn_limit(state) // 3 # effect of exit churn
        + get_activation_churn_limit(state) // 3 # effect of activation churn
        + get_consolidation_churn_limit(state) # effect of consolidation churn
    )
    epochs_for_validator_set_churn = SAFETY_DECAY * t // (2 * delta * 100)
    return MIN_VALIDATOR_WITHDRAWABILITY_DELAY + epochs_for_validator_set_churn

Deposit processing

The only modification is replacing get_activation_exit_churn_limit with get_activation_churn_limit, maintaing the current cap on deposit churn respects, while removing the cap from exits. This reverts to the pre-Electra status quo, when activations were capped but exits were not.

def process_pending_deposits(state: BeaconState) -> None:
    next_epoch = Epoch(get_current_epoch(state) + 1)
    # [Modified in Gloas:EIP-8061]
    available_for_processing = state.deposit_balance_to_consume + get_activation_churn_limit(
        state
    )
    processed_amount = 0
    next_deposit_index = 0
    deposits_to_postpone = []
    is_churn_limit_reached = False
    finalized_slot = compute_start_slot_at_epoch(state.finalized_checkpoint.epoch)
    for deposit in state.pending_deposits:
        # Do not process deposit requests if Eth1 bridge deposits are not yet applied.
        if (
            # Is deposit request
            deposit.slot > GENESIS_SLOT
            and
            # There are pending Eth1 bridge deposits
            state.eth1_deposit_index < state.deposit_requests_start_index
        ):
            break
        # Check if deposit has been finalized, otherwise, stop processing.
        if deposit.slot > finalized_slot:
            break
        # Check if number of processed deposits has not reached the limit, otherwise, stop processing.
        if next_deposit_index >= MAX_PENDING_DEPOSITS_PER_EPOCH:
            break
        # Read validator state
        is_validator_exited = False
        is_validator_withdrawn = False
        validator_pubkeys = [v.pubkey for v in state.validators]
        if deposit.pubkey in validator_pubkeys:
            validator = state.validators[ValidatorIndex(validator_pubkeys.index(deposit.pubkey))]
            is_validator_exited = validator.exit_epoch < FAR_FUTURE_EPOCH
            is_validator_withdrawn = validator.withdrawable_epoch < next_epoch
        if is_validator_withdrawn:
            # Deposited balance will never become active. Increase balance but do not consume churn
            apply_pending_deposit(state, deposit)
        elif is_validator_exited:
            # Validator is exiting, postpone the deposit until after withdrawable epoch
            deposits_to_postpone.append(deposit)
        else:
            # Check if deposit fits in the churn, otherwise, do no more deposit processing in this epoch.
            is_churn_limit_reached = processed_amount + deposit.amount > available_for_processing
            if is_churn_limit_reached:
                break
            # Consume churn and apply deposit.
            processed_amount += deposit.amount
            apply_pending_deposit(state, deposit)
        # Regardless of how the deposit was handled, we move on in the queue.
        next_deposit_index += 1
    state.pending_deposits = state.pending_deposits[next_deposit_index:] + deposits_to_postpone
    # Accumulate churn only if the churn limit has been hit.
    if is_churn_limit_reached:
        state.deposit_balance_to_consume = available_for_processing - processed_amount
    else:
        state.deposit_balance_to_consume = Gwei(0)

Exit processing

We replace get_activation_exit_churn_limit with get_exit_churn_limit.

def compute_exit_epoch_and_update_churn(state: BeaconState, exit_balance: Gwei) -> Epoch:
    earliest_exit_epoch = max(
        state.earliest_exit_epoch,
        compute_activation_exit_epoch(get_current_epoch(state))
    )
    # [Modified in Gloas:EIP-8061]
    per_epoch_churn = get_exit_churn_limit(state)
    # New epoch for exits.
    if state.earliest_exit_epoch < earliest_exit_epoch:
        exit_balance_to_consume = per_epoch_churn
    else:
        exit_balance_to_consume = state.exit_balance_to_consume

    # Exit doesn't fit in the current earliest epoch.
    if exit_balance > exit_balance_to_consume:
        balance_to_process = exit_balance - exit_balance_to_consume
        additional_epochs = (balance_to_process - 1) // per_epoch_churn + 1
        earliest_exit_epoch += additional_epochs
        exit_balance_to_consume += additional_epochs * per_epoch_churn

    # Consume the balance and update state variables.
    state.exit_balance_to_consume = exit_balance_to_consume - exit_balance
    state.earliest_exit_epoch = earliest_exit_epoch

    return state.earliest_exit_epoch

Rationale

Independent parameters: a separate churn consolidation is easy to independently tune, in particular adjusted upward if we want to speed up the consolidation process further, and later downward, when the primary wave of validator set consolidation has already happened and the consolidation operation becomes less crucial.
Scaling with stake: the exit churn regains proportionality to the total stake, and the consolidation churn maintains it.
Preserving the activation cap: the activation churn limit maintains the cap from EIP-7514
Balancing security and functionality: the exit churn limit is increased by ~4x compared to the current cap, and exactly 2x compared to previous uncapped version, while the consolidation churn limit is increased by ~2x. Activations remain capped at the existing limit. As we see later in more detail, accounting for the asymmetric impact of exits and activations on safety degradation, this results in a decrease of the weak subjectivity period from ~15.7 days to ~7 days (see detailed calculations below), or ~6 days if we were to later remove the activation cap, in either case still on the order of a week. Moreover, were consolidations to be removed later, the weak subjectivity period would go up to ~11 days, or ~8.4 days without the activation cap.

Backwards Compatibility

This EIP introduces a backwards-incompatible change to the consensus rules and MUST be activated as part of a scheduled network upgrade.

Security Considerations

Weak subjectivity period

Let MIN_VALIDATOR_WITHDRAWABILITY_DELAY = 256 epochs, and let $S$ denote the total stake, $E$ the exit churn per epoch, $A$ the activation churn per epoch, and $C$ the consolidation churn per epoch. Each unit of exit churn contributes to a safety degradation (measured in ETH, as the churn) of $\frac{4}{3}$, whereas the safety degradation from activations is only $\frac{2}{3}$ per unit. Finally, it is $2$ per unit for consolidations, as a consolidation is the equivalent of an exit and an activation.

The formula to compute the weak subjectivity period (in epochs) for a 10% safety decay target (exactly corresponding to compute_weak_subjectivity_period) then is:

$\text{WS}_{\text{epochs}} = 256 + \frac{0.1 \cdot S}{\frac{4}{3} \cdot E + \frac{2}{3} \cdot A + 2 \cdot C}$

The churn limits of the current protocol, assuming a total stake $S = 36M$ ETH (approximately the stake at the time of writing) are:

$A = E = \min(256, S/2^{16}) = 256$ ETH (capped)
$C = S/2^{16} - A \approx 293$ ETH

The weak subjectivity period is then:

$\text{WS}_{\text{epochs}} \approx 3533$

$\Rightarrow\ \textbf{WS} \approx \mathbf{15.7\ \text{days}}$

In days, it is $\text{WS}_{\text{epochs}} / 225$.

Under this EIP, and assuming a total stake $S = 36M$ ETH:

$E = S/2^{15} \approx 1098$ ETH
$A = \min(256, S/2^{15}) = 256$ ETH (capped)
$C = S/2^{16} \approx 549$ ETH

The weak subjectivity period is then:

$\text{WS}_{\text{epochs}} \approx 1573$

$\Rightarrow\ \textbf{WS} \approx \mathbf{7.0\ \text{days}}$

Other possible future scenarios are:

Activation cap removed: $\textbf{WS} \approx \mathbf{6.0\ \text{days}}$ ($\text{WS}_{\text{epochs}} \approx 1348$)
Consolidations disabled: $\textbf{WS} \approx \mathbf{10.9\ \text{days}}$ ($\text{WS}_{\text{epochs}} \approx 2457$)
Consolidations disabled and activation cap removed: $\textbf{WS} \approx \mathbf{8.4\ \text{days}}$ ($\text{WS}_{\text{epochs}} \approx 1894$)

Note that removing the activation cap only reduces the weak subjectivity period by one day, and leaves it on the order of a week. The current parameters might then also be considered acceptable in a future where it is decided to remove the activation cap.

Copyright

Upgrade Mascots

Wed, 29 Oct 2025 00:00:00 +0000

EIP #8066 - Upgrade Mascots is in Last Call status. It is authored by Jordan Holberg (@eviljordan), Andrew B Coathup (@abcoathup) and was originally created 2025-10-29. It is in the category of type Informational. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-8066-upgrade-mascots/26009

Abstract

This EIP establishes a mascot for each Ethereum network upgrade. Mascots serve to humanize and celebrate upgrades, fostering community engagement while adhering to principles of cuteness, relevance, and inclusivity. The mascot is selected through community-driven processes, with safeguards for appropriateness, by a designated facilitator (the “Mascot Wrestler”).

Motivation

Ethereum network upgrades often introduce complex technical changes that can feel abstract to the broader community. Mascots provide a fun, memorable, and relatable symbol for each upgrade, drawing inspiration from its headliners, the namesakes of its layer names, or its client interop events. By mandating emoji-representable mascots that are cute and non-offensive, this process:

Enhances community participation and excitement around network upgrades.
Creates opportunities for creative expression in upgrade event branding (e.g., watch parties, attendance NFTs).
Builds a consistent, whimsical tradition that differentiates Ethereum’s upgrade narrative from other ecosystems.

Specification

1. Mascot Requirements

Relevance: The mascot MUST relate thematically to one or more of the network upgrade’s headliners, the namesakes of the network upgrade’s layer names (e.g., the execution layer city or the consensus layer star), or the client interop events for the network upgrade.
Representation: The mascot MUST be expressible using one or more standard Unicode emojis (e.g., 🐼 for the Merge).
Form: The mascot SHOULD depict an animal (real, mythical, or stylized, but always animal-adjacent).
Tone: The mascot MUST NOT be offensive (no depictions of violence, discrimination, or controversy) and SHOULD be inherently cute (e.g., avoiding aggressive or fearsome traits unless softened for adorability).

2. Roles and Responsibilities

Mascot Wrestler: A self-selected community facilitator responsible for proposing, selecting, and adopting the mascot for a network upgrade. The role MAY rotate voluntarily per upgrade cycle to encourage diverse participation.
- Duties include:
  - Soliciting and curating mascot candidates.
  - Facilitating selection processes.
  - Announcing the final mascot (e.g., Ethereum Magicians, All Core Devs).
Veto Powers:
- The Mascot Wrestler MAY veto any candidate mascot not meeting the mascot requirements above.
- A rough consensus of client teams MAY veto the selected mascot, triggering fallback to the next-highest-ranked candidate mascot.

3. Selection Process

The Mascot Wrestler SHALL conduct selection using one or more community-appropriate mechanisms.

The process MUST:

Run for a minimum of 7 days.
Present at least 2 candidates.
Rank finalists by popularity.
Document results publicly.

If no consensus is reached, the Mascot Wrestler selects the top candidate by default, subject to veto.

4. Usage Guidelines

All uses MUST respect the network upgrade mascot’s cute, non-offensive nature and credit original concept creators where applicable.

Mascots exist to celebrate network upgrades and SHOULD NOT be used to promote speculative tokens (e.g., meme coins).

Rationale

This specification balances creativity with guardrails to prevent mascot drift (e.g., unrelated or edgy choices). Emoji-based representation ensures accessibility across digital platforms, while the animal/cute mandate aligns with Ethereum’s community ethos of approachability. The self-selected Mascot Wrestler role decentralizes coordination, leveraging vetoes for accountability. Selection flexibility accommodates Ethereum’s decentralized governance evolution.

Alternatives considered:

Fully onchain mandates: Too rigid for creative processes.
No formal process: Risks ad-hoc or absent mascots.
Non-animal options: Animals evoke universality and whimsy.

Backwards Compatibility

This EIP does not directly change the Ethereum protocol. It formalizes part of the current network upgrade process. Past upgrades (e.g., Shapella’s owl 🦉) are retroactively honored if they fit the criteria; future upgrades MUST comply starting with the next hard fork post-adoption.

Security Considerations

None

Copyright

eth/72 - Sparse Blobpool

Wed, 29 Oct 2025 00:00:00 +0000

EIP #8070 - eth/72 - Sparse Blobpool is in Last Call status. It is authored by Raúl Kripalani (@raulk), Bosul Mun (@healthykim), Francesco D'Amato (@fradamt), Csaba Kiraly (@cskiraly), Felix Lange (@fjl), Marios Ioannou (@mariosioannou-create), Alex Stokes (@ralexstokes), Kamil Salakhiev (@kamilsa) and was originally created 2025-10-29. It is in the Networking category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-8070-sparse-blobpool/26023

Abstract

This proposal introduces the sparse blobpool, a construction that brings cell-level, custody-aligned sampling in the Execution Layer (EL). For every new type 3 (blob-carrying) transaction, an EL node fetches full blob payloads only with probability p = 0.15, and otherwise it merely samples the blobs, using the same custody assignment as its Consensus Layer (CL) counterpart. For validators, this means downloading as little as 1/8 of the data (8 out of 64 cells), so that the average bandwidth consumption compared to the (current) full blobpool is 0.15 + 0.85/8 ~ 0.25, a ~4x reduction. The choice of p = 0.15 balances reducing bandwidth consumption with guaranteeing the full propagation of txs, by ensuring that for each blob tx there exists a large connected backbone of nodes that have the full blob payload. At an individual node level, p = 0.15 translates to 98.6% probability of least 3/50 neighbours holding the full blob payload, only 0.03% chance of total unavailability. The sampling performed with probability 1 - p = 0.85 enables streamlined data availability checks during block validation, as well as enhancing the availability of the data.

Motivation

As Blob Parameter Only (BPO) forks progressively increase throughput, the full-replication nature of today’s EL blobpool will begin dominating bandwidth utilization, causing us to hit EIP-7870 limits. Furthermore, this traffic will compete, and potentially starve, block and attestation propagation, risking instability and liveness issues. This behavior has already been observed in Fusaka devnets, where the average bandwidth consumption of a full node is dominated by the EL blobpool, since column propagation on the CL benefits from sampling.

Figure 1. Breakdown of the average bandwidth consumption (download) of full nodes in Fusaka Devnet 5, for blob count target/max of 22/33 (left) and 48/72 (right). The average bandwidth consumption of the EL is ~4-5x that of the CL.

While the average bandwidth consumption does not reflect that the load on the EL is spread out over time rather than concentrated in a small time window as it is in the CL, the gap between the EL and CL is quite large (~4-5x), and future upgrades will enable the CL to better spread out data propagation in the slot, leaving the EL blobpool as even more of a bottleneck.

The sparse blobpool mechanism brings sampling to the EL as well, with an anticipated ~4x reduction in average bandwidth consumption for a given blobpool load. In doing so, it preserves the unstructured, stochastic nature of the current blobpool rather than introducing complex sharding architectures, prioritizing simplicity and resilience. Moreover, it preserves the CL’s ability to satisfy its own sampling needs with the pre-propagated data in the EL blobpool (through the getBlobs Engine API). This is achieved by aligning the EL and CL sampling, in particular by having the EL fetch the cells corresponding to the CL custody set. This preserves a key feature of the blobpool, as it stretches the time window for blob data propagation, offloading this work from the critical path of block validation and leading to smoother and less bursty bandwidth utilization patterns over time.

While the scalability gain may be more modest than with other solutions, we believe this design balances between simplicity, security, and scalability, in order to unlock the next tier of blob throughput without requiring user-facing changes, or deeper architectural redesigns.

Specification

Execution clients :: devp2p changes

We introduce a new devp2p protocol version, eth/72 extending the existing eth/71 protocol.

Modify NewPooledTransactionHashes (0x08) message. Add a new field cell_mask of type B_16 (uint128). This field MUST be interpreted as a bitarray of length CELLS_PER_EXT_BLOB, carrying 1 in the indices of columns the announcer has available for all type 3 txs announced within the message. This field MUST be set to nil when no transactions of such type are announced. (TODO: this approach is not expressive enough if the node wants to offer randomly sampled columns, nor if it wants to announce transactions with full and partial availability in a single message).

old schema (eth/71): [types: B, [size_0: P, size_1: P, ...], [hash_0: B_32, hash_1: B_32, ...]]
new schema (eth/72): [types: B, [size_0: P, size_1: P, ...], [hash_0: B_32, hash_1: B_32, ...], cell_mask: B_16]

Modify GetPooledTransactions (0x09) / PooledTransactions (0x0a) behaviour. Responses MUST elide blob payloads for type 3 transactions requested via this RPC by encoding the transaction’s blobs field as the RLP empty list (0xc0, the encoding of []). The field MUST NOT be encoded as the RLP empty byte string (0x80). Cell proofs and commitments are unaffected and continue to be sent.

old schema (eth/71): [request_id: P, [tx_0, tx_1, ...]], where type 3 transactions are encoded as 0x03 || rlp([tx_payload_body, wrapper_version, blobs, commitments, cell_proofs])
new schema (eth/72): [request_id: P, [tx_0, tx_1, ...]], where type 3 transactions are encoded as 0x03 || rlp([tx_payload_body, wrapper_version, [], commitments, cell_proofs])

New message type GetCells (0x14). Used to request cells for type 3 transactions. It specifies the transaction hashes being requested, along with a cell_mask specifying which cell indices are needed, with syntax identical as cell_mask in NewPooledTransactionHashes.

eth/72: [[hash_0: B_32, hash_1: B_32, ...], cell_mask: B_16]

New message type Cells (0x15). Used to respond to a GetCells requests.

eth/72: [[hash_0: B_32, hash_1: B_32, ...], cells: [[cell_0_0: B_2048, cell_0_1: B_2048, ...], [cell_1_0: B_2048, cell_1_1: B_2048, ...]], cell_mask: B_16]

Execution clients :: Blobpool behavior

New transaction hash. Upon receiving a NewPooledTransactionHashes announcement containing a previously unknown type 3 transaction hash, the node makes a probabilistic decision about fetching the blob payload: it decides to fetch the full blob payload with probability p = 0.15 (provider role), or simply sample otherwise (sampler role). This decision MAY be remembered for some period chosen by the implementer, in which case stateless heuristics are RECOMMENDED (e.g. calculating a hash by appending some time-bound value mixed in with stable transaction properties, and applying p to it).

Provider role. If the node is a provider, and the announcing peer signaled full availability, the node MUST request the signed transaction and full blob data from that peer via GetPooledTransactions and GetCells with an all-ones cell_mask bitmap. Upon successful retrieval and validation (as per EIP-7594), the node MUST in turn announce the transaction hash to its peers via NewPooledTransactionHashes, also with an all-ones cell_mask.

Sampler role. If the node is a sampler, the node MUST only request the transaction payload via GetPooledTransactions. It SHOULD await to observe at least 2 distinct provider announcements, and to successfully receive and validate the signed transaction, before acting further. It then MUST request custody-aligned cells from peers that announced overlapping availability, including providers. When fetching from a provider, the node MUST request C_extra random columns in addition to its custody set (see “Sampling noise” in Rationale). The responder MAY truncate its Cells response depending on its current capacity, returning fewer cells than requested.

Ensuring fairness. Nodes MAY keep a record of the frequency of full payload fetches made by each peer, relative to their sampling requests. Nodes MAY elect to disconnect peers who exceed some locally-determined fairness heuristic. Such heuristics are not object of standardization.

Supernode behaviour. Supernodes (nodes intending to fetch every blob payload in full) MUST load balance requests across samplers and providers. Furthermore, supernodes SHOULD prioritize reconstructing blobs and proofs from 64 columns. Supernodes SHOULD maintain a larger peerset in order to satisfy their increased blob fetching needs without over-stressing a small set of neighbours and violating fairness.

Sampler eviction A sampler MAY drop a transaction if it has not observed sufficient network saturation (i.e., announcements from other peers for the same blob) within a defined period.

Continued sampling Tenured transactions MAY be subject to resampling in order to test for liveness and confirm confidence of continued network-wide availability.

Execution clients :: Local block builders

Eager mode for block builders. By default block builder SHOULD permanently act in eager mode: it acts as a provider (p = 1.0) for every type 3 transaction it intends to include, fetching the full blob payload. This guarantees that the builder holds complete blob data for all transactions in the payload.

A builder MAY choose to act as a provider with p = 0.15 probability, and switch to eager mode 2-3 slots prior to block building. But this is not recommended as this creates a clear pattern for the builder’s networking behavior and compromises its privacy, increasing the risk of DoS attacks against it.

Engine API extensions

Method engine_forkchoiceUpdatedV4

This EIP extends engine_forkchoiceUpdatedV4 as defined in the Amsterdam Engine API specification by adding an optional custodyColumns parameter, allowing the CL to inform the EL of its current blob column custody set.

Request:

method: engine_forkchoiceUpdatedV4
params:
1. forkchoiceState: ForkchoiceStateV1.
2. payloadAttributes: Object|null - Instance of PayloadAttributesV4 or null.
3. custodyColumns: DATA|null - 16-byte value interpreted as a bitarray of length CELLS_PER_EXT_BLOB, where a 1 at position i indicates the CL node has custody of column i. null if the CL is unable to provide an update.
timeout: 8s

Response:

Refer to the response for engine_forkchoiceUpdatedV3.

Specification:

CL MUST include a custodyColumns value after startup or when its columns custody set changes. It MUST also resend it after any Engine API interruption or reconnection.
EL MUST return an Ok response if the request is well-formed. All subsequent sampling requests MUST adopt the new custody set. Queued sampling requests MAY be patched to reflect the new custody set.
For type 3 transactions pending in the blobpool:
1. If the custody set has expanded relative to the previously known set, the Execution client MUST issue new sampling requests for the delta columns. It SHOULD broadcast updated NewPooledTransactionHashes announcements reflecting the expanded available set when act as a sampler.
2. If the custody set has contracted, the Execution client MAY prune dropped cells from local storage, but only AFTER broadcasting an updated NewPooledTransactionHashes announcement with the reduced available set, to avoid peers perceiving availability fault.
The Execution client MUST treat a custodyColumns value identical to the current custody set or a null value as a no-op with respect to blobpool state, while still processing the rest of the forkchoice update normally.

Method engine_getBlobsV4

Called by the Consensus layer client to retrieve blob cells from the Execution layer blobpool.

Request:

method: engine_getBlobsV4
params:
- versioned_blob_hashes: []bytes32, an array of blob versioned hashes.
- indices_bitarray: uint128, a bitarray denoting the indices of the cells to retrieve.
timeout: 500ms

Response:

result: []BlobCellsAndProofsV1
error: code and message set in case an error occurs during processing of the request.

Data structure BlobCellsAndProofsV1

blob_cells: a sequence of byte arrays []bytes representing the partial matrix of the requested blobs, with nil entries for missing cells.
proofs: Array of DATA - Array of KZGProof as defined in EIP-4844, 48 bytes each (DATA)

Parameters

Fetching probability: p = 0.15
Mesh degree: D = 50 (default peerset size)
Sampling requirement: Minimum SAMPLES_PER_SLOT = 8 columns per node as per PeerDAS specification
Reconstruction threshold: 64 cells required for Reed-Solomon decoding
Minimum providers to sample: minimum 2 providers should be observed before sampling
Extra random columns per request: C_extra = 1

Rationale

Parameter selection

The choice of p = 0.15 balances bandwidth reduction with availability guarantees. Mathematical analysis for a mesh degree D = 50 shows:

Primary reliability: Probability of having at least 3 peers with complete blob payload is 98.6%
Secondary reliability: Via reconstruction from partial availability, recovery probability exceeds 80% when 6+ provider peers exist.
Total unavailability: Only 0.03% chance with these parameters.

Reliability framework

Primary reliability. Let $X$ be the number of direct peers with the full payload. With $X∼Binomial(D,p)$, the probability that at least $k$ honest peers hold the full blob payload for a type 3 tx is:

\[P(X \geq k) = 1 - \sum_{i=0}^{k-1} \binom{D}{i} p^i (1-p)^{D-i}\]

Evaluating for sensible values of $p$ and $k$ yields, where $D=50$ (Geth’s default mesh degree):

$p$	$k = 6$	$k = 5$	$k = 4$	$k = 3$	$k = 2$	$k = 1$	$P(0)$
0.05	0.037776	0.103617	0.239592	0.459467	0.720568	0.923055	0.076945
0.08	0.208126	0.371050	0.574704	0.774026	0.917288	0.984534	0.015466
0.10	0.383877	0.568802	0.749706	0.888271	0.966214	0.994846	0.005154
0.125	0.606513	0.765366	0.886232	0.958237	0.989739	0.998740	0.001260
0.15	0.780647	0.887895	0.953953	0.985811	0.997095	0.999704	0.000296
0.20	0.951973	0.981504	0.994344	0.998715	0.999807	0.999986	0.000014

Secondary reliability. Probability that a payload can be reconstructed from partial availability when primary reliability fails. Let $Y$ be the number of distinct columns available from sampler peers. Given $k$ provider peers that failed to serve the full payload, a node with $D - k$ sampler peers (each holding 8 random columns, assuming they’re all minimal custody full nodes) can reconstruct with probability $P(Y \geq 64 \mid n = D - k)$. For the adversarial scenario where we attained $k = 3$, yet all failed to serve the blob data, with $D = 50$, secondary reliability exceeds 99.9% as samplers provide an expected 124 distinct columns from 47 peers.

Providers ($k$)	Samplers ($n=D-k$)	$E[Distinct Columns]$	$P(Y ≥ 64)$
0	50	125.1	>99.99%
1	49	124.9	>99.99%
2	48	124.6	>99.99%
3	47	124.3	>99.99%
4	46	124.0	>99.99%
…	…	…	…
~40	~10	~68	~80%

Minimum threshold: Approximately $n_{\min} \approx 10$ samplers needed for reasonable reconstruction probability (>80%).

Backwards Compatibility

This EIP changes the eth protocol and requires rolling out a new version, eth/72. Supporting multiple versions of a wire protocol is possible. Rolling out a new version does not break older clients immediately, since they can keep using protocol version eth/71.

This EIP does not change consensus rules and does not strictly require a hard fork. We are assessing the gradual rollout possibilities. In the meantime, it is RECOMMENDED that this EIP be deployed within the context of a hard fork.

Test Cases

TBD

Security Considerations

Attack scenarios and threat model

The goal of threat modeling is to identify potential attack vectors and vulnerabilities in the proposed sparse blobpool mechanism that may hurt the security, availability, or integrity of the type 3 transaction propagation. The threat model assumes a permissionless environment where adversaries can freely join the network, create multiple identities (Sybil attacks), and behave maliciously. Adversaries may aim to disrupt the network, degrade performance, censor transactions, or manipulate the availability of blob data. Below are some potential attack scenarios and their implications:

DoS attacks. An important consideration in all mempool sharding mechanisms is the possibility of DoS attacks. This refers to the case where a malicious sender posts a transaction to the mempool disclosing only part of it, which makes the transaction impossible to be included in any future block, while still consuming mempool resources. In this system, such a sender can be detected by nodes that request the full payload of the transaction.

Selective withholding attacks. A malicious peer might selectively withhold full blob data for certain type 3 transactions (e.g. produced by a certain L2), thus slowing down their propagation and potentially leading to reduced availability. This can be mitigated by ensuring a sufficiently large and diverse peerset.

Eclipse attacks. Malicious peers can try to isolate a victim node by controlling all its connections, serving only partial blob data and preventing it from obtaining the full payload. This hurts the victim’s ability to propagate transactions and can lead to reduced availability of blob data and potential censorship of the honest peer. However, periodic rotation of connections and keeping track of neighbor peer’s rate of full payload announcements can help mitigate this attack.

Free rider attacks. A peer can send an excessive volume of blob data requests without reciprocating with announcements, thus consuming bandwidth without contributing to the network. This can be mitigated by keeping track of the requests to announcements ratio of peers and disconnecting those that exceed a certain threshold.

Peer disconnection policies

Nodes MAY keep a record of the frequency of full payload and column requests made by each peer. If a frequency exceeds some quota or the probabilistic expectation by some tolerance threshold, the node MAY decide to disconnect the offending peer alleging abuse as a reason. This prevents nodes from spending too much upload bandwidth on peers that fetch full payloads much more often that the expected p = 0.15.

The need for sampling noise

Custody-aligned sampling generates in stable and predictable request patterns that attackers could game. For example, a malicious node may trick a victim by pretending to be a provider when in reality it only stores the few, predictable columns the victim is expected to sample. To defend against this, this EIP introduces the simple mechanism of “sampling noise.”

When a peer requests its custody columns from a provider, it must also request at least ONE randomly selected column. A failure to serve this extra column can be interpreted as a strong sign of misbehavior. The attacker could choose to timeout, but after a number of repetitions, the victim would likely disconnect anyway due to high failure rates.

This simple mechanism reinforces key model assumptions (a provider is truly a provider) in exchange for negligible overhead per request (MAX_BLOBS_PER_TX x CELL_SIZE + proofs = ~12KiB).

No normative peer scoring

An earlier design considered a peer scoring system to grade peers by tracking their statistical ratio of requests to announcements (leechiness vs. helpfulness). After careful consideration, we deemed this approach brittle and dropped the feature. Our rationale was that such mechanism would strongly encode assumptions and confine the system to conform to some modellic behaviour, thus reducing flexibility and resilience in the face of environmental changes, shocks, or unexpected/improbable events (properties that are crucial in open and permissionless systems). Instead, we defer to implementations to define their own local heuristics for peer disconnection, if any.

devp2p message schema choices

We note that cell_mask field in NewPooledTransactionHashes is not expressive enough to signal different local availability for type 3 txs announced within the same message. This limitation implies that (a) fully and partially available txs cannot be announced together, and (b) availability of randomly sampled columns cannot be signaled in practice (because indices vary per tx), only custody columns can be consistently announced (they’re shared across all sampled transactions).

Nevertheless, the sender can efficiently split and group announcements: fully-available txs can be bundled together, and partially-available txs can be announced in separate messages. Per-message dispatch overhead is minimal (one uint64 request_id and one uint8 message_type), and more expressive designs are likely to incur in higher overhead. Furthermore, from a protocol flow perspective, devp2p supports concurrent requests and unordered responses (via request_id correlation), so this approach is not affected by head-of-line blocking either (at least from a protocol perspective).

We considered more expressive designs, ranging from simple arrays of cell_masks (one per tx), to union types express full availability more compactly, to more complex schemes involving run-length encoding and compression. But we concluded that the added complexity was not justified at this time.

Open points

Further threat modelling and security hardening.
RBF (replace-by-fee) impact.

Copyright

Cell-Level Deltas for Data Column Broadcast

Thu, 23 Jan 2025 00:00:00 +0000

EIP #8136 - Cell-Level Deltas for Data Column Broadcast is in Last Call status. It is authored by Marco Munizaga (@MarcoPolo) , Daniel Knopik (@dknopik) , Sukun Tarachandani (@sukunrt) , Aarsh Shah (@aarshkshah1992) and was originally created 2025-01-23. It is in the Networking category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-8136-cell-level-deltas-for-data-column-broadcast/27675

Abstract

Cell-Level Deltas for Data Column Broadcast optimizes PeerDAS (EIP-7594) by allowing more efficient transfers of blob data columns across the network. Instead of having to exchange full data columns, peers exchange only the cells they need within a column. This becomes especially useful when the majority of cells within a column are already present from the local mempool. This optimization is backwards compatible and can be progressively deployed. It does not require a hard fork. Nodes that do not implement this optimization still receive and transmit full data columns.

Motivation

In the vast majority of cases, all or nearly all blobs referenced in a block are available in the mempool. Leveraging the blob data a node already has locally lets a node avoid wasting bandwidth for cells it already has. In the current design, if even a single blob is not present in the local mempool, the Consensus Layer will have to wait to receive the full data column from the network before passing its data availability checks. With this optimization, the client need only wait to receive the missing cells.

Specification

Cell-Level Deltas uses Gossipsub’s Partial Messages Extension to exchange cell bitmaps and request/provide cells.

In an effort to maintain a single source of truth, the specification is defined in the ethereum/consensus-specs repo.

Rationale

The design is guided by two main factors:

Minimal semantic changes.
Backwards compatible (no hard fork required).

These two factors lead the design into something that extends the existing gossipsub behavior rather than introducing a new protocol. The mesh and gossip properties of gossipsub are unchanged. If a node’s gossipsub peers support this extension they can both make use of it. Otherwise, the behavior falls back to traditional gossipsub.

The biggest difference the extension introduces is defaulting to a pull-based dissemination strategy of cells rather than a push based one. Eager pushing of data is still possible, but it is not the default behavior.

Alternative Designs

Smaller gossipsub messages.

This design makes the gossipsub message unit be a single cell rather than a full column. While it would transfer data at the cell level, without having bitmaps as a first class concept it would introduce overhead for a cell per message. Furthermore, informing peers about cells a node has (via IDONTWANT) would always race against the peers pushing the same cells to the node. The default-push strategy is too aggressive for the case when almost all blobs are public. The message ID is content based (e.g. a hash), and lacks context as to what block this cell is part of, making it impossible for a node to request cells it doesn’t have or prioritize cells from a block it’s processing.

Changing the semantics of the message ID may be possible as a workaround for some of the above issues, but this would still require a separate gossipsub topic that could not be used as a backwards compatible replacement to the existing gossipsub topic. Changing message ID semantics may also break gossipsub implementations that assume a message ID and message are 1:1.

A new RPC method.

This seems like the simplest option at first glance, but it ignores the work already happening in gossipsub. If we merely add a new RPC method with no gossipsub changes, we risk only increasing network and compute load rather than reducing it. Because we are now doing an extra RPC on top of existing gossipsub work. To fix this, gossipsub and the RPC method need to be cognizant of each other. Eventually this leads to the proposed design, a gossipsub extension of partial messages with application defined semantics.

A new protocol separate from gossipsub.

While this may be a long term direction worth exploring, this is deemed too big a change to make to leverage this optimization. Especially if we’d like to deploy this without a hard fork.

Backwards Compatibility

No backward compatibility issues.

Nodes form gossipsub meshes and gossip with the same rules as before. This optimization only takes effect when both nodes in a gossipsub exchange support this extension. If either side does not support this extension, both nodes behave the same as before, exchanging full gossipsub messages to each other.

Gossipsub scores peers well if they provide timely messages, and penalizes peers if they provide invalid messages. This extension does not change that, peer scores should behave the same with and without this extension.

Security Considerations

In the default case, this adds minor latency to cell dissemination compared to the standard gossipsub’s default push behavior in exchange for more efficient bandwidth usage. However, over time the eager cell push policy of nodes can be refined to match and even improve dissemination latency. This latency is a key metric that will be monitored during and after rollout.

There are also a couple implementation specific pitfalls client implementers and gossipsub implementers should be aware of.

While it is more efficient for a node to mesh with peers that support this EIP, it risks dividing the network if those peers are preferred. Implementations SHOULD NOT discriminate against peers that do not support this extension.
Related to the above, a peer’s score should be roughly equivalent whether they support partial messages or not. A peer should not score higher if they provide cells one at a time versus all at once.
Implementations should be resilient to peers spamming messages with different Group IDs. Implementations SHOULD reserve space for mesh peer messages in case of adversarial non-mesh peers.

This optimization is expected to roll out gradually with the ability to roll back if needed.

Copyright

Facet-Based Diamonds

Sat, 07 Feb 2026 00:00:00 +0000

EIP #8153 - Facet-Based Diamonds is in Last Call status. It is authored by Nick Mudge (@mudgen) and was originally created 2026-02-07. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/erc-8153-facet-based-diamonds/27685

Abstract

A diamond is a proxy contract that delegatecalls to multiple implementation contracts called facets.

Diamond contracts were originally standardized by ERC-2535. This ERC builds on that foundation by defining a facet-based architecture in which facets self-describe their function selectors through a standardized introspection interface.

By moving selector discovery on-chain, this approach eliminates the need for off-chain selector management. As a result, diamond deployment and upgrades become simpler, more deterministic, and more gas efficient.

This ERC introduces a facet introspection function, exportSelectors(), which every facet MUST implement. This function returns the list of function selectors implemented by the facet, allowing a diamond to discover and register selectors on-chain during deployment or upgrade.

This ERC also defines facet-based events for adding, replacing, and removing facets.

Additionally, the ERC defines an optional upgradeDiamond function. This function uses exportSelectors() to automatically determine which selectors should be added, replaced, or removed when applying facet changes.

Motivation

Motivation for Diamond Contracts

Through a single contract address, a diamond provides functionality from multiple implementation contracts (facets). Each facet is independent, yet facets can share internal functions and storage. This architecture allows large smart-contract systems to be composed from separate facets and presented as a single contract, simplifying deployment, testing, and integration with other contracts, off-chain software, and user interfaces.

By decomposing large smart contracts into facets, diamonds can reduce complexity and make systems easier to reason about. Distinct areas of functionality can be isolated, organized, tested, and managed independently.

Diamonds combine the single-address convenience of a monolithic contract with the modular flexibility of distinct, integrated contracts.

This architecture is well suited to immutable smart-contract systems, where all functionality is composed from multiple facets at deployment time and permanently fixed thereafter.

For upgradeable systems, diamonds enable incremental development: new functionality can be added, and existing functionality modified, without redeploying unaffected facets.

Additional motivation and background for diamond-based smart-contract systems can be found in ERC-1538 and ERC-2535.

Motivation for this Standard

In the past, deploying and upgrading diamonds suffered from:

High gas costs
Function selector management complexity Deploying or upgrading a diamond requires assembling function selectors off-chain. Since common tooling (e.g., Hardhat, Foundry) does not natively manage diamond selectors, developers rely on custom scripts or third-party libraries to handle diamond “plumbing”.

This standard reduces gas costs and eliminates off-chain selector management:

Diamonds become less expensive to deploy.
Function selectors no longer need to be gathered off-chain.
Standard deployment tools can be used without special diamond support.
ERC-2535 introspection functions have simple implementations.

Specification

Terms

A diamond is a smart contract that routes external function calls to one or more implementation contracts, referred to as facets. A diamond is stateful: all persistent data is stored in the diamond’s contract storage. A diamond implements the requirements in the Implementation Requirements section.
A facet is a smart contract that defines one or more external functions. A facet is deployed independently, and one or more of its functions are added to one or more diamonds. A facet’s functions are executed in the diamond’s context via delegatecall, so reads/writes affect the diamond’s storage. The term facet is derived from the diamond industry, referring to a flat surface of a diamond.
An introspection function is a function that returns information about the facets and/or functions used by a diamond or facet.
For the purposes of this specification, a mapping refers to a conceptual association between two items and does not refer to a specific implementation.

Diamond Diagram

This diagram shows the structure of a diamond.

It shows that a diamond has a mapping from function to facet and that facets can access the storage inside a diamond.

Fallback

When an external function is called on a diamond, its fallback function is executed. The fallback function determines which facet to call based on the first four bytes of the calldata (known as the function selector) and executes the function from the facet using delegatecall.

A diamond’s fallback function and delegatecall enable a diamond to execute a facet’s function as if it were implemented by the diamond itself. The msg.sender and msg.value values do not change and only the diamond’s storage is read and written to.

Here is an example of how a diamond’s fallback function might be implemented:

error FunctionNotFound(bytes4 _selector);

// Executes function call on facet using `delegatecall`.
// Returns function call return data or revert data.
fallback() external payable {
    // Get facet address from function selector
    address facet = selectorToFacet[msg.sig];
    if (facet == address(0)) {
        revert FunctionNotFound(msg.sig);
    }
    // Execute external function on facet using `delegatecall` and return any value.
    assembly {
        // Copy function selector and any arguments from calldata to memory.
        calldatacopy(0, 0, calldatasize())
        // Execute function call using the facet.
        let result := delegatecall(gas(), facet, 0, calldatasize(), 0, 0)
        // Copy all return data from the previous call into memory.
        returndatacopy(0, 0, returndatasize())
        // Return any return value or error back to the caller.
        switch result
        case 0 {revert(0, returndatasize())}
        default {return (0, returndatasize())}
    }
}

Function Not Found

If the fallback function cannot find a facet for a function selector, and there is no default function or other mechanism to handle the call, the fallback MUST revert with the error FunctionNotFound(bytes4 _selector).

Inspecting Diamonds

A diamond implementing this standard MUST implement the same introspection functions as defined in ERC-2535. Specifically, these functions MUST be implemented:

interface IDiamondInspect {
    struct Facet {
        address facetAddress;
        bytes4[] functionSelectors;
    }

    /// @notice Gets all facet addresses and their four byte function selectors.
    /// @return facets_ Facet
    function facets() external view returns (Facet[] memory facets_);

    /// @notice Gets all the function selectors supported by a specific facet.
    /// @param _facet The facet address.
    /// @return facetFunctionSelectors_
    function facetFunctionSelectors(address _facet) external view returns (bytes4[] memory facetFunctionSelectors_);

    /// @notice Get all the facet addresses used by a diamond.
    /// @return facetAddresses_
    function facetAddresses() external view returns (address[] memory facetAddresses_);

    /// @notice Gets the facet that supports the given selector.
    /// @dev If facet is not found return address(0).
    /// @param _functionSelector The function selector.
    /// @return facetAddress_ The facet address.
    function facetAddress(bytes4 _functionSelector) external view returns (address facetAddress_);
}

Typically, these functions are implemented in a facet and the facet is added to diamonds.

Each facet MUST implement the following pure introspection function:

interface IFacet {
    function exportSelectors() external pure returns (bytes memory selectors);
}

exportSelectors() returns a bytes array containing one or more 4-byte function selectors. The returned bytes array length MUST be a multiple of 4, and each 4-byte chunk is a selector. The function MUST NOT return a specific selector more than once.

The bytes array contains selectors of functions implemented by the facet that are intended to be added to a diamond.

This enables a diamond to discover selectors directly from facets at deployment or upgrade time. A diamond calls exportSelectors() on each facet to determine which selectors to add, replace, or remove.

Selector gathering is therefore no longer an off-chain responsibility.

This also means diamonds implementing this ERC are facet-based rather than function-based. Deployment and upgrades operate on facets.

This ERC replaces ERC-2535’s function-based events with facet-based events.

When facets are added, replaced, or removed, the diamond MUST emit the following events:

 /**
  * @notice Emitted when a facet is added to a diamond.
  * @dev The function selectors this facet handles can be retrieved by calling
  *      `IFacet(_facet).exportSelectors()`
  *
  * @param _facet The address of the facet that handles function calls to the diamond.
  */
event FacetAdded(address indexed _facet);

/**
 * @notice Emitted when an existing facet is replaced with a new facet.
 * @dev
 * - Selectors that are present in the new facet but not in the old facet are added to the diamond.
 * - Selectors that are present in both the new and old facet are updated to use the new facet.
 * - Selectors that are not present in the new facet but are present in the old facet are removed from
 *   the diamond.
 *
 * The function selectors handled by these facets can be retrieved by calling:
 * - `IFacet(_oldFacet).exportSelectors()`
 * - `IFacet(_newFacet).exportSelectors()`
 *
 * @param _oldFacet The address of the facet that previously handled function calls to the diamond.
 * @param _newFacet The address of the facet that now handles function calls to the diamond.
 */
event FacetReplaced(address indexed _oldFacet, address indexed _newFacet);

/**
 * @notice Emitted when a facet is removed from a diamond.
 * @dev The function selectors this facet handles can be retrieved by calling
 *      `IFacet(_facet).exportSelectors()`
 *
 * @param _facet The address of the facet that previously handled function calls to the diamond.
 */
event FacetRemoved(address indexed _facet);

Block explorers and other tooling can obtain the function selectors for any of the facets referenced by these events by calling exportSelectors() on the facet address.

Optional Events

Recording Non-Fallback `delegatecall`s

This event is OPTIONAL, except upgradeDiamond functions MUST emit it as specified in this standard.

This event can be used to record delegatecalls made by a diamond.

This event MUST NOT be emitted for delegatecalls made by a diamond’s fallback function when routing calls to facets. It is only intended for delegatecalls made by functions in facets or a diamond’s constructor.

This event enables tracking of changes to a diamond’s contract storage caused by delegatecall execution.

/**
* @notice Emitted when a diamond's constructor or function from a
*         facet makes a `delegatecall`. 
* 
* @param _delegate         The contract that was the target of the `delegatecall`.
* @param _delegateCalldata The function call, including function selector and 
*                          any arguments.
*/
event DiamondDelegateCall(address indexed _delegate, bytes _delegateCalldata);

Diamond Metadata

This event is OPTIONAL, except upgradeDiamond functions MUST emit it as specified in this standard.

This event can be used to record versioning or other information about diamonds.

It can be used to record information about diamond upgrades.

/**
* @notice Emitted to record information about a diamond.
* @dev    This event records any arbitrary metadata. 
*         The format of `_tag` and `_data` are not specified by the 
*         standard.
*
* @param _tag   Arbitrary metadata, such as a release version.
* @param _data  Arbitrary metadata.
*/
event DiamondMetadata(bytes32 indexed _tag, bytes _data);

Implementation Requirements

A facet-based diamond MUST implement the following:

Diamond Structure
- A fallback() function.
Function Association
- It MUST associate function selectors with facet addresses.
Function Execution
- When an external function is called on a diamond:
  - The diamond’s fallback function is executed.
  - The fallback function MUST find the facet associated with the function selector.
  - The fallback function MUST execute the function on the facet using delegatecall.
  - If no facet is associated with the function selector, the diamond MAY execute a default function or apply another handling mechanism.
  - If no facet, default function, or other handling mechanism exists, execution MUST revert with the error FunctionNotFound(bytes4 _selector).
Events
- The following events MUST be emitted:
  - FacetAdded — when a facet is added to a diamond.
  - FacetReplaced — when a facet is replaced with a different facet.
  - FacetRemoved — when a facet is removed from a diamond.
Diamond Introspection
- A diamond MUST implement the following introspection functions:
  - facets()
  - facetFunctionSelectors(address _facet)
  - facetAddresses()
  - facetAddress(bytes4 _functionSelector)
Facet Introspection
- Each facet MUST implement the exportSelectors() function, which returns a bytes array.

`receive()` Function

A diamond MAY have a receive() function.

`upgradeDiamond` Function

Implementing upgradeDiamond is OPTIONAL.

This function is specified for interoperability with tooling (e.g., GUIs and command-line tools) so that upgrades can be executed with consistent and predictable behavior.

upgradeDiamond adds, replaces, and removes any number of facets in a single transaction. It can also optionally execute a delegatecall to perform initialization or state migration.

The upgradeDiamond function works as follows:

Call exportSelectors() on the facet to obtain its function selectors.
Add each selector to the diamond, mapping it to the facet address.

Call exportSelectors() on the old facet to obtain its function selectors.
Call exportSelectors() on the new facet to obtain its function selectors.
For selectors present in the new facet but not the old facet: add them.
For selectors present in both: replace them to point to the new facet.
For selectors present in the old facet but not the new facet: remove them.

Call exportSelectors() on the facet to obtain its function selectors.
Remove each selector from the diamond.

Errors and Types

/**
 * @notice The upgradeDiamond function below detects and reverts
 *         with the following errors.
 */
error NoSelectorsForFacet(address _facet);
error NoBytecodeAtAddress(address _contractAddress);
error CannotAddFunctionToDiamondThatAlreadyExists(bytes4 _selector);
error CannotRemoveFacetThatDoesNotExist(address _facet);
error CannotReplaceFacetWithSameFacet(address _facet);
error FacetToReplaceDoesNotExist(address _oldFacet);
error DelegateCallReverted(address _delegate, bytes _delegateCalldata);
error ExportSelectorsCallFailed(address _facet);

/**
 * @dev This error means that a function to replace exists in a
 *      facet other than the facet that was given to be replaced.
 */
error CannotReplaceFunctionFromNonReplacementFacet(bytes4 _selector);

/**
 * @notice This struct is used to replace old facets with new facets.
 */
struct FacetReplacement {
    address oldFacet;
    address newFacet;
}

Function Signature

/**
 * @notice Upgrade the diamond by adding, replacing, or removing facets.
 *
 * @dev
 * Facets are added first, then replaced, then removed.
 *
 * These events are emitted to record changes to facets:
 * - `FacetAdded(address indexed _facet)`
 * - `FacetReplaced(address indexed _oldFacet, address indexed _newFacet)`
 * - `FacetRemoved(address indexed _facet)`
 *
 * If `_delegate` is non-zero, the diamond performs a `delegatecall` to
 * `_delegate` using `_delegateCalldata`. The `DiamondDelegateCall` event is
 *  emitted.
 *
 * The `delegatecall` is done to alter a diamond's state or to
 * initialize, modify, or remove state after an upgrade.
 *
 * However, if `_delegate` is zero, no `delegatecall` is made and no
 * `DiamondDelegateCall` event is emitted.
 *
 * If _tag is non-zero or if _metadata.length > 0 then the
 * `DiamondMetadata` event is emitted.
 *
 * @param _addFacets        Facets to add.
 * @param _replaceFacets    (oldFacet, newFacet) pairs, to replace old with new.
 * @param _removeFacets     Facets to remove.
 * @param _delegate         Optional contract to delegatecall (zero address to skip).
 * @param _delegateCalldata Optional calldata to execute on `_delegate`.
 * @param _tag              Optional arbitrary metadata, such as release version.
 * @param _metadata         Optional arbitrary data.
 */
function upgradeDiamond(
    address[] calldata _addFacets,
    FacetReplacement[] calldata _replaceFacets,
    address[] calldata _removeFacets,
    address _delegate,
    bytes calldata _delegateCalldata,
    bytes32 _tag,
    bytes calldata _metadata
) external;

The upgradeDiamond function MUST adhere to the following requirements:

Definitions of events and custom errors referenced below are given earlier in this standard.

Inputs
- _addFacets array of facet addresses to add.
- _replaceFacets array of (oldFacet, newFacet) pairs.
- _removeFacets array of facet addresses to remove.
Execution Order
1. Add facets
2. Replace facets
3. Remove facets
Event Emission
- Every change to a facet MUST emit exactly one of:
  - FacetAdded
  - FacetReplaced
  - FacetRemoved
Error Conditions
- The implementation MUST detect and revert with the specified error when:
  - Adding a selector that already exists: CannotAddFunctionToDiamondThatAlreadyExists.
  - Removing a facet that does not exist: CannotRemoveFacetThatDoesNotExist.
  - Replacing a facet with itself: CannotReplaceFacetWithSameFacet.
  - Replacing a facet that does not exist: FacetToReplaceDoesNotExist.
  - Replacing a selector that exists in the diamond but is mapped to a facet different than the facet being replaced: CannotReplaceFunctionFromNonReplacementFacet.
Facet Validation
- If any facet address contains no contract bytecode, revert with NoBytecodeAtAddress.
- If exportSelectors() is missing, reverts, or cannot be called successfully, revert with ExportSelectorsCallFailed.
- If exportSelectors() returns zero selectors, revert with NoSelectorsForFacet.
Delegate Validation
- If _delegate is non-zero but contains no bytecode, revert with NoBytecodeAtAddress.
Delegatecall Execution
- If _delegate is non-zero, the diamond MUST delegatecall _delegate with _delegateCalldata.
- If the delegatecall fails and returns revert data, the diamond MUST revert with the same revert data.
- If the delegatecall fails and returns no revert data, revert with DelegateCallReverted.
- If a delegatecall is performed, the diamond MUST emit the DiamondDelegateCall event.
- _delegateCalldata MAY be empty. If empty, the delegatecall executes with no calldata.
Metadata Event
- If _tag is non-zero or _metadata.length > 0, the diamond MUST emit the DiamondMetadata event.

After adding, replacing, or removing facets, the diamond MAY perform a delegatecall to initialize, migrate, or clean up state.

It is also valid to call upgradeDiamond solely to perform a delegatecall (i.e., without adding, replacing, or removing any facets).

To skip an operation, supply an empty array for its parameter (for example, new address[](0) for _addFacets).

Rationale

Eliminating Selector Management

To deploy a facet-based diamond implementing this ERC, the deployer provides an array of facet addresses to the diamond constructor. The constructor calls exportSelectors() on each facet and registers those selectors in the diamond.

Because facets self-describe their selectors, deployers no longer need to gather selectors off-chain or depend on specialized selector tooling.

Reducing Deployment Gas Costs

Reducing Calldata

In a non-facet-based diamond, selectors are typically passed to the constructor as one or more bytes4[] arrays. These arrays are paid for in calldata and then copied into memory, incurring additional gas.

In a facet-based diamond, only facet addresses are passed to constructors. The diamond calls exportSelectors() on each facet to obtain selectors on-chain, avoiding calldata costs for selector lists. While calling exportSelectors() introduces some overhead, non-facet-based diamonds typically perform code-existence checks (e.g., extcodesize) on facet addresses anyway, incurring the cold account access gas cost.

Reducing Storage

In a non-facet-based diamond, function selectors are stored directly for introspection, typically in a bytes4[] selectors array (or an equivalent structure). Because a storage slot is 32 bytes, each slot can hold up to eight bytes4 selectors. As more functions are added, additional storage slots are required, so storage usage grows linearly with the number of selectors.

In a facet-based diamond, introspection data can be stored per facet instead of per function. Each facet only needs a single representative selector. This means one 32-byte storage slot can represent up to eight facets, regardless of how many function selectors each facet implements. Storage usage therefore grows with the number of facets, not the number of functions.

Alternatively, a facet-based diamond can be implemented as a linked list of facets. With this design, introspection requires a single 32-byte storage slot, while supporting any number of facets and any number of selectors per facet.

`exportSelectors()` Function Return Value

exportSelectors() returns bytes rather than bytes4[] for two reasons:

`bytes4[]` Wastes Memory

Each element of a bytes4[] array occupies 32 bytes in memory, but only 4 bytes are meaningful. This wastes 87.5% of allocated memory, increasing gas costs. Packing selectors into bytes reduces memory overhead.

Facets can implement exportSelectors() concisely using Solidity’s built-in function bytes.concat. Example:

function exportSelectors() external pure returns (bytes memory) {
    return bytes.concat(
        this.facetAddress.selector,
        this.facetFunctionSelectors.selector,
        this.facetAddresses.selector,
        this.facets.selector
    );
}

The diamond can traverse the returned bytes and extract selectors efficiently.

Diamond Upgrades

The upgrade function specified by this standard is optional.

This means a couple of things:

1. Diamonds Can Be Immutable

A Diamond does not have to have an upgrade function.

A diamond can be fully constructed within its constructor without adding any upgrade function, making it immutable upon deployment.
A large immutable diamond can be built using well organized facets.
A diamond can initially be upgradeable, and later made immutable by removing its upgrade function.

2. You Can Create Your Own Upgrade Functions

You can design and create your own upgrade functions and remain compliant with this standard. All that is required is that you emit the appropriate add/replace/remove events specified in the Facet-Based Events section, and that the introspection functions defined in the Inspecting Diamonds section and the Inspecting Facets section continue to exist and accurately return function and facet information.

Runtime Gas Considerations

Routing calls via delegatecall introduces a small amount of gas overhead. In practice, this cost is mitigated by several architectural and tooling advantages enabled by diamonds:

Optional, gas-optimized functionality
By structuring functionality across multiple facets, diamonds make it straightforward to include specialized, gas-optimized features without increasing the complexity of core logic.
For example, an ERC-721 diamond may implement batch transfer functions in a dedicated facet, improving both gas efficiency and usability while keeping the base ERC-721 implementation simple and well-scoped.
Reduced external call overhead
Some contract architectures require multiple external calls within a single transaction. By consolidating related functionality behind a single diamond address, these interactions can execute internally with shared storage and shared authorization, reducing gas costs from external calls and repeated access-control checks.
Selective optimization per facet
Because facets are compiled and deployed independently, they may be built with different compiler optimizer settings. This allows gas-critical facets to use aggressive optimization configurations to reduce execution costs, without increasing bytecode size or compilation complexity for unrelated functionality.

Storage Layout

Diamonds and facets need to use a storage layout organizational pattern because Solidity’s default storage layout doesn’t support proxy contracts or diamonds. The storage layout technique or pattern to use is not specified in this ERC. However, examples of storage layout patterns that work with diamonds are ERC-8042 Diamond Storage and ERC-7201 Namespaced Storage Layout.

Facets are separately deployed, independent units, but can share state and functionality in the following ways:

Facets can share state variables by using the same structs at the same storage positions.
Facets can share internal functions by importing them or inheriting contracts.

A deployed facet can be used by many diamonds.

It is possible to create and deploy a set of facets that are reused by different diamonds.

The ability to use the same deployed facets for many diamonds has the potential to reduce development time, increase reliability and security, and reduce deployment costs.

It is possible to implement facets in a way that makes them usable/composable/compatible with other facets.

Backwards Compatibility

Diamonds implementing this ERC have the same introspection functions as ERC-2535 diamonds, so they are compatible with ERC-2535 tooling that relies on these functions.

This ERC breaks compatibility with ERC-2535 events and upgrades.

Facets deployed for ERC-2535 diamonds cannot be used with ERC-8153 diamonds if they do not have the exportSelectors() function.

Security Considerations

Arbitrary Execution with `upgradeDiamond`

The upgradeDiamond function allows arbitrary execution with access to the diamond’s storage (through delegatecall). Access to this function must be restricted carefully.

Only trusted and verified facets should be added to facet-based diamonds.

exportSelectors() MUST be pure and should not contain logic that varies the returned bytes. Facets should be immutable so returned selectors cannot change over time.

If a facet’s exportSelectors() output changes, upgrades that rely on it may add/remove/replace the wrong selectors and corrupt diamonds.

Upgrade Integrity Checks

The specified upgradeDiamond behavior prevents a number of upgrade mistakes. Upgrades revert when:

A facet is added that already exists in the diamond.
A facet is replaced or removed that does not exist in the diamond.
A selector is added that already exists in the diamond.
A selector is replaced that exists in the diamond but is mapped to a different facet than the facet being replaced.
A facet address contains no bytecode.
A facet does not implement exportSelectors() successfully.
A facet provides zero selectors.
A facet is replaced with itself (same contract address).

Selector collisions (two different signatures with the same 4-byte selector) are handled as “selector already exists” and are therefore prevented.

Do Not Self Destruct

Use of selfdestruct in a facet is heavily discouraged. Misuse of it can delete a diamond or a facet.

Transparency

A diamond emits an event every time a facet is added, replaced or removed. Source code can be verified. This enables people and software to monitor changes to a diamond.

Security and domain experts can review a diamond’s upgrade history.

Copyright

eth/71 - Block Access List Exchange

Thu, 12 Feb 2026 00:00:00 +0000

EIP #8159 - eth/71 - Block Access List Exchange is in Last Call status. It is authored by Toni Wahrstätter (@nerolation) and was originally created 2026-02-12. It is in the Networking category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-8159-eth-71-block-access-list-exchange/27725

Abstract

This EIP modifies the ‘eth’ p2p protocol to support Block-level Access Lists (BALs). It adds two new messages, GetBlockAccessLists (0x12) and BlockAccessLists (0x13), enabling peers to request and serve BALs for synchronization and parallel execution.

Motivation

EIP-7928 introduces block-level access lists that record all state locations accessed during block execution. These lists enable parallel disk reads, parallel transaction execution, and executionless state updates.

For syncing clients to leverage these capabilities, BALs must be obtainable from peers. The Engine API provides BALs from the consensus layer during normal operation, but historical BALs and peer-based sync require wire protocol support.

Specification

Block Header Extension

The block header is extended with a new field after requests-hash:

block-header = [
    ...
    requests-hash: B_32,
    block-access-list-hash: B_32,
]

The block-access-list-hash field contains keccak256(rlp.encode(block-access-list)) as defined in EIP-7928. This field MUST be present in headers after the Amsterdam fork and absent for earlier blocks.

Block Access List Encoding

BALs are RLP-encoded as a list of account changes, sorted lexicographically by address:

block-access-list = [account-changes₁, account-changes₂, ...]

account-changes = [
    address: B_20,
    storage-changes,
    storage-reads,
    balance-changes,
    nonce-changes,
    code-changes,
]

storage-changes = [slot-changes₁, slot-changes₂, ...]
slot-changes = [slot: P, [storage-change₁, storage-change₂, ...]]
storage-change = [block-access-index: P, value: P]

storage-reads = [slot₁: P, slot₂: P, ...]

balance-changes = [balance-change₁, balance-change₂, ...]
balance-change = [block-access-index: P, balance: P]

nonce-changes = [nonce-change₁, nonce-change₂, ...]
nonce-change = [block-access-index: P, nonce: P]

code-changes = [code-change₁, code-change₂, ...]
code-change = [block-access-index: P, code: B]

storage-changes MUST be sorted by slot ascending. Changes within each slot MUST be sorted by block-access-index ascending. storage-reads MUST be sorted by slot ascending.

Where block-access-index indicates when the change occurred:

0 for pre-execution system contract calls
1...n for transactions (in block order)
n+1 for post-execution system contract calls and withdrawals

See EIP-7928 for complete BAL generation rules and inclusion semantics.

New Protocol Messages

GetBlockAccessLists (0x12)

[request-id: P, [blockhash₁: B_32, blockhash₂: B_32, ...]]

Request BALs for the given block hashes. The number of BALs that can be requested in a single message is subject to implementation-defined limits.

BALs are only available for blocks after EIP-7928 activation and within the retention period defined therein. Requests for unavailable BALs return empty entries.

BlockAccessLists (0x13)

[request-id: P, [block-access-list₁, block-access-list₂, ...]]

Response to GetBlockAccessLists. Each element corresponds to a block hash from the request, in order. The RLP empty string (0x80) is returned for blocks where the BAL is unavailable.

The recommended soft limit for BlockAccessLists responses is 2 MiB.

Validation

When a BAL is received, clients MUST validate it by computing keccak256(rlp.encode(bal)) and comparing against the block-access-list-hash in the corresponding block header.

Rationale

Separate Messages vs. Block Body Extension

BALs are transmitted via dedicated messages rather than extending block bodies because:

Size: BALs average ~70 KiB, significantly increasing block propagation overhead if bundled.
Optional retrieval: Not all sync strategies require BALs. Snap sync can reconstruct state without them.
Retention policy: BALs may be pruned per EIP-7928, while block bodies are retained longer.

Message IDs

Message IDs 0x12 and 0x13 follow sequentially from the existing eth/69 messages (BlockRangeUpdate is 0x11).

Response Size Limit

The 2 MiB soft limit is consistent with other eth protocol responses (blocks, receipts, headers) and accommodates multiple BALs per response. Responses containing a single BAL that exceeds 2 MiB are still valid, as the soft limit governs when to stop appending additional items, not the maximum size of an individual item.

Backwards Compatibility

This EIP changes the eth protocol and requires rolling out a new version, eth/71. Supporting multiple protocol versions is standard practice. Rolling out eth/71 does not break older clients, as they can continue using eth/69 or eth/70.

This EIP requires the Amsterdam hard fork for the header field extension. The new messages are only meaningful for post-Amsterdam blocks.

Security Considerations

Validation Cost

BAL validation requires computing a keccak256 hash of the RLP-encoded list. For typical BALs (~70 KiB), this is negligible. For worst-case BALs at high gas limits, validation remains bounded by the block gas limit.

Amplification

A GetBlockAccessLists request can trigger responses larger than the request. Implementations SHOULD apply rate limiting and respect the soft response size limit to prevent amplification attacks.

Unavailable Data

Clients MUST handle empty responses gracefully. A peer returning empty entries for available blocks may be misbehaving but could also have pruned the data legitimately.

Copyright

snap/2 - BAL-Based State Healing

Fri, 06 Mar 2026 00:00:00 +0000

EIP #8189 - snap/2 - BAL-Based State Healing is in Last Call status. It is authored by Toni Wahrstätter (@nerolation), Gary Rong (@rjl493456442) and was originally created 2026-03-06. It is in the Networking category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-8189-snap-2-bal-based-state-healing/27953

Abstract

This EIP upgrades the snap protocol from version 1 to version 2, removing GetTrieNodes (0x06) / TrieNodes (0x07) and adding GetBlockAccessLists (0x08) / BlockAccessLists (0x09) to enable BAL-based state healing during snap sync.

Motivation

EIP-7928 introduces block-level access lists (BALs) that capture all state changes per block, committed to block headers via block-access-list-hash. With BALs available, the snap sync healing phase — which iteratively fetches individual Merkle trie nodes via GetTrieNodes to resolve state inconsistencies — can be replaced entirely.

Instead of discovering and fetching trie nodes across many round trips, a syncing node downloads BALs for the blocks that advanced during sync and applies state diffs sequentially. Each BAL is verified against its header commitment. The set of blocks to catch up is known upfront, eliminating iterative discovery.

Specification

Protocol Version

The protocol version is incremented from snap/1 to snap/2. Peers negotiate the version during the RLPx capability handshake.

Removed Messages

Message	ID	Reason
`GetTrieNodes`	0x06	Replaced by BAL-based healing
`TrieNodes`	0x07	Replaced by BAL-based healing

New Messages

GetBlockAccessLists (0x08)

[request-id: P, [blockhash₁: B_32, blockhash₂: B_32, ...], bytes: P]

Request BALs for the given block hashes. bytes is the maximum cumulative size of the BAL data the client is willing to receive in a single response. The number of hashes per request is subject to implementation-defined limits.

BALs are only available for blocks after EIP-7928 activation and within the retention period defined therein.

Notes:

Nodes must always respond to the query.
If the node does not have the BAL for a requested block hash, it must return the RLP empty string (0x80) at that position.
The responding node is allowed to return fewer entries than requested (serving the bytes soft limit or Quality of Service (QoS) limits), truncating from the tail. Returned entries must preserve request order.
Nodes should retain BALs for orphaned (non-canonical) blocks within the retention period defined in EIP-7928. Since requests are keyed by block hash, orphaned BALs can be served the same way as canonical ones. Retaining them enables syncing nodes to recover from reorgs past the pivot block without restarting sync.

BlockAccessLists (0x09)

[request-id: P, [block-access-list₁, block-access-list₂, ...]]

Response to GetBlockAccessLists. Each element corresponds positionally to a block hash from the request. The RLP empty string (0x80) is returned for blocks where the BAL is unavailable.

The responding node should respect the bytes limit from the request. In the absence of a specific limit, the recommended soft limit for BlockAccessLists responses is 2 MiB.

Unchanged Messages

Messages 0x00–0x05 (GetAccountRange, AccountRange, GetStorageRanges, StorageRanges, GetByteCodes, ByteCodes) are unchanged from snap/1.

Validation

Received BALs must be validated by computing keccak256(rlp.encode(bal)) and comparing against the block-access-list-hash in the corresponding block header. See EIP-7928 for the BAL encoding format.

Synchronization Algorithm

snap/2 replaces trie healing with BAL-based catch-up:

Download headers and identify the chain head.
Pick a pivot block P sufficiently behind the chain head (e.g., HEAD-64) to reduce the likelihood of P being reorged while remaining recent enough that serving peers still hold its state in memory.
Bulk download state at P via GetAccountRange, GetStorageRanges, GetByteCodes.
If P becomes stale during bulk download (step 3) — i.e., serving peers no longer hold state at P — the syncing node fetches BALs for blocks P+1 through P’ via GetBlockAccessLists (where P’ is the new pivot), applies the diffs locally, and continues bulk download at P’.
While state is being downloaded, the chain advances and the pivot switches from P to a new block P+K (typically K is 64). Because serving peers may no longer retain the state at P once the pivot advances, the syncing node fetches BALs for blocks P+1 through P+K via GetBlockAccessLists, applies the state diffs locally, and immediately uses P+K as the new sync target. Each BAL is verified against its header hash before application.
If the pivot advances further during step 5, repeat for the newly produced blocks.
Recompute and verify the state root against the latest header.

If the chain reorgs past the pivot block P, let W be the common ancestor of the old and new canonical chains. The syncing node collects BALs for blocks W+1 through P on the old fork, identifies state entries mutated on the old fork but not on the new fork, deletes those entries locally, and re-fetches them via GetAccountRange / GetStorageRanges. It then applies BALs from W+1 forward on the new canonical chain and continues sync with a new pivot. If the required orphaned BALs are unavailable, the node must discard state and restart sync.

Rationale

Separate Protocol vs. eth/71

This follows the established snap design philosophy. GetByteCodes was duplicated from eth into snap for the same reason:

This functionality was duplicated into snap from eth/65 to permit eth long term to become a chain maintenance protocol only and move synchronization primitives out into satellite protocols only.

Synchronization primitives belong in satellite protocols. snap is optional and independently versioned; duplicating BAL exchange here avoids coupling sync functionality to eth.

Removing GetTrieNodes

BAL-based healing makes trie node fetching for state reconciliation unnecessary. Removing these messages avoids maintaining two healing mechanisms.

Backwards Compatibility

This EIP requires rolling out a new protocol version, snap/2. Older clients continue using snap/1. snap/2 is only meaningful for post-Amsterdam blocks, since the block-access-list-hash header field (EIP-7928) is absent for earlier blocks.

For a node synchronizing data, if both snap/1 and snap/2 are supported, it should use either snap/1 or snap/2 for state sync; running both simultaneously is not recommended. Once the synchronization phase is complete, the node can serve requests for both protocols.

Security Considerations

Amplification

A GetBlockAccessLists request can trigger responses significantly larger than the request. Implementations should apply rate limiting and respect the 2 MiB soft response limit.

Unavailable Data

Peers returning empty entries for available blocks may be misbehaving or may have pruned data legitimately. Implementations should track peer reliability and deprioritize unreliable peers.

Application Order

BALs must be applied in strict block order with each BAL hash verified before application. Incorrect ordering or wrong-fork BALs produce an invalid state root, detected during the final state root verification.

Copyright

Remove SELFDESTRUCT Burn

Fri, 01 May 2026 00:00:00 +0000

EIP #8246 - Remove SELFDESTRUCT Burn is in Last Call status. It is authored by Paweł Bylica (@chfast) and was originally created 2026-05-01. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-8246-remove-selfdestruct-burn/28416

Abstract

This EIP removes the remaining cases where SELFDESTRUCT burns ETH. Accounts marked for selfdestruction still have their code, storage, and nonce cleared at transaction finalization, but any remaining balance is preserved.

Motivation

The remaining burn behavior of SELFDESTRUCT is almost completely unused, but it still forces special-case handling in EVM implementations, specifications, and tests.

After EIP-6780, ETH can still be burned only when a contract created in the same transaction executes SELFDESTRUCT, either with itself as beneficiary or in a case where the contract receives additional ETH (via CALL or via SELFDESTRUCT, potentially multiple times) later in the same transaction. A full replay of Ethereum mainnet from genesis to approximately block 25M found only 2 post-Cancun burns through this path and 0 cases of balance being burned during transaction finalization. By comparison, pre-Cancun history contained 54 self-burns in total. This indicates that the remaining burn behavior is rarer than the burn behavior already removed by EIP-6780, so the complete removal proposed here should affect fewer transactions than the partial removal already introduced there.

Removing the final burn cases simplifies SELFDESTRUCT semantics and avoids preserving an exotic special case that is barely used in practice.

As a consequence, this also removes the last EVM mechanism by which ETH can leave total supply.

Specification

The behavior of SELFDESTRUCT changes as follows:

When SELFDESTRUCT is executed in the same transaction as the contract was created, and if the beneficiary address is the executing account address, the balance of this account remains unchanged.
During transaction finalization, all accounts marked for selfdestruction, instead of being deleted, are modified as follows:
1. nonce is reset to 0,
2. balance is unchanged,
3. code is cleared,
4. all storage is cleared.

Note: All other behavior of SELFDESTRUCT is unchanged.

Note: If the resulting balance is 0, the account is empty and is deleted from the state by EIP-161.

Rationale

This change removes burn behavior at its source instead of adding dedicated handling for it elsewhere.

The chosen design preserves the state-clearing effect of SELFDESTRUCT for contracts created in the same transaction. The account may still survive in the state, but only as a balance-only account. This removes the special case where ETH disappears from the state while keeping the account non-executable after transaction finalization.

Resetting the nonce to 0 ensures that a future CREATE2 at the same address is not blocked by a preserved balance-only account.

An alternative would be to preserve the whole account, including nonce, code, and storage. That would work as a complete SELFDESTRUCT disarming and would remove the burn as well, but it would be a larger semantic change than necessary. This EIP removes only the burn behavior.

Backwards Compatibility

This EIP requires a hard fork, since it modifies consensus rules.

Previously it was possible to burn ETH by executing SELFDESTRUCT in a contract created in the same transaction, either by targeting the executing contract as beneficiary or by sending ETH to the contract after SELFDESTRUCT and before transaction finalization. After this EIP, ETH will not be burned in either case.

Previously such contracts were always deleted at transaction finalization. After this EIP, a contract with zero final balance is still deleted, but a contract with nonzero final balance remains in the state as a balance-only account with empty code, empty storage, and nonce 0.

For the balance-only accounts created this way, CREATE2 still may recreate a contract at the same address in a follow-up transaction. Such a usage pattern remains operational.

For contracts not created in the same transaction in which SELFDESTRUCT is executed, the behavior is unchanged from EIP-6780.

Unlike Mainnet, some L2 chains use the burn feature of SELFDESTRUCT regularly and will require a separate migration plan.

In the OP Stack, ETH withdrawn to L1 accumulates in the L2ToL1MessagePasser predeploy at 0x4200000000000000000000000000000000000016. It provides a permissionless burn() function which destroys that balance by creating a contract whose constructor executes SELFDESTRUCT with itself as the beneficiary, so the L2 ETH supply does not inflate. Chains derived from that codebase inherit the dependency unless they modify the predeploy, including those not commonly identified as Optimism-based. Such contracts are deployed with CREATE, so the balance-only accounts they leave behind cannot be recreated by the CREATE2 pattern described above.

Test Cases

Unmodified behavior

General test coverage of the SELFDESTRUCT instruction is expected to be excellent already because this instruction has been modified multiple times in the past. Updating existing test cases to align with this EIP should give us good coverage of all unmodified features of SELFDESTRUCT.

Modified behavior

Each of the following test cases should be executed (where physically meaningful) across the combinations of these factors:

level: top-level transaction, internal call,
call type: CALL (including top-level tx), CREATE (including top-level tx), CREATE2,
code state: SELFDESTRUCT executed inside initcode (before deployment) / from deployed code,
status: SELFDESTRUCT succeeds, SELFDESTRUCT fails due to OOG,
revert: effects of SELFDESTRUCT are committed to the post-state, effects of SELFDESTRUCT are reverted (only for wrapped internal calls),
balance: balance of the selfdestructing account at the SELFDESTRUCT instruction is zero / non-zero.

Instruction level

Same-transaction selfdestruct-to-self.
Same-transaction selfdestruct-to-self, followed by selfdestruct-to-self.
Same-transaction selfdestruct-to-self, followed by selfdestruct-to-other.
Same-transaction selfdestruct-to-other, followed by selfdestruct-to-self.

Transaction finalization

Same-transaction selfdestruct-to-other, followed by a CALL with value to the selfdestructed account.
Same-transaction selfdestruct-to-other, followed by multiple CALLs with value to the selfdestructed account.
Same-transaction selfdestruct-to-other, followed by a CALL with value to the selfdestructed account, followed by selfdestruct-to-other.
Same-transaction selfdestruct-to-other, followed by a CALL with value to the selfdestructed account, followed by selfdestruct-to-self.
Same-transaction selfdestruct-to-self, followed by a CALL with value to the selfdestructed account.
Same-transaction selfdestruct-to-self, followed by multiple CALLs with value to the selfdestructed account.
Same-transaction selfdestruct-to-self, followed by a CALL with value to the selfdestructed account, followed by selfdestruct-to-other.
Same-transaction selfdestruct-to-self, followed by a CALL with value to the selfdestructed account, followed by selfdestruct-to-self.
Create new account, new account creates other accounts to bump its nonce, new account selfdestruct-to-self.
Create new account, new account creates other accounts to bump its nonce, new account selfdestruct-to-other.
Create new account, new account adds new storage, new account selfdestruct-to-self.
Create new account, new account adds new storage, new account selfdestruct-to-other.

Multi-transaction

Tx-1: CREATE2 new account with non-zero balance, new account selfdestruct-to-self. Tx-2: Repeats Tx-1.

Security Considerations

SELFDESTRUCT behavior modification has a combinatorial effect on a vast number of test scenarios involving multi-call/create contract interactions. This EIP requires significant testing effort. However, many existing test cases for EIP-6780 can be adapted to the new behavior.
When a use case relies on the ETH burn happening, the transaction will create dust-like accounts with potentially locked non-zero balance. However, the new account creation gas cost is paid by the transaction, so dust accounts are not a free DoS vector. Only 2 such events have been recorded on Mainnet (Cancun–25M) so far.
Preserving the balance leaves a funded account whose nonce, code and storage are cleared, which makes the address a valid CREATE2 target again (a non-zero balance alone never triggers a creation collision, per EIP-684). The (sender, salt, initcode) of a deployment is public data, so when the sender is a permissionless factory anyone can redeploy the account and potentially take the preserved balance.

Copyright

Gas Limit Schedule

Mon, 11 May 2026 00:00:00 +0000

EIP #8261 - Gas Limit Schedule is in Last Call status. It is authored by Barnabas Busa (@barnabasbusa) and was originally created 2026-05-11. It is in the category of type Informational. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-8261-gas-limit-schedule/28494

Abstract

This EIP recommends that, starting with Gloas (EIP-7732), consensus layer clients source their gas limit preference from an optional GAS_LIMIT_SCHEDULE field in the consensus layer config.yaml instead of hardcoded, release-scoped defaults. Each entry activates at the start of its specified epoch and provides a value that plays two roles: it is the default gas limit that validator clients target in the absence of operator configuration, and the recommended maximum. The schedule is ignored before Gloas, preserving existing gas limit behavior. Operators remain free to configure any value; clients should warn when a configured preference exceeds the active scheduled value, but honor it because the maximum is a recommendation, not a rule. The schedule lives only on the consensus layer because post-Gloas the validator’s preference flows through validator registrations and the builder pipeline, with no execution layer configuration involved. No consensus rules are changed: the EIP-1559 ±1/1024 elasticity rule remains the only gas-limit validity rule, and blocks above or below the scheduled value remain valid.

Motivation

Today the block gas limit is set by each block proposer, driven by validator client “preferred gas limit” settings, client default configurations, and builder bids, with the ±1/1024 elasticity rule from EIP-1559 moving the realized limit block by block.

The pain point this EIP addresses is that gas limit defaults are release-scoped rather than epoch-based: a new default activates whenever an operator happens to update their node, not at a network-coordinated epoch. This creates a concrete coordination problem for large increases. Suppose clients want to raise the default from 60M toward a substantially higher value at a future epoch:

If clients ship the new default in releases ahead of the activation epoch, every node updated early starts voting the gas limit up immediately, before the network has agreed the new value is safe to reach.
The alternative, shipping the new default in a back-to-back release immediately after the intended activation epoch and asking all operators to update quickly, is operationally inconvenient and slow to take effect.
One-off override flags for each planned increase push the coordination burden onto every individual operator.

There is also no single place where “the gas limit the network should run at” is written down: moving the network today requires either every client team shipping a new hardcoded default, or a large share of operators updating flags, coordinated socially over months. EIP-7935 demonstrated that coordinating a default gas limit recommendation at a known epoch works; this EIP generalizes that approach into a reusable, machine-readable schedule, mirroring the epoch-based BLOB_SCHEDULE configuration format from EIP-7892.

With Gloas (EIP-7732), the consensus layer becomes the natural single home for this schedule: the gas limit a block is built to originates from the validator side of the builder flow, so a CL configuration entry can drive the network’s gas limit end to end without any execution layer configuration.

Specification

This EIP changes no consensus rules. The EIP-1559 gas limit validity rules (±1/1024 elasticity, 5000 minimum) are unchanged, and a block whose gas_limit differs from the scheduled value in either direction remains valid. Everything below is recommended client and tooling behavior.

Gas limit schedule

The consensus layer config.yaml MAY be extended with a GAS_LIMIT_SCHEDULE field, mirroring the BLOB_SCHEDULE mechanism in EIP-7892. Entries represent recommended gas limit changes that take effect at the start of the listed epoch:

GAS_LIMIT_SCHEDULE:
  - EPOCH: 500000     # Gloas activation epoch
    GAS_LIMIT: 60000000
  - EPOCH: 520000     # A later scheduled increase
    GAS_LIMIT: 75000000
  - EPOCH: 540000     # Another scheduled increase
    GAS_LIMIT: 90000000

EPOCH and GAS_LIMIT are uint64 values; GAS_LIMIT matches the type of ExecutionPayload.gas_limit in the consensus specifications.

The field is OPTIONAL: CL clients MAY add support for it, and clients that do not recognize it ignore it, per the existing convention for unknown configuration keys. Supporting clients MUST ignore the schedule for duties before GLOAS_FORK_EPOCH. A client that is not using the parameter because the duty is pre-Gloas, the field is absent, or no schedule entry is active simply keeps its existing gas limit behavior.

Each entry independently schedules a recommended gas limit change at its EPOCH. An entry MAY align with a protocol upgrade, but the schedule itself does not create or require a fork.

Define:

def get_scheduled_gas_limit(epoch: Epoch, config: Config) -> Optional[int]:
    if epoch < config.GLOAS_FORK_EPOCH:
        return None
    active_entries = [
        entry for entry in config.GAS_LIMIT_SCHEDULE
        if entry.EPOCH <= epoch
    ]
    if not active_entries:
        return None
    # Latest schedule entry whose EPOCH <= epoch
    return max(active_entries, key=lambda entry: entry.EPOCH).GAS_LIMIT

Recommended client behavior

For CL clients that support GAS_LIMIT_SCHEDULE, an active scheduled value serves as both the default gas limit and the recommended maximum:

Default. When no operator preference is supplied and get_scheduled_gas_limit(epoch) returns a value, the client SHOULD use it as the gas limit preference, where epoch is the epoch of the slot the registration or proposal applies to. Before Gloas or when no entry is active, the client SHOULD retain its existing default behavior. Clients SHOULD NOT introduce a separate release-scoped default for epochs covered by an active schedule entry.
Recommended maximum. If an operator-supplied preference exceeds the active scheduled value, the client SHOULD honor it, since this EIP introduces no enforcement, but SHOULD log a clear warning, e.g., configured gas limit 100000000 exceeds the recommended maximum of 90000000 at epoch 540000. Exceeding the recommendation is thereby a deliberate, visible operator decision rather than a silent one.
Operator preferences are always honored. Values below the scheduled value work unchanged, as today.
Builders and relays. When a schedule entry is active, builders SHOULD produce, and relays SHOULD prefer, bids whose gas_limit does not exceed the scheduled value for the bid’s slot.

Epoch-based switching

The schedule only delivers its benefit if the effective default changes exactly at the configured epoch boundary, which requires new client logic: today, gas limit defaults are read once (at startup, or when a validator registration is created) and held constant. Under this EIP, the scheduled value SHOULD be looked up per duty against the epoch of the slot being proposed or registered for, never against wall-clock time or a value cached at startup. A running node then switches its preference at the first slot of the configured epoch with no restart, follow-up release, or operator action. Since validator registrations are re-issued periodically, registrations naturally roll over to a new scheduled value as duties cross the activation epoch.

Because the schedule is keyed by epoch, a release shipped months before an entry activates keeps using the current value until that epoch, then switches automatically. This makes it safe to ship large future increases well ahead of time: early updaters do not begin voting toward the new value before its configured activation epoch.

The consensus layer drives the gas limit

Starting with Gloas (EIP-7732), the gas limit a block is built to originates on the consensus layer side of the builder flow — the validator’s preference, expressed through validator registrations and the payload bid path — rather than from execution layer configuration. The schedule therefore lives only in the CL config.yaml; no execution layer chain-configuration counterpart is needed, and EL gas limit flags retain their existing pre-Gloas and local-tooling meaning. This EIP does not change gas limit selection before Gloas.

Illustrative preference selection:

def effective_gas_limit_preference(
    operator_preference: Optional[int],
    existing_default: int,
    epoch: Epoch,
    config: Config,
) -> int:
    scheduled = get_scheduled_gas_limit(epoch, config)
    if scheduled is None:
        return operator_preference if operator_preference is not None else existing_default
    if operator_preference is None:
        return scheduled
    if operator_preference > scheduled:
        log.warning(
            f"configured gas limit {operator_preference} exceeds the recommended "
            f"maximum of {scheduled} at epoch {epoch}"
        )
    return operator_preference

The realized network gas limit continues to move under the EIP-1559 ±1/1024 rule, so a scheduled increase plays out as a gradual, bounded ramp starting at the activation epoch rather than an instant step.

Rationale

Why epoch-based defaults instead of release-scoped defaults?

Keying the default on the duty’s epoch rather than the release version decouples shipping a new gas limit from activating it. This directly resolves the large-increase dilemma described in the Motivation: clients can ship the schedule entry for a big raise arbitrarily early, and no node will begin voting toward it until the configured epoch. An entry can align with a hard fork when desired, but the mechanism itself is only an epoch-based client configuration.

Why one value for both the default and the recommended maximum?

The number the community coordinates on for an epoch is the number the network runs at and the number operators are asked not to exceed. A single dial means there is no second parameter to negotiate or get out of sync, and no untested operating region between a default and a higher ceiling. Operators who want to run below it can; running above it is possible (nothing in consensus prevents it) but happens against a clear warning, which is a much stronger signal than today’s silently configurable free-for-all.

Why does the schedule live only on the consensus layer?

Post-Gloas, the CL is authoritative for the gas limit in practice: the validator preference drives registrations, builder bids, and payload construction. A parallel execution layer schedule would be redundant configuration that could only ever agree with or diverge from the CL’s — and divergence is a new failure mode with no benefit. One schedule, in the layer that actually drives the value, is the minimal design. EL clients require no changes at all under this EIP.

Why informational rather than a consensus rule?

An earlier draft of this EIP made the scheduled value a consensus-enforced maximum (and, before that, an exact-match requirement). This version is deliberately advisory:

Adoptability. A recommendation requires no fork, no engine API changes, and no coordination risk. The configuration field is optional, so CL teams can adopt it independently and incrementally, and entries can activate at any coordinated post-Gloas epoch.
Validator sovereignty is preserved. Gas limit choice remains, in the limit, with proposers — this EIP changes the defaults and social convention around that choice, not the protocol.
It solves the actual coordination problem. The premature-voting and back-to-back-release problems are default-management problems, and defaults are client behavior. Consensus enforcement addresses a different (drift-above-tested-envelope) risk, and can be pursued later as a separate Core EIP layered on the same schedule if the community wants it.

Why warn rather than clamp out-of-range preferences?

Clamping a preference down to the scheduled value would be enforcement — just relocated from consensus into the client. Without a consensus rule behind it, that would be dishonest in both directions: it implies a network ceiling that does not actually exist (any proposer running a non-conforming client could still exceed it), and it silently overrides an explicit operator decision that produces perfectly valid blocks. It would also fragment behavior across clients, since only those that adopt the optional schedule would clamp. A prominent warning keeps the mechanism honest: the schedule shapes defaults, and exceeding the recommended maximum remains possible but becomes a deliberate, visible act instead of a silent misconfiguration.

Relationship to EIP-7935

EIP-7935 recommended a single default (60M) tied to Fusaka’s activation. This EIP generalizes that one-off into a standing, machine-readable epoch schedule so future changes reuse the same mechanism instead of requiring a new EIP and a fresh round of client-default coordination.

Backwards Compatibility

No consensus rules change and no blocks become invalid. Pre-Gloas behavior and existing operator settings remain unchanged. For post-Gloas duties covered by an active schedule entry, unconfigured validators derive their gas limit preference from the schedule instead of a hardcoded constant, and configured values above the scheduled maximum produce a warning but are honored. CL clients that do not adopt the field, and all EL clients, are unaffected. Tooling that reads block.gas_limit is unaffected.

Security Considerations

The ceiling is advisory. Nothing in consensus prevents a proposer from exceeding the scheduled value, so this EIP does not protect against a deliberately non-conforming actor. It does protect against the accidental paths — a default shipped early, a stale setting, an uncoordinated bump — which historically are how unintended gas limit movement happens. The ±1/1024 elasticity rule further rate-limits how fast any actor, conforming or not, can move the realized limit.

Herding on the schedule. If most validators follow the schedule, the network’s gas limit becomes highly predictable, which is the goal. It also means an error in a scheduled value propagates widely; scheduled values should receive the same devnet and worst-case-block testing that gas limit increases receive today (as described in EIP-7935) before being added to a network’s configuration.

Partial adoption. Because the field is optional, clients that do not support it keep their existing defaults, and their operators keep coordinating manually. The mechanism’s coordination benefit is proportional to adoption; a mixed network is no worse than today, since non-supporting clients behave exactly as they do now.

Path to enforcement. If the community later wants a hard guarantee that the network cannot exceed a tested envelope, a future Standards Track Core EIP can promote this schedule’s value to a consensus-enforced maximum without changing the configuration format.

Copyright

Builder Execution Requests

Fri, 22 May 2026 00:00:00 +0000

EIP #8282 - Builder Execution Requests is in Last Call status. It is authored by Cayman (@wemeetagain), Nico Flaig , Felix Lange , Justin Traglia and was originally created 2026-05-22. It is in the Core category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/eip-8282-builder-execution-requests/28699

Abstract

This EIP introduces two EIP-7685 request types and corresponding predeploy contracts for EIP-7732 builders. A builder deposit contract handles initial registration and stake top-ups. A builder exit contract lets a builder’s execution_address trigger a full exit. Both contracts follow the request-bus pattern of EIP-7002 and EIP-7251. Builders no longer onboard through the validator deposit flow or exit through the voluntary-exit operation.

Motivation

EIP-7732 introduces builders as a separate, staked consensus-layer actor, but reuses validator flows for their lifecycle. A builder is registered by a validator deposit whose withdrawal credential carries the 0xB0 BUILDER_WITHDRAWAL_PREFIX, and it exits through a builder branch of the voluntary-exit operation. Dedicated builder request types improve on this in several ways.

Dedicated types make the actor explicit from the request type alone. The consensus layer no longer routes deposits by inspecting credential prefixes, and the validator and builder registries are keyed independently.

A builder deposit’s proof-of-possession is verified inline when the deposit is processed, unlike a validator deposit’s, which is deferred to the churn-limited pending_deposits queue. Builder deposits carried on the validator deposit request inherit its high per-payload ceiling. A dedicated request type isolates the verification work and caps it at MAX_DEPOSIT_REQUESTS_PER_BLOCK per block.

Under EIP-7732, a builder can only exit with a signature from its BLS key, the same hot key that signs its bids. The exit contract instead authorizes exit by the builder’s execution_address, as EIP-7002 does for validators.

Builders that must exist at the fork are unaffected. The EIP-7732 fork-transition onboarding of builder-credentialed pending deposits is retained, and only post-fork onboarding moves to the new contract.

Specification

Constants

Name	Value	Comment
`BUILDER_DEPOSIT_CONTRACT_ADDRESS`	`0x0000bFF46984e3725691FA540a8C7589300D8282`	Predeploy address of the builder deposit contract
`BUILDER_EXIT_CONTRACT_ADDRESS`	`0x000064D678505ad48F8cCb093BC65613800E8282`	Predeploy address of the builder exit contract
`BUILDER_DEPOSIT_REQUEST_TYPE`	`0x03`	EIP-7685 request-type byte for builder deposits
`BUILDER_EXIT_REQUEST_TYPE`	`0x04`	EIP-7685 request-type byte for builder exits
`SYSTEM_ADDRESS`	`0xfffffffffffffffffffffffffffffffffffffffe`	Address that invokes the end-of-block system call (as in EIP-7002)
`MAX_DEPOSIT_REQUESTS_PER_BLOCK`	`64`	Maximum records the builder deposit contract drains into one block
`TARGET_DEPOSIT_REQUESTS_PER_BLOCK`	`8`	Per-block request count above which the fee rises for the deposit contract
`MAX_EXIT_REQUESTS_PER_BLOCK`	`16`	Maximum records the builder exit contract drains into one block
`TARGET_EXIT_REQUESTS_PER_BLOCK`	`2`	Per-block request count above which the fee rises for the exit contract
`MIN_REQUEST_FEE`	`1`	Minimum request fee, in wei
`REQUEST_FEE_UPDATE_FRACTION`	`17`	Controls the fee’s rate of change
`BUILDER_MIN_DEPOSIT`	`1000000000000000000`	Minimum credited stake for a deposit, in wei (1 ETH — the EIP-7732 builder minimum)
`BUILDER_DEPOSIT_CONTRACT_RUNTIME_CODE`	see Reference Implementation	Runtime bytecode of the builder deposit contract
`BUILDER_EXIT_CONTRACT_RUNTIME_CODE`	see Reference Implementation	Runtime bytecode of the builder exit contract

Final request-type values MUST be unique across all active EIP-7685 request types. Allocation is coordinated in consensus-specs, where the existing types are defined (electra/beacon-chain.md).

Deployment

Both contracts are deployed by a CREATE2 factory (EIP-7997). Each address is determined by the factory, a salt, and the contract’s init code. The salt was mined so that the addresses above result from the current reference bytecode.

The contracts MUST be deployed before the fork that activates this EIP. If there is no code at either address once the EIP is active, every block from activation onward MUST be invalid.

Request queue and system call

Both predeploys follow the EIP-7002 and EIP-7251 contract design, with minor tweaks, and reuse their storage layout. There is no Solidity-compatible ABI. Each contract dispatches on the caller and on calldatasize alone. Calls that match none of the cases below MUST revert.

Write path

A call from any address other than SYSTEM_ADDRESS, with calldata of exactly the contract’s input size, submits a request. The contract MUST validate the request and the value sent (see below), append one record to its queue, increment the per-block count, and emit the accepted record as an anonymous log.

Fee getter

A call from any address other than SYSTEM_ADDRESS, with empty calldata, returns the current fee without modifying state. The contract MUST revert if any value is attached.

System call

At the end of each block, the contract is called by SYSTEM_ADDRESS. If any calldata is included, the queue is permanently disabled via an inhibitor. If no calldata is included, it MUST dequeue up to its per-block maximum of records (MAX_DEPOSIT_REQUESTS_PER_BLOCK or MAX_EXIT_REQUESTS_PER_BLOCK, oldest first), return their concatenation as its request_data, and reset the per-block count. Records beyond the cap remain queued for subsequent blocks.

The execution layer prepends the contract’s request-type byte and includes request_type ++ request_data in the block requests list, committed via the requests_hash (EIP-7685). The system call follows the same rules as in EIP-7002. It runs with a dedicated gas limit of 30_000_000 that does not count against the block gas limit. If either contract’s system call fails, the block MUST be invalid.

Request fee

Each request carries a fee, computed as in EIP-7002:

fee = fake_exponential(MIN_REQUEST_FEE, excess, REQUEST_FEE_UPDATE_FRACTION)

where fake_exponential is the EIP-1559-style integer approximation of MIN_REQUEST_FEE * e**(excess / REQUEST_FEE_UPDATE_FRACTION). The fee rises super-linearly while blocks contain more than the target number of requests and decays back to MIN_REQUEST_FEE otherwise. It is charged on top of any staked value and is left locked in the contract.

Both contracts are modified to apply fee increases for each write path, rather than at end-of-block, as in EIP-7002.

Deposit requests

A deposit request is submitted by calling BUILDER_DEPOSIT_CONTRACT_ADDRESS with calldata of exactly 184 bytes:

Bytes	Field	Description
`0:48`	`pubkey`	48-byte BLS public key
`48:80`	`withdrawal_credentials`	32-byte commitment (`version` byte + `execution_address`)
`80:88`	`amount`	Big-endian `uint64`, in gwei
`88:184`	`signature`	96-byte BLS proof-of-possession

A deposit request serves both a builder’s first deposit and subsequent top-ups. The contract MUST reject the request unless amount * 1 gwei >= BUILDER_MIN_DEPOSIT and msg.value >= amount * 1 gwei + fee. Any value beyond amount * 1 gwei + fee is retained by the contract and not credited to the builder.

On success the contract queues the 184 input bytes. The dequeued record is the input verbatim with amount converted to little-endian, as in EIP-7002. The contract does not verify the signature. It is carried in the record and verified by the consensus layer. Submitters SHOULD verify the proof-of-possession off-chain before broadcasting a first deposit.

Exit requests

An exit request is submitted by calling BUILDER_EXIT_CONTRACT_ADDRESS with calldata of exactly 48 bytes, the pubkey of the builder to exit. The contract MUST require msg.value >= fee. No value is staked. On success it queues a record of source_address (20) ++ pubkey (48), where source_address is msg.sender.

Authorization is by source_address, as in EIP-7002. The contract records msg.sender and performs no further check. The consensus layer honors the request only when source_address equals the target builder’s execution_address.

Consensus layer processing

The consensus layer decodes each dequeued record into one of two SSZ containers, selected by request type:

class BuilderDepositRequest(Container):
    pubkey: Bytes48
    withdrawal_credentials: Bytes32
    amount: uint64  # Gwei
    signature: Bytes96

class BuilderExitRequest(Container):
    source_address: Bytes20
    pubkey: Bytes48

A type’s request_data is the concatenation of the fixed-size SSZ serializations of its records, which is exactly the bytes the system call returns, in the same order. BuilderDepositRequest is the EIP-6110 DepositRequest without the index field.

Detailed state-transition behavior is specified in consensus-specs. In summary:

A BuilderDepositRequest for a pubkey not in the builder registry registers a new builder if its signature is a valid proof-of-possession over (pubkey, withdrawal_credentials, amount) under DOMAIN_BUILDER_DEPOSIT, a builder-specific signing domain. A record with an invalid signature is ignored and its stake forfeited. Deposits are applied immediately rather than routed through the validator pending_deposits queue.
A BuilderDepositRequest for an already-registered pubkey is a top-up. The amount is credited and the record’s withdrawal_credentials and signature are ignored, as with validator deposits.
A BuilderExitRequest initiates a full exit only if its pubkey is an active builder, its source_address equals that builder’s execution_address, and the builder has no pending balance to withdraw. Otherwise the record is dropped rather than re-queued, and the request must be resubmitted.

Changes to EIP-7732

Deposit routing

The builder branch of process_deposit_request is removed, so a deposit to the validator deposit contract is always an ordinary validator deposit. Builders are created and topped up only through BUILDER_DEPOSIT_REQUEST_TYPE. A post-fork deposit to the validator contract with a 0xB0 credential mints a validator that cannot withdraw its balance, so builder deposits MUST be sent to the builder deposit contract.

Fork-transition onboarding

The one-time EIP-7732 onboarding of builder-credentialed pending deposits at the fork is retained, so builders exist from the first slot. This is the only path that onboards builders through the validator deposit contract. The 0xB0 BUILDER_WITHDRAWAL_PREFIX is deprecated afterward.

Exit routing

The builder branch of process_voluntary_exit is removed, making the voluntary-exit operation validator-only. Builders exit only through BUILDER_EXIT_REQUEST_TYPE.

Rationale

Two predeploys, two request types

This mirrors withdrawals (0x01) and consolidations (0x02). The execution layer needs no new read semantics, and the consensus layer routes by request type rather than by inspecting credentials.

One request for deposits and top-ups

This matches the validator deposit contract. The proof-of-possession is checked on a pubkey’s first appearance, and later deposits credit stake. A top-up cannot redirect a builder’s withdrawals because its withdrawal_credentials and signature are ignored.

Exit by `execution_address`

A builder’s BLS key is hot, since it signs bids continuously, so it should not also authorize exits. Routing exit through the cold execution_address mirrors the EIP-7002 rationale for validator withdrawal credentials and gives builders a single, well-defined exit authorizer.

Request fee

The same demand-responsive fee as EIP-7002 and EIP-7251 meters submission, together with the per-block caps and the per-deposit stake.

Onboarding at the fork

Some applications depend on builders existing from the first slot of the fork, which post-fork deposits to the new contract cannot provide. The existing EIP-7732 onboarding path is therefore retained for the initial builder set.

Backwards Compatibility

This EIP is additive at the execution layer. It introduces new contracts at previously empty addresses and does not modify the validator deposit contract or the validator request predeploys. At the consensus layer it modifies the EIP-7732 builder lifecycle as described in Changes to EIP-7732. Builders onboarded at the fork are unaffected.

Reference Implementation

See src/builder_deposits and src/builder_deposits.

Security Considerations

Exit authorization

The exit contract records msg.sender as source_address and performs no further check. The request carries no signature, so the source_address check during consensus layer processing is the only exit authorization; without it an arbitrary caller could exit any builder.

Signing-domain separation

Builder deposits are signed under DOMAIN_BUILDER_DEPOSIT, distinct from the validator DOMAIN_DEPOSIT, so deposit proofs-of-possession cannot be replayed across the two classes. Fork-transition seed deposits are made through the validator deposit contract and are necessarily signed under DOMAIN_DEPOSIT.

Replayable deposit records

A deposit’s fields are public in calldata, so a third party can resubmit them for an already-registered builder at an amount it funds itself. Such a replay is a top-up whose credentials and signature are ignored. It credits stake and redirects nothing.

Custodial-split exit standoff

Exit requires a zero pending balance, every winning bid adds pending balance, and only the execution_address can authorize exit. Where the execution_address (capital owner) and the BLS key (bidding operator) are held by different parties, an operator that keeps winning bids can indefinitely block the owner’s exit. Delegating parties should retain off-chain control over the operator’s bidding.

Spam and state growth

The per-block caps bound the drain rate, not enqueue, so the in-state queues can grow across blocks. Growth is gated by value, since each deposit locks at least BUILDER_MIN_DEPOSIT plus the fee. An attacker submitting valid proofs-of-possession forfeits nothing, because the stake remains a withdrawable builder balance, so post-fork onboarding can be delayed behind a backlog of attacker deposits at the cost of locked capital. This is tolerable because the time-critical initial builder set is seeded through the fork transition rather than the steady-state contract.

Locked funds

The request fee, any overpayment, and the principal of a first deposit that the consensus layer rejects for an invalid proof-of-possession are permanently locked in the predeploy. The execution layer does not verify BLS signatures, so the off-chain proof-of-possession check advised in Deposit requests is a submitter’s only protection against losing a first deposit’s principal.

Copyright

Asset Anchor Registry

Sat, 04 Jul 2026 00:00:00 +0000

EIP #8325 - Asset Anchor Registry is in Last Call status. It is authored by Chris Turner , David Hay (@david-hay), Reagan Simpson (@krumg111), Collins Musyimi (@Musyimi97) and was originally created 2026-07-04. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/erc-8325-asset-anchor-registry/28934

Abstract

This Ethereum Request for Comments (ERC) defines interfaces for registries that bind token contracts or token IDs to anchor records representing claims about off-chain assets. Each anchor contains separate commitments to a claimed legal basis and supporting evidence. Bindings distinguish whole-contract scope from token-ID scope, enforce registry-scoped exclusivity, and preserve immutable binding history.

Token-side interfaces allow contracts to declare the same registry and anchor, enabling consumers to verify both sides of a binding. A lifecycle interface defines structured metadata, expiry, re-attestation, and permanent deactivation. An optional recovery interface permits disputed bindings to be invalidated without deleting their historical records.

The resulting records provide durable, registry-scoped binding provenance for consumers that require an auditable lifecycle history.

This ERC does not establish the existence, ownership, legal validity, or value of an off-chain asset.

Motivation

A token can claim in metadata that it represents an off-chain asset, but that claim does not provide a common interface for another contract to determine:

which registry record the token claims;
whether the registry records the same token-to-anchor relationship;
whether the binding is exclusive within that registry;
whether the binding applies to an entire token contract or one token ID; or
whether the anchor is active, expired, deactivated, or invalidated.

Deployments subject to institutional or regulatory oversight often need a durable answer to which token tuple was recorded against an asset claim, when the binding was established, and whether it remains current. This ERC makes registry-scoped exclusivity and immutable binding history explicit without asserting that the underlying claim is legally valid or factually correct.

Without a mutually queryable structure, the relationship remains assertion-only tokenization: the token can describe an off-chain asset, but an independent consumer cannot verify the claimed token-to-record relationship through a common interface.

Applications consequently rely on implementation-specific metadata and registries. The same asset claim can be represented differently by each issuer, and consumers cannot inspect a binding through a common interface.

This ERC standardizes the structural relationship between a registry anchor and a token contract or token ID. The guarantee is intentionally limited to one registry instance. Registry operators remain responsible for deciding which claims they accept, and consumers remain responsible for deciding which registries they trust.

Specification

Definitions

An anchor is a registry record containing commitments and metadata for an off-chain asset claim.

A contract binding binds an anchor to an entire token contract. This is appropriate when one contract represents one claimed asset or instrument.

A token-ID binding binds an anchor to one token ID within a token contract.

A binding tuple is (token, bindingScope, tokenId).

A valid binding is a recorded binding that has not been invalidated through the optional IAssetAnchorRegistryRecovery interface, defined in the Recovery Interface section below. Binding validity is distinct from lifecycle activity.

An active anchor is an anchor that has not been permanently deactivated and whose metadata has not expired.

Binding Scopes

Implementations MUST use the following scope identifiers:

bytes32 constant BINDING_SCOPE_CONTRACT =
    keccak256("ERC-8325:BINDING_SCOPE:CONTRACT");

bytes32 constant BINDING_SCOPE_TOKEN_ID =
    keccak256("ERC-8325:BINDING_SCOPE:TOKEN_ID");

For BINDING_SCOPE_CONTRACT, tokenId MUST equal 0 as a canonical unused value.

For BINDING_SCOPE_TOKEN_ID, every uint256 value is valid, including token ID 0. Token ID 0 MUST NOT be interpreted as a contract-binding sentinel.

Metadata Encoding

Registration metadata MUST be application binary interface (ABI) encoded as the following ordered tuple:

struct AnchorMetadata {
    bytes32 assetClass;
    bytes32 jurisdiction;
    uint64 attestationDate;
    uint64 expiresAt;
    bytes uri;
    bytes extensions;
}

The canonical encoding is:

abi.encode(
    metadata.assetClass,
    metadata.jurisdiction,
    metadata.attestationDate,
    metadata.expiresAt,
    metadata.uri,
    metadata.extensions
)

assetClass and jurisdiction MUST NOT be bytes32(0). attestationDate MUST NOT be 0 and MUST NOT be later than block.timestamp. expiresAt MUST be later than attestationDate and MUST NOT be earlier than block.timestamp at registration. uri MUST NOT be empty. extensions MAY be empty.

assetClass SHOULD be a domain-separated identifier from a documented taxonomy. When an anchor has one primary country jurisdiction, jurisdiction SHOULD be a domain-separated identifier derived from its uppercase International Organization for Standardization (ISO) 3166-1 alpha-2 code.

The Uniform Resource Identifier (URI) identifies where a consumer can retrieve material corresponding to the anchor commitments. This ERC does not require a particular URI scheme or guarantee availability.

Registry Interface

pragma solidity ^0.8.20;

interface IAssetAnchorRegistry {
    struct AnchorRecord {
        bytes32 anchorId;
        bytes32 legalHash;
        bytes32 evidenceHash;
        address boundToken;
        bytes32 bindingScope;
        uint256 boundTokenId;
        uint64 registeredAt;
        bool active;
    }

    event AnchorRegistered(
        bytes32 indexed anchorId,
        bytes32 legalHash,
        bytes32 evidenceHash
    );

    event TokenBound(
        bytes32 indexed anchorId,
        address indexed token,
        bytes32 indexed bindingScope,
        uint256 tokenId
    );

    event AnchorDeactivated(bytes32 indexed anchorId, string reason);

    event AnchorReattested(
        bytes32 indexed anchorId,
        uint64 oldExpiresAt,
        uint64 newExpiresAt,
        uint64 newAttestationDate
    );

    function registerAnchor(
        bytes32 legalHash,
        bytes32 evidenceHash,
        bytes calldata metadata
    ) external returns (bytes32 anchorId);

    function bindToken(
        bytes32 anchorId,
        address token,
        bytes32 bindingScope,
        uint256 tokenId
    ) external;

    function registerAndBind(
        bytes32 legalHash,
        bytes32 evidenceHash,
        bytes calldata metadata,
        address token,
        bytes32 bindingScope,
        uint256 tokenId
    ) external returns (bytes32 anchorId);

    function getAnchor(bytes32 anchorId)
        external
        view
        returns (AnchorRecord memory);

    function isBound(bytes32 anchorId) external view returns (bool);
}

Registration

registerAnchor and registerAndBind MUST reject bytes32(0) for legalHash or evidenceHash.

The anchor identifier MUST be derived as:

anchorId = keccak256(abi.encode(legalHash, evidenceHash));

The same (legalHash, evidenceHash) pair therefore produces the same anchorId within and across implementations of this ERC. A registry MUST reject an anchorId that it has already registered.

On successful registration, the registry MUST:

store the supplied hashes and derived anchorId;
store registeredAt as uint64(block.timestamp);
initialize boundToken to address(0);
initialize bindingScope to bytes32(0);
initialize boundTokenId to 0;
initialize active to true; and
emit AnchorRegistered.

The mechanism for authorizing registration is implementation-defined. Implementations MUST document their authorization policy.

Binding

bindToken MUST reject an unknown anchor, an inactive or expired anchor, a zero token address, an unsupported binding scope, and an anchor whose binding fields have already been set.

Before recording a binding, the registry MUST ensure that no valid anchor is already associated with the same binding tuple. The uniqueness key SHOULD be derived as:

keccak256(abi.encode(token, bindingScope, tokenId))

On successful binding, the registry MUST set boundToken, bindingScope, and boundTokenId and emit TokenBound. These three historical fields MUST NOT be modified after they are set, including after deactivation or invalidation.

registerAndBind MUST apply the same registration and binding requirements atomically.

The mechanism for authorizing binding is implementation-defined. It MUST prevent an unrelated caller from binding another registrar’s unbound anchor.

If token exposes anchorRegistry(), the returned address MUST equal the registry performing the binding. A registry MAY bind a token that does not implement a token-side interface. Such a record is a registry-side binding only and does not constitute mutually declared binding under this ERC.

Registry Queries

getAnchor MUST return the complete stored record and MUST revert for an unknown anchorId.

isBound MUST return true when boundToken is not address(0), regardless of lifecycle activity or recovery invalidation. It MUST return false for a known but unbound anchor and MUST revert for an unknown anchorId.

Lifecycle Interface

Every compliant registry MUST implement the lifecycle interface because anchor activity and expiry are part of the common verification model:

pragma solidity ^0.8.20;

interface IAssetAnchorRegistryLifecycle {
    function getMetadata(bytes32 anchorId)
        external
        view
        returns (AnchorMetadata memory);

    function registeredBy(bytes32 anchorId)
        external
        view
        returns (address);

    function isActive(bytes32 anchorId) external view returns (bool);

    function deactivateAnchor(
        bytes32 anchorId,
        string calldata reason
    ) external;

    function reattest(
        bytes32 anchorId,
        uint64 newExpiresAt,
        uint64 newAttestationDate
    ) external;
}

getMetadata, registeredBy, and isActive MUST revert for an unknown anchor.

registeredBy MUST return the address that successfully registered the anchor and MUST NOT change after registration.

isActive MUST return false if AnchorRecord.active is false or if block.timestamp > expiresAt. An anchor remains active at the exact expiresAt timestamp.

deactivateAnchor MUST be restricted to authorized callers, set active to false, and emit AnchorDeactivated. Manual deactivation is permanent and MUST NOT be reversed by reattest.

reattest MUST be restricted to an authorized caller and MUST reject a manually deactivated anchor. newAttestationDate MUST NOT be 0, later than block.timestamp, or earlier than the existing attestationDate. newExpiresAt MUST be later than block.timestamp, later than newAttestationDate, and not earlier than the existing expiresAt. Successful re-attestation MUST emit AnchorReattested.

Recovery Interface

Binding recovery is OPTIONAL. A registry that permits disputed bindings to be invalidated MUST implement:

pragma solidity ^0.8.20;

interface IAssetAnchorRegistryRecovery {
    event TokenBindingInvalidated(
        bytes32 indexed anchorId,
        address indexed token,
        bytes32 indexed bindingScope,
        uint256 tokenId,
        bytes32 reasonHash
    );

    function invalidateTokenBinding(
        bytes32 anchorId,
        bytes32 reasonHash
    ) external;

    function isBindingValid(bytes32 anchorId)
        external
        view
        returns (bool);
}

invalidateTokenBinding MUST be restricted to an authorized recovery role. It MUST reject an unknown, unbound, or previously invalidated anchor and a zero reasonHash.

Successful invalidation MUST:

preserve boundToken, bindingScope, and boundTokenId;
make isBindingValid(anchorId) return false;
permanently deactivate the anchor;
emit AnchorDeactivated if the anchor was active; and
emit TokenBindingInvalidated.

An implementation MAY free the binding tuple so that a different anchor can be bound to it. If it does so, the invalidated record MUST remain historically queryable and MUST NOT itself be rebound.

isBindingValid MUST return true only when an anchor is bound and has not been invalidated. It MUST revert for an unknown anchor.

Token Interfaces

Whole-contract bindings use:

pragma solidity ^0.8.20;

interface IAssetBoundToken is IERC165 {
    function anchorId() external view returns (bytes32);
    function anchorRegistry() external view returns (address);
    function isAnchorActive() external view returns (bool);
}

Token-ID bindings use:

pragma solidity ^0.8.20;

interface IAssetBoundTokenId is IERC165 {
    function anchorIdOf(uint256 tokenId)
        external
        view
        returns (bytes32);

    function anchorRegistry() external view returns (address);

    function isAnchorActiveFor(uint256 tokenId)
        external
        view
        returns (bool);
}

anchorRegistry MUST remain unchanged after deployment.

For IAssetBoundToken, anchorId MUST remain unchanged after deployment.

For IAssetBoundTokenId, anchorIdOf(tokenId) MUST revert when the token ID is not bound. Once a nonzero anchor is declared for a token ID, that declaration MUST NOT change.

isAnchorActive and isAnchorActiveFor MUST reflect lifecycle activity from the declared registry. Consumers MUST query isBindingValid separately when the registry implements the recovery interface.

Interface Detection

Compliant registries MUST implement ERC-165 and return true for type(IAssetAnchorRegistry).interfaceId.

Compliant registries MUST return true for type(IAssetAnchorRegistryLifecycle).interfaceId. Registries implementing recovery MUST also return true for type(IAssetAnchorRegistryRecovery).interfaceId.

Compliant tokens MUST return true for the applicable token-side interface ID.

ERC-165 detects interface support. It does not prove correct behavior, transfer enforcement, registrar trustworthiness, or the validity of an off-chain claim.

Complete Binding Verification

A consumer treating a binding as mutually declared MUST verify all of the following:

getAnchor(anchorId) returns the expected token, scope, and token ID.
isBound(anchorId) returns true.
isActive(anchorId) returns true.
isBindingValid(anchorId) returns true when recovery is implemented.
The token supports the applicable token-side interface.
The token reports the same registry and anchor.

Failure of any applicable check means the consumer MUST NOT treat the binding as a current mutually declared binding.

Rationale

Why Use a Registry?

A separate registry allows the same binding interface to compose with fungible, non-fungible, multi-token, permissioned, and future token standards. It also provides one inspection surface for applications that do not control the token implementation.

The registry does not create global truth. Consumers select which registry operators and authorization policies they trust.

Why Two Hashes?

Off-chain asset structures often distinguish the instrument or legal basis from evidence about the referenced asset. Separate commitments preserve that distinction without assigning universal semantics to either document set.

Deployments that do not need the distinction can commit to two separately defined records. A zero hash is not available as an omission sentinel.

Why a Deterministic Anchor Identifier?

Deriving anchorId from both commitments gives implementations the same identifier for the same pair of bytes and makes duplicate registration within a registry unambiguous. It does not deduplicate semantically equivalent documents with different byte representations.

Why Explicit Binding Scope?

Using token ID 0 to mean whole-contract binding prevents token ID 0 from being bound as an actual ERC-721 or ERC-1155 token. Including an explicit scope makes contract binding and token-ID-zero binding distinct.

Why Split the Token Interfaces?

A whole-contract token has no meaningful anchorIdOf query, while a collection with independently anchored token IDs has no meaningful contract-wide anchorId. Separate interfaces avoid mandatory functions with misleading or implementation-specific failure behavior.

Why Separate Activity from Binding?

A binding is historical identity data. Activity is lifecycle status. Expiry or deactivation can make an anchor operationally inactive without changing which token was bound to it. Accordingly, isBound is not an activity check.

Why an Optional Recovery Interface?

Permanent bindings are vulnerable to registrar compromise, key loss, and binding-key squatting. Recovery allows an explicitly trusted administrator to invalidate an operational binding while preserving its history. Deployments that prefer absolute immutability can omit the recovery interface.

Recovery introduces substantial administrative trust and is therefore not part of the minimum registry interface.

Why Not Enforce Allocation Integrity?

Allocation constraints, such as ensuring that fractional token supply does not represent more than a defined share of an asset, depend on the economic and legal structure of the instrument. They are meaningful for some fungible fractional claims but not for a single non-fungible token (NFT) representing one object or for a registry record that does not express ownership percentages.

The registry therefore standardizes binding identity rather than issuance or allocation rules. Tokens and application-specific contracts remain responsible for enforcing any supply, fraction, or entitlement constraints.

Why Leave Registry Governance Open?

Different deployments require different trust models. A registry may be operated by one accountable issuer, a regulated registrar, a multisignature, a decentralized autonomous organization (DAO), or a permissionless protocol. Requiring one governance model would exclude otherwise interoperable implementations without making their off-chain claims more truthful.

Consumers select which registries and governance policies they trust. The common interface makes those registries technically inspectable; it does not make them equally trustworthy.

Why Are Historical Binding Fields Immutable?

Changing a binding’s token, scope, or token ID in place would erase the relationship that consumers previously inspected. This ERC therefore preserves those fields after deactivation and recovery invalidation, allowing auditors and other consumers to determine which tuple was recorded and how its status changed over time.

Field immutability does not mean that a binding remains active or valid. Consumers must evaluate lifecycle activity and, when implemented, recovery validity separately. If an implementation releases an invalidated tuple, the invalidated record remains queryable and a replacement is stored as a separate anchor. The guarantee remains scoped to one registry and does not establish global one-token-to-one-asset uniqueness.

Prior Art

ERC-3643 and ERC-7943 define token behavior and compliance-related interfaces. They do not define the registry-scoped token-to-anchor relationship specified here. Tokens implementing either can also implement a token-side interface from this ERC.

Backwards Compatibility

This ERC introduces new interfaces and does not change existing token standards. Existing token contracts can be recorded in a registry without modification, but this produces only a registry-side binding.

An existing upgradeable token can add the applicable token-side interface. An immutable token that lacks the interface requires a wrapper, adapter, or new deployment to provide mutually declared binding. Consumers should distinguish a registry-only record from a binding confirmed by both registry and token.

Test Cases

Implementations should test at least the following cases:

deterministic anchor derivation and duplicate rejection;
rejection of zero hashes and malformed metadata;
contract scope with tokenId == 0;
rejection of contract scope with a nonzero token ID;
token-ID scope with token ID 0;
separation of contract scope from token-ID-zero scope;
rejection of duplicate anchor and duplicate valid binding tuple use;
atomic registration and binding;
expiry at, before, and after the inclusive boundary;
permanent manual deactivation;
monotonic re-attestation;
token registry mismatch;
complete mutually declared binding verification across registry and token-side queries;
preservation of binding fields across deactivation and recovery invalidation;
lifecycle event coverage for registration, binding, re-attestation, deactivation, and recovery invalidation;
optional release of an invalidated binding tuple; and
positive and negative ERC-165 detection.

Reference Implementation

A Solidity reference implementation, unit tests, fuzz tests, invariants, and an independent audit are linked from the discussion referenced in the preamble. The implementation is illustrative; its access-control roles and deployment model are not required by this ERC.

Security Considerations

Registry Trust

The registry proves only that its own state satisfies the specified structural rules. A malicious or compromised registrar can register false claims with validly formed hashes and metadata. Consumers should evaluate the registry’s operator, authorization policy, upgrade authority, and legal context.

No Legal or Physical Truth Guarantee

Neither a hash nor a mutually declared token binding proves that an off-chain asset exists, that documents are authentic, or that a token conveys a legal right. Those determinations require external verification.

Registration-to-Binding Races

Separate registration and binding create an interval in which an unauthorized caller may attempt to bind an anchor. Implementations should restrict binding to authorized parties. Registrars should use registerAndBind when atomicity is required.

Malicious Tokens and Interface Spoofing

A token can return arbitrary values from the token-side interfaces or falsely claim ERC-165 support. Consumers should verify the registry record independently. Registries that call token contracts during binding should use static calls and handle malformed return data and reverts.

Recovery Authority

A recovery administrator can invalidate legitimate bindings and, when the implementation releases binding tuples, enable replacement anchors. Production deployments should protect recovery authority with a multisignature, governance, timelock, or equivalent controls. Consumers should monitor TokenBindingInvalidated and AnchorDeactivated events.

Releasing an invalidated tuple does not change an immutable token-side anchor declaration. A replacement can be mutually declared only when the token already declares the replacement anchor. A replacement binding recorded for a token that does not expose a token-side interface is registry-side only.

Document Canonicalization

The registry treats legalHash and evidenceHash as opaque commitments. Two representations of the same document can produce different hashes. Deployments requiring interoperable document commitments should define a deterministic normalization and bundle-hashing procedure.

Data Availability

An on-chain commitment is not useful for verification if the committed material cannot be retrieved. The registry does not guarantee URI persistence or data availability. Deployments should use durable storage and availability policies.

Multi-Registry and Cross-Chain Duplication

Independent registries or deployments on different chains can register claims about the same off-chain asset. This ERC provides no global uniqueness or cross-registry conflict resolution.

Because anchorId does not include a chain identifier or registry address, consumers requiring globally scoped identity should use (chainId, registry, anchorId) rather than anchorId alone. A companion system that accepts only a bare anchorId can otherwise conflate records from different registry domains.

Expiry and Timestamp Dependence

Lifecycle status depends on block.timestamp, which block producers can vary within protocol constraints. Applications should avoid relying on second-level precision around an expiry boundary.

Upgradeability

An upgradeable registry can alter binding behavior after consumers begin relying on it. Upgrades must preserve historical binding fields to remain compliant. Consumers should inspect proxy administration and upgrade policies.

Institutional and Regulated Deployments

Deployments operating under institutional or regulatory controls should document registration and binding authority, protect recovery and upgrade authority with appropriate multisignature, timelock, governance, or equivalent controls, and monitor all binding and lifecycle events.

Such deployments should also define how contested invalidations are reviewed and how committed records are made available to authorized auditors. Conformance with this ERC provides a common technical interface; it does not establish regulatory status, legal sufficiency, or compliance with any jurisdiction’s requirements.

Copyright

Canonical Document Bundle Anchor

Sun, 05 Jul 2026 00:00:00 +0000

EIP #8326 - Canonical Document Bundle Anchor is in Last Call status. It is authored by Chris Turner , David Hay (@david-hay), Reagan Simpson (@krumg111), Collins Musyimi (@Musyimi97) and was originally created 2026-07-05. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/erc-8326-canonical-document-bundle-anchor/28935

Abstract

This Ethereum Request for Comments (ERC) defines a deterministic manifest and anchoring interface for commitments to bundles of off-chain documents. Each document is represented by a fixed-width entry containing a content hash, document role, media-type hash, filename hash, and normalization-profile identifier. Entries are placed in a total order and hashed under a schema-version prefix to produce one bytes32 bundle commitment.

The on-chain interface anchors a bundle hash in a (subjectId, role) namespace, records declarative metadata, and preserves an append-only supersession history. An optional recovery interface permits administrative reassignment of authority over a contested namespace without rewriting anchored records.

This ERC standardizes manifest construction and commitment anchoring. It does not prove document authenticity, legal effect, off-chain availability, or the correct application of a normalization profile.

Motivation

Contracts and applications frequently commit to multiple off-chain documents, including agreements, certifications, evidence, amendments, and supporting records. Without a common manifest, implementations differ in entry encoding, ordering, version separation, and supersession behavior. Two systems can hold the same canonical document representations but derive incompatible bundle commitments.

Document commitment has two distinct layers. Normalization transforms a raw format into canonical bytes. Manifesting describes and orders the resulting document commitments before deriving a bundle hash. Normalization is format-specific and evolves independently; manifesting and on-chain anchoring can remain stable.

This ERC provides a common manifest and anchoring surface while making that boundary explicit. Compatible implementations derive the same bundle hash only when they use the same canonical document bytes, entry fields, normalization profile identifiers, schema version, and ordering rules.

Specification

Definitions

A document entry is a fixed-width record describing one normalized document commitment.

A normalization profile defines how raw document input is converted to the bytes committed by contentHash.

A bundle is a non-empty multiset of document entries. Duplicate entries are retained and affect the resulting bundle hash.

A bundle hash is the schema-versioned commitment derived from the canonically ordered entries.

A slot is the (subjectId, role) namespace containing at most one active bundle hash.

A superseded record is a historical anchor that has been replaced in its slot. Supersession does not delete or rewrite its immutable fields.

Document Entry

Each document MUST be represented as:

struct DocumentEntry {
    bytes32 contentHash;
    bytes32 role;
    bytes32 mimeTypeHash;
    bytes32 filenameHash;
    bytes32 normProfileId;
}

contentHash MUST be the keccak256 hash of the exact output bytes produced by the selected normalization profile.

role identifies the function of the document within the bundle.

mimeTypeHash MUST be keccak256 of the canonical IANA media type encoded as lowercase ASCII without parameters. For example, application/json; charset=utf-8 is represented by keccak256("application/json").

filenameHash MUST be derived by treating U+002F (/) and U+005C (\) as path separators, retaining the substring after the final separator, applying ASCII lowercase conversion to A through Z, applying Unicode NFC normalization, encoding the result as UTF-8, and applying keccak256.

normProfileId identifies the transformation used to produce the committed bytes. Consumers MUST NOT interpret contentHash without considering its normalization profile.

Schema, Role, and Profile Identifiers

Implementations MUST use the following schema identifier:

bytes32 constant SCHEMA_V1 = keccak256("ERC-8326:BUNDLE:V1");

The following role identifiers are defined:

bytes32 constant LEGAL_BASIS = keccak256("LEGAL_BASIS");
bytes32 constant EVIDENCE = keccak256("EVIDENCE");
bytes32 constant CERTIFICATION = keccak256("CERTIFICATION");
bytes32 constant AGREEMENT = keccak256("AGREEMENT");
bytes32 constant AMENDMENT = keccak256("AMENDMENT");
bytes32 constant SUPPORTING = keccak256("SUPPORTING");

Applications MAY define additional role identifiers. Custom roles SHOULD use a documented namespace and version to prevent semantic collisions.

The following normalization profiles are defined:

bytes32 constant PROFILE_RAW = keccak256("NORM:RAW:V1");
bytes32 constant PROFILE_JSON_RFC8785 =
    keccak256("NORM:JSON:RFC8785:V1");
bytes32 constant PROFILE_XML_C14N11 =
    keccak256("NORM:XML:C14N11:V1");

For PROFILE_RAW, the output bytes are the raw input bytes without transformation.

For PROFILE_JSON_RFC8785, the output bytes are the UTF-8 serialization produced by RFC 8785. Implementations MUST reject inputs that cannot be processed under the RFC 8785 and I-JSON constraints, including duplicate object keys, invalid Unicode, lone surrogates, and numbers outside the interoperable range. JSON string values are preserved; this profile does not apply Unicode normalization to them.

For PROFILE_XML_C14N11, the output bytes are produced by Canonical XML 1.1 without comments. Implementations MUST disable external entity resolution. This profile is distinct from Exclusive XML Canonicalization.

PDF, image, signed-PDF, and plain-text normalization are not defined by this ERC. Such documents SHOULD use PROFILE_RAW unless another precisely specified profile is agreed by the producer and verifier.

Custom profile identifiers SHOULD use:

NORM:CUSTOM:<namespace>:<format>:<version>

A custom profile specification MUST define exact transformation rules and test fixtures. The namespace MUST identify the defining organization or protocol.

Canonical Ordering

Entries MUST be ordered lexicographically by their raw bytes32 values using the following keys, each ascending:

role
filenameHash
contentHash
mimeTypeHash
normProfileId

The comparison proceeds to the next key only when all preceding keys are equal. Equal entries remain duplicated. No timestamp or preparer-controlled value is included in a document entry.

Bundle Hash Derivation

A bundle MUST contain at least one entry.

For each canonically ordered entry, derive:

bytes32 leaf = keccak256(
    abi.encodePacked(
        entry.contentHash,
        entry.role,
        entry.mimeTypeHash,
        entry.filenameHash,
        entry.normProfileId
    )
);

The bundle hash is:

bundleHash = keccak256(
    abi.encodePacked(SCHEMA_V1, leaf0, leaf1, ..., leafN)
);

All encoded elements are fixed-width bytes32 values, so packed encoding does not introduce variable-length boundary ambiguity.

Future incompatible manifest schemas MUST use a new schema identifier. They MUST NOT reuse SCHEMA_V1.

Reference Hashing Functions

The following signatures describe two conforming reference paths:

function computeCanonicalBundleHash(DocumentEntry[] memory entries)
    internal pure returns (bytes32);

function computeBundleHash(DocumentEntry[] memory entries)
    internal pure returns (bytes32);

computeCanonicalBundleHash MUST sort entries according to the total order before deriving the hash.

computeBundleHash MUST require already sorted entries and MUST revert for unsorted input. Both functions MUST revert for an empty bundle and MUST produce the derivation specified above.

The reference computeCanonicalBundleHash uses an in-memory quadratic sort for clarity. Production systems SHOULD normalize, sort, and hash off-chain. Large bundles verified on-chain SHOULD use pre-sorted entries with computeBundleHash or a more gas-efficient algorithm that produces the same total order.

Anchor Interface

pragma solidity ^0.8.20;

interface IDocumentBundleAnchor {
    struct AnchorRecord {
        bytes32 bundleHash;
        bytes32 subjectId;
        bytes32 role;
        address anchoredBy;
        uint64 anchoredAt;
        uint256 documentCount;
        string metadataURI;
        bool superseded;
        bytes32 supersededBy;
    }

    event BundleAnchored(
        bytes32 indexed bundleHash,
        bytes32 indexed subjectId,
        bytes32 indexed role,
        uint256 documentCount
    );

    event BundleSuperseded(
        bytes32 indexed oldBundleHash,
        bytes32 indexed newBundleHash,
        bytes32 indexed subjectId,
        bytes32 role
    );

    function anchorBundle(
        bytes32 bundleHash,
        bytes32 subjectId,
        bytes32 role,
        uint256 documentCount,
        string calldata metadataURI
    ) external;

    function supersedeBundle(
        bytes32 oldBundleHash,
        bytes32 newBundleHash,
        bytes32 subjectId,
        bytes32 role,
        uint256 documentCount,
        string calldata metadataURI
    ) external;

    function getAnchor(
        bytes32 bundleHash,
        bytes32 subjectId,
        bytes32 role
    ) external view returns (AnchorRecord memory);

    function isAnchored(
        bytes32 bundleHash,
        bytes32 subjectId,
        bytes32 role
    ) external view returns (bool);

    function activeBundle(
        bytes32 subjectId,
        bytes32 role
    ) external view returns (bytes32);
}

Anchoring

anchorBundle MUST reject a zero bundleHash, zero subjectId, zero role, or zero documentCount.

metadataURI MAY be empty. An empty value indicates that the anchor does not provide an on-chain retrieval pointer. Applications requiring availability SHOULD enforce a non-empty URI before calling the registry.

Applications without an existing subject identifier SHOULD derive a nonzero, domain-separated subjectId from application context rather than sharing a common placeholder value.

Each record MUST be keyed by the (bundleHash, subjectId, role) triple. The same bundle hash MAY be anchored under different subjects or roles, producing independent records.

anchorBundle MUST reject a duplicate triple and MUST reject a slot that already has an active bundle. Replacement of an occupied slot MUST use supersedeBundle.

On success, the registry MUST:

store all supplied values;
set anchoredBy to msg.sender;
set anchoredAt to uint64(block.timestamp);
initialize superseded to false;
initialize supersededBy to bytes32(0);
set the active bundle for the slot; and
emit BundleAnchored.

The registry MUST restrict anchoring to authorized callers. Its authorization mechanism is implementation-defined and MUST be documented.

Supersession

supersedeBundle MUST reject a zero newBundleHash, zero subjectId, zero role, or zero documentCount. It MUST reject oldBundleHash == newBundleHash.

The old record MUST exist, MUST NOT already be superseded, and MUST be the active bundle for the specified slot. The new triple MUST NOT already exist.

The caller MUST be authorized to supersede that slot. Authorization is implementation-defined, but an unrelated authorized anchorer MUST NOT be able to take over another principal’s slot.

Supersession MUST atomically:

set the old record’s superseded field to true;
set its supersededBy field to newBundleHash;
create the new active record;
update the active slot;
emit BundleSuperseded; and
emit BundleAnchored for the new record.

The old record’s remaining fields MUST NOT change and the old record MUST remain queryable.

Queries

getAnchor MUST return the complete record for a triple and MUST revert when no record exists.

isAnchored MUST return true for every existing record, including a superseded record, and false for an unknown triple.

activeBundle MUST return the active bundle hash for a slot or bytes32(0) if the slot has never been occupied.

Recovery Interface

Administrative slot recovery is OPTIONAL. A registry that supports principal reassignment MUST implement:

pragma solidity ^0.8.20;

interface IDocumentBundleAnchorRecovery {
    event SlotPrincipalAssigned(
        bytes32 indexed subjectId,
        bytes32 indexed role,
        address indexed principal
    );

    function slotPrincipal(
        bytes32 subjectId,
        bytes32 role
    ) external view returns (address);

    function assignSlotPrincipal(
        bytes32 subjectId,
        bytes32 role,
        address principal
    ) external;
}

slotPrincipal MUST return the address currently authorized as principal for the slot or address(0) when none is assigned.

When the recovery extension is implemented, successful first anchoring and supersession MUST set the slot principal to msg.sender.

assignSlotPrincipal MUST be restricted to an authorized recovery administrator and MUST reject zero subjectId, zero role, and a zero principal. Assignment MUST emit SlotPrincipalAssigned.

Principal assignment does not itself grant general anchoring authority. A designated principal MUST also satisfy the implementation’s authorization policy before anchoring or superseding.

If a principal is assigned before first anchoring, anchorBundle MUST reject any other caller for that slot. After reassignment, the former principal MUST NOT be able to supersede that slot solely by retaining general anchoring authority.

Interface Detection

Compliant registries MUST implement ERC-165 and return true for type(IDocumentBundleAnchor).interfaceId.

Registries implementing recovery MUST also return true for type(IDocumentBundleAnchorRecovery).interfaceId.

ERC-165 reports interface support. It does not establish that a bundle was derived correctly, that referenced documents are authentic or available, or that an operator is trustworthy.

Consumer Verification

A consumer relying on an active bundle MUST:

Query activeBundle(subjectId, role) and reject bytes32(0).
Retrieve the corresponding record with getAnchor(bundleHash, subjectId, role).
Verify that the returned fields match the requested hash, subject, and role.
Verify that anchoredAt and documentCount are nonzero.
Verify that superseded is false.
Reproduce the manifest, canonical ordering, and bundle hash off-chain.

documentCount is declarative and MUST NOT be treated as independently verified by the anchoring contract.

Rationale

Why Separate Manifesting from Normalization?

Combining universal document normalization with bundle hashing would overstate what one ERC can guarantee. The manifest gives normalized document commitments a common structure. Profiles define how a particular input format produces the committed bytes and can evolve independently.

Why a Total Order Over All Five Fields?

Ordering by only role, filename, and content leaves insertion order as a hidden tie-breaker when entries differ only by media type or normalization profile. Including all five fields gives every distinct entry a deterministic position.

Why Include a Schema Identifier?

The schema identifier separates incompatible manifest versions. Without it, a future change to entry interpretation or hash derivation could reuse the same hash domain.

Why Use Subject and Role Slots?

The same document set can be relevant to multiple subjects or serve different purposes. Keying records by (bundleHash, subjectId, role) preserves those independent records, while (subjectId, role) identifies the one current bundle for a particular purpose.

Why Permit an Empty Metadata URI?

The bundle commitment remains valid without an on-chain retrieval pointer. Some deployments distribute documents through private or regulated channels, while others use content-addressed public storage. Availability policy belongs to the application and is not implied by a syntactically non-empty URI.

Why Preserve Superseded Records?

Document sets evolve through amendments, renewals, and corrections. Mutating or deleting the prior record would remove the audit trail. Supersession changes only the prior record’s forward pointer and status.

Why a Slot-Principal Recovery Extension?

An anchoring key can be compromised, revoked, or used to squat a slot. Directly attempting an administrative supersession is front-runnable because the current principal can supersede first and invalidate the administrator’s expected old hash. Atomic principal reassignment removes that race while preserving all bundle records.

Recovery introduces administrative trust, so it is separated from the core interface. Deployments preferring immutable authority can omit it.

Why Compute Bundle Hashes Off-Chain?

Normalization and sorting can be expensive. The reference canonical convenience path uses a quadratic sort and repeated memory encoding, which is suitable for tests and small bundles but inefficient for large on-chain sets. The anchoring contract accepts a precomputed bundleHash; consumers reproduce it off-chain.

Why Not Use a Merkle Root?

This ERC commits to the complete ordered manifest and is optimized for reproducing one bundle identifier, not proving membership of a single document without the rest of the manifest. Applications requiring compact membership proofs can commit a separately specified Merkle root as a document or extension field, but that construction is outside this ERC.

Why Defer PDF and Image Normalization?

PDF and image files contain format-specific metadata, incremental updates, compression choices, object ordering, color profiles, and renderer-dependent behavior. A credible profile requires exact binary fixtures and specialized review. Until then, byte-identical raw hashing is the only defined profile for those files.

Prior Art

ERC-5732 defines a generic commit-reveal mechanism. It can be used as a privacy layer around publication but does not define document entries or bundle hashing.

ERC-7208 defines general on-chain data containers. This ERC defines a document-specific commitment and lifecycle interface.

ERC-7578 includes document URI storage in a physical-asset redemption flow but does not define deterministic bundle manifesting.

ERC-3668 defines an off-chain data retrieval and verification flow. It can retrieve material referenced by an anchor but does not determine how a document bundle commitment is derived.

Backwards Compatibility

This ERC introduces new interfaces and does not change existing token or registry standards. Existing systems can store the resulting bytes32 bundle hash without changing their storage type, but ad hoc bundle hashes are not necessarily compatible with this derivation.

Existing document registries can integrate by storing this bundle hash as a document commitment or by deploying a companion IDocumentBundleAnchor registry. Composition with any particular asset registry is optional; subjectId is an application-defined nonzero identifier.

Test Cases

Implementations should test at least:

raw-byte content hashing;
RFC 8785 canonical serialization and invalid-input rejection;
Canonical XML 1.1 serialization with external entities disabled;
all profile, role, and schema constants;
ordering differences at each of the five fields;
permutation independence through the canonical hashing path;
rejection of unsorted input through the pre-sorted path;
empty, single-entry, and duplicate-entry bundles;
schema-version separation;
anchoring and querying independent triples;
rejection of occupied active slots;
multi-step supersession history;
independent use of the same bundle hash by different subjects or roles;
empty and non-empty metadata URIs;
positive and negative ERC-165 detection; and
contested-slot recovery and pre-assignment.

Normative Test Vectors

The hexadecimal byte strings in this section are authoritative. Text renderings are included only for readability. None of the inputs or canonical outputs has an implicit byte-order mark or trailing newline unless its hexadecimal form includes one.

The schema identifier for these vectors is:

SCHEMA_V1
0x1853dddb0c73884633f2ff8e736679ec654a11f704ed868aacca79d8ae4caf67

JSON Entry

The filename input contains e followed by U+0301 COMBINING ACUTE ACCENT. Filename processing selects the basename, folds ASCII uppercase characters, and applies NFC, producing the UTF-8 bytes for café.json.

input document:       {"b":2,"a":1}
input bytes:          0x7b2262223a322c2261223a317d
canonical document:   {"a":1,"b":2}
canonical bytes:      0x7b2261223a312c2262223a327d
filename input:       records/Cafe\u0301.JSON
filename input bytes: 0x7265636f7264732f43616665cc812e4a534f4e
canonical filename:   café.json
filename bytes:       0x636166c3a92e6a736f6e
role preimage:         AGREEMENT
media type preimage:  application/json
profile preimage:     NORM:JSON:RFC8785:V1
contentHash:          0xb8ffb64722137f4b100665a52e3c943f8066e8ab8ba3b427e6f4b404defd82b0
role:                 0x566614d5b403a4ea71e1ef1027b77ff1e1a13a54c7f393aa64a1368de23a5f92
mimeTypeHash:         0x82e6a468c95da6cfe399f69ee0782fd009e354a8030ea5636ea9c7db0edcf7f5
filenameHash:         0x3b40ecd25f3375868ddf559a0ef47c2dc15863a529ac592bec5e1b618bcbaf3e
normProfileId:        0x464861b0846e795db3d9c52e9c49870c7e83f2bb07f73764f7e4850151994f40
leaf:                 0xe78934e3ee972b7eae660a945de9780c77e5656203bfe437ab117413adf3ad2b

XML Entry

The backslash in the filename input is a path separator. Canonical XML 1.1 orders the unqualified attributes lexicographically. The canonical output has no trailing newline.

input document:       <doc b="2" a="1"></doc>
input bytes:          0x3c646f6320623d22322220613d2231223e3c2f646f633e
canonical document:   <doc a="1" b="2"></doc>
canonical bytes:      0x3c646f6320613d22312220623d2232223e3c2f646f633e
filename input:       Evidence\Proof.XML
filename input bytes: 0x45766964656e63655c50726f6f662e584d4c
canonical filename:   proof.xml
filename bytes:       0x70726f6f662e786d6c
role preimage:         EVIDENCE
media type preimage:  application/xml
profile preimage:     NORM:XML:C14N11:V1
contentHash:          0xde64c753c807c4620bf010c7e855bcd38bd389e980c4054b81abd5d44d45eab1
role:                 0x7477535acdef313b25d16b4871e7023fac62af68d6312bbdbdb96203a4710dc3
mimeTypeHash:         0x37aaf14a93fea5695fd8577aacfb548c98692a106d439219bfb9b83e3011ea2f
filenameHash:         0x696b36bf7095c1b1564382a37b8f5ba7d259b36be7639a7a1b50c97cd13cfe39
normProfileId:        0x72efa7a47196f4ad021a5a3758b19b14d8e09d7b7b211bf4745b35cba62e49c2
leaf:                 0x8c72daea8a7297c8d307dd41e24038ff71065f9b0932a07e9016942abbc5c9ac

Raw Entry

The input and canonical output end with one U+000A LINE FEED byte.

input document:       Hello, ERC-8326!<LF>
input bytes:          0x48656c6c6f2c204552432d38333236210a
canonical document:   Hello, ERC-8326!<LF>
canonical bytes:      0x48656c6c6f2c204552432d38333236210a
filename input:       README.TXT
filename input bytes: 0x524541444d452e545854
canonical filename:   readme.txt
filename bytes:       0x726561646d652e747874
role preimage:         SUPPORTING
media type preimage:  text/plain
profile preimage:     NORM:RAW:V1
contentHash:          0x06750728a91d155294f77f992fec49acabb0470481439ed5e3bb59854df82ec9
role:                 0xb0e9b5730d97b99270ce15f439eec98a4f9580e1dfbfb8f5c9e0e3ab71d4bca6
mimeTypeHash:         0xb25570cad408307f58d995c1dadde60bc76e94924d640305a148c9a11f8303bf
filenameHash:         0x31f491635b16d6fb45a7d770fcbcc8cbb6eae32ac98ab622631f4bc4a8c7e9ce
normProfileId:        0xbe97b35c60bb0caee86a5a99022973ef2aa47cbf9586dd34065141c6668b430b
leaf:                 0xa418892b0b93cf88e9d840cf38d36f5bfa16813774f22f5cf02d6b4fcc48375a

Bundle Vector

The entries sort in JSON, XML, raw order by their role values. Concatenating SCHEMA_V1 with the three leaf values in that order produces:

bundleHash:
0xbe712c4a5eb51d9eb303f1a5c896417a8407a420936fa210626bb66b1a6d0613

Reference Implementation

A Solidity reference implementation, hashing library, unit tests, Medusa property tests, consumer verifier, and independent audit are linked from the discussion referenced in the preamble. The implementation performs manifest ordering and hashing over supplied entries; raw JSON and XML normalization occurs off-chain.

Security Considerations

Normalization Profile Trust

The determinism guarantee is only as strong as the profile implementation. PROFILE_RAW performs no normalization. Custom profiles can be ambiguous, malicious, or incompletely specified. Consumers should verify the selected profile and reproduce the exact transformation.

Canonicalization Boundary

The Solidity hashing library receives document-entry fields and does not parse or canonicalize JSON, XML, PDF, images, filenames, or media types. A caller can submit a hash while falsely claiming that a profile was followed. Consumers must reproduce normalization and entry derivation off-chain.

Document Availability and Privacy

An anchored hash does not make its preimage available. metadataURI can become unavailable, change content, or expose sensitive information. Empty URIs are permitted. Applications should use durable retrieval policies and must not place personal, confidential, or legally restricted information directly in a public URI.

Declarative Document Count

The anchoring contract cannot verify that documentCount matches the committed manifest. Consumers should count the reproduced entries rather than trusting the stored value independently.

Authorization and Slot Squatting

A caller with anchoring authority can occupy an unassigned slot. Implementations should scope authorization appropriately or pre-assign principals for protected slots. Recovery administrators can redirect legitimate authority and therefore require strong operational controls.

Supersession Front-Running

An administrator attempting direct supersession of a contested slot can be front-run by the current principal. Implementations supporting recovery should use atomic principal reassignment before the legitimate principal supersedes the active bundle.

Hash and Encoding Assumptions

The construction relies on keccak256 collision resistance. Packed encoding is used only for fixed-width fields. Implementations must not substitute variable-length fields into the leaf or bundle encoding without introducing unambiguous length encoding and a new schema identifier.

Filename and Unicode Handling

ASCII case folding does not provide Unicode case equivalence. NFC normalization requires a conforming Unicode implementation. Different path or Unicode handling will produce different filename hashes.

No Authenticity or Legal-Effect Guarantee

A reproducible bundle hash proves agreement on committed bytes, not that a document is authentic, current, authorized, legally effective, or associated with the claimed subject.

Copyright

Directional Transfer Domain Registry

Sun, 05 Jul 2026 00:00:00 +0000

EIP #8327 - Directional Transfer Domain Registry is in Last Call status. It is authored by Chris Turner , David Hay (@david-hay), Reagan Simpson (@krumg111), Collins Musyimi (@Musyimi97) and was originally created 2026-07-05. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/erc-8327-directional-transfer-domain-registry/28936

Abstract

This Ethereum Request for Comments (ERC) defines a token-agnostic registry interface for querying directional transfer-route permission between opaque domains by asset class. For an ordered triple of sourceDomain, destinationDomain, and assetClass, the registry reports whether that route is currently permitted and exposes the evidence commitments and effective timestamp associated with its latest state.

The core interface supports immediate route permission and revocation, state retrieval, and batch queries. An optional extension supports delayed revocation with explicit initiation, cancellation, lazy effectiveness, and finalization semantics.

This ERC does not assign addresses to domains, derive asset classes, validate evidence, or enforce token transfers. A token or transfer controller that relies on a route decision must resolve the applicable domains and asset class, query the registry, and enforce the result within its transfer path.

Motivation

Transfer restrictions are commonly expressed in token-local or address-level logic. That model is appropriate when eligibility depends on a particular holder, balance, token, or transaction amount. It does not provide a common lookup surface for policies that apply to transfers between logical domains across multiple tokens sharing an asset classification.

A domain can represent a jurisdiction, regulated venue, enterprise network, game economy, decentralized autonomous organization (DAO) treasury boundary, or another application-defined context. Transfer compatibility between such domains is often directional: permission from domain A to domain B does not imply permission from B to A. The same route can also differ by asset class.

Without a shared interface, each token or controller embeds its own route table or integrates with a proprietary registry. This duplicates policy state and requires integrations to understand implementation-specific query methods.

This ERC standardizes the narrow external question:

Is the route from this source domain to this destination domain currently permitted for this asset class?

It deliberately does not answer whether a complete transfer can succeed. Balances, holder eligibility, freezes, sanctions, settlement conditions, and token-specific rules remain separate checks.

Specification

Definitions

A domain is an opaque, nonzero bytes32 identifier for an application-defined logical boundary.

An asset class is an opaque, nonzero bytes32 identifier for a category of assets to which one route policy applies.

A route is the ordered triple (sourceDomain, destinationDomain, assetClass).

A registrar is an address authorized by the implementation to modify route state.

An evidence hash is a nonzero bytes32 commitment to application-defined material supporting a route lifecycle action.

A grace period is an implementation-defined delay between initiation and effectiveness of a graceful revocation.

Core Interface

A compliant registry MUST implement:

pragma solidity ^0.8.20;

interface ITransferDomainRegistry {
   struct Route {
       bool permitted;
       uint64 effectiveAt;
       bytes32 permissionEvidenceHash;
       bytes32 revocationEvidenceHash;
   }

   event RouteSet(
       bytes32 indexed sourceDomain,
       bytes32 indexed destinationDomain,
       bytes32 indexed assetClass,
       bytes32 permissionEvidenceHash,
       uint64 effectiveAt
   );

   event RouteRevoked(
       bytes32 indexed sourceDomain,
       bytes32 indexed destinationDomain,
       bytes32 indexed assetClass,
       bytes32 revocationEvidenceHash,
       uint64 effectiveAt
   );

   function isRoutePermitted(
       bytes32 sourceDomain,
       bytes32 destinationDomain,
       bytes32 assetClass
   ) external view returns (bool);

   function getRoute(
       bytes32 sourceDomain,
       bytes32 destinationDomain,
       bytes32 assetClass
   ) external view returns (Route memory);

   function setRoute(
       bytes32 sourceDomain,
       bytes32 destinationDomain,
       bytes32 assetClass,
       bytes32 permissionEvidenceHash
   ) external;

   function revokeRoute(
       bytes32 sourceDomain,
       bytes32 destinationDomain,
       bytes32 assetClass,
       bytes32 revocationEvidenceHash
   ) external;

   function isRoutePermittedBatch(
       bytes32[] calldata sourceDomains,
       bytes32[] calldata destinationDomains,
       bytes32[] calldata assetClasses
   ) external view returns (bool[] memory permitted);
}

Route Direction and Scope

Routes MUST be directional. A permitted route (A, B, C) MUST NOT imply that (B, A, C) is permitted. Bidirectional permission requires two independently permitted routes.

Routes MUST also be asset-class scoped. A permitted route (A, B, C) MUST NOT imply permission for (A, B, D).

The registry MUST treat each route triple independently.

Route Queries

isRoutePermitted MUST return the current permission state for the exact route triple. It MUST return false for a route that has never been permitted, has been revoked immediately, or has reached the effective time of a graceful revocation.

For a given block, the result MUST be deterministic and MUST NOT depend on msg.sender, tx.origin, or caller-specific state.

getRoute MUST return the current Route representation for the exact triple. For an unknown route, it MUST return the default record in which every field is zero.

When permitted is true, effectiveAt is the time at which the current permission state became effective. When permitted is false and effectiveAt is nonzero, it is the time at which the latest revocation became effective. An unknown route has effectiveAt == 0.

Setting a Route

setRoute MUST be restricted to authorized registrars. It MUST reject a zero sourceDomain, destinationDomain, assetClass, or permissionEvidenceHash.

On success, setRoute MUST:

set permitted to true;
set effectiveAt to uint64(block.timestamp);
store the supplied permissionEvidenceHash;
set revocationEvidenceHash to bytes32(0); and
emit RouteSet with the stored values.

Calling setRoute for an already permitted or previously revoked route is allowed. The new call replaces the route’s current state and evidence fields; prior lifecycle actions remain discoverable through events.

An implementation MUST reject the call if block.timestamp cannot be represented as uint64.

Immediate Revocation

revokeRoute MUST be restricted to authorized registrars. It MUST reject a zero sourceDomain, destinationDomain, assetClass, or revocationEvidenceHash.

On success, revokeRoute MUST:

set permitted to false;
set effectiveAt to uint64(block.timestamp);
preserve the current permissionEvidenceHash;
store the supplied revocationEvidenceHash; and
emit RouteRevoked with the stored values.

For an authorized caller supplying valid nonzero arguments, revokeRoute MUST NOT revert solely because the route was unknown or already revoked. Revoking an unknown route creates a non-permitted route state with zero permission evidence and the supplied revocation evidence. Repeated revocation replaces the latest revocation timestamp and evidence and emits a new event.

An implementation MUST reject the call if block.timestamp cannot be represented as uint64.

Evidence Semantics

All evidence hashes accepted by this ERC MUST be nonzero. The registry treats them as opaque commitments and does not validate their preimages, hashing scheme, authority, correctness, or availability.

permissionEvidenceHash represents the evidence supplied for the current permission state. revocationEvidenceHash represents the evidence supplied for the current revocation state and MUST be bytes32(0) while the route is permitted.

Route state contains only the latest evidence fields. Consumers reconstructing the complete lifecycle MUST index the route events.

Batch Queries

isRoutePermittedBatch MUST revert when its three arrays have different lengths. Otherwise, it MUST return an array of the same length in which output element i equals:

isRoutePermitted(
   sourceDomains[i],
   destinationDomains[i],
   assetClasses[i]
)

Implementations MAY impose a documented maximum batch size. Consumers calling the batch function from state-changing execution SHOULD bound the input length.

Graceful Revocation Extension

Graceful revocation is OPTIONAL. A registry implementing it MUST implement both the core interface and the following extension:

pragma solidity ^0.8.20;

interface IGracefulRouteRevocation {
   struct Revocation {
       uint64 initiatedAt;
       uint64 effectiveAt;
       bytes32 revocationEvidenceHash;
       bool pending;
       bool finalized;
   }

   event RouteRevocationInitiated(
       bytes32 indexed sourceDomain,
       bytes32 indexed destinationDomain,
       bytes32 indexed assetClass,
       bytes32 revocationEvidenceHash,
       uint64 initiatedAt,
       uint64 effectiveAt
   );

   event RouteRevocationCancelled(
       bytes32 indexed sourceDomain,
       bytes32 indexed destinationDomain,
       bytes32 indexed assetClass,
       bytes32 cancellationEvidenceHash
   );

   function getRevocation(
       bytes32 sourceDomain,
       bytes32 destinationDomain,
       bytes32 assetClass
   ) external view returns (Revocation memory);

   function initiateRevocation(
       bytes32 sourceDomain,
       bytes32 destinationDomain,
       bytes32 assetClass,
       bytes32 revocationEvidenceHash
   ) external;

   function cancelRevocation(
       bytes32 sourceDomain,
       bytes32 destinationDomain,
       bytes32 assetClass,
       bytes32 cancellationEvidenceHash
   ) external;

   function finalizeRevocation(
       bytes32 sourceDomain,
       bytes32 destinationDomain,
       bytes32 assetClass
   ) external;
}

The grace-period duration and its configuration mechanism are implementation defined. The implementation MUST document that policy. Only the resulting timestamps and state transitions are standardized.

Graceful Revocation Initiation

initiateRevocation MUST be restricted to authorized registrars. It MUST reject a zero route identifier or zero revocationEvidenceHash.

It MUST revert unless isRoutePermitted currently returns true for the route and no graceful revocation is pending.

On success, it MUST:

set initiatedAt to uint64(block.timestamp);
set effectiveAt to a representable uint64 value strictly later than initiatedAt;
store the supplied revocationEvidenceHash;
set pending to true;
set finalized to false; and
emit RouteRevocationInitiated.

The route MUST remain permitted while block.timestamp < effectiveAt.

Lazy Effectiveness

When block.timestamp >= effectiveAt for a pending graceful revocation, isRoutePermitted MUST return false without requiring a finalization transaction.

During that interval, getRoute MUST return an effective route representation with:

permitted == false;
effectiveAt equal to the graceful revocation’s effectiveAt;
the existing permissionEvidenceHash; and
revocationEvidenceHash equal to the graceful revocation evidence.

The stored revocation remains pending until finalized, but the route is already non-permitted. Therefore, consumers MUST NOT infer route permission from whether RouteRevoked has been emitted.

Graceful Revocation Cancellation

cancelRevocation MUST be restricted to authorized registrars. It MUST reject a zero route identifier or zero cancellationEvidenceHash.

It MUST revert unless a revocation is pending and block.timestamp < effectiveAt.

On success, it MUST clear the revocation state and emit RouteRevocationCancelled. The route remains permitted. The cancellation evidence is emitted but is not retained in the Revocation struct; consumers requiring it MUST index the event.

Graceful Revocation Finalization

finalizeRevocation MUST reject a zero route identifier. It MUST revert unless a revocation is pending and block.timestamp >= effectiveAt.

On success, it MUST:

set pending to false;
set finalized to true;
persist the route as non-permitted;
set the route’s effectiveAt to the graceful revocation effective time;
store the graceful revocationEvidenceHash on the route; and
emit RouteRevoked exactly once for that graceful revocation.

Finalization MAY be permissionless because route effectiveness does not depend on it. Repeated or nonexistent finalization MUST NOT emit a duplicate RouteRevoked event.

The finalized Revocation record MUST remain queryable until another route lifecycle action clears it.

Interaction With Core Lifecycle Functions

In a registry implementing the graceful extension, setRoute MUST clear any pending or finalized graceful-revocation record before installing the new permission state.

revokeRoute MUST clear any pending or finalized graceful-revocation record before installing the immediate revocation state.

These actions do not emit RouteRevocationCancelled. Their respective RouteSet or RouteRevoked event records the state transition.

Domain and Asset-Class Identification

This ERC does not map accounts or tokens to domains and does not define domain or asset-class taxonomies. Applications MUST document how they derive each identifier supplied to the registry.

Identifiers SHOULD be domain separated by an application or registry namespace. The same bytes32 value in two independent registries MUST NOT be assumed to have the same meaning without an explicit coordination agreement.

An asset class MAY represent a regulatory category, asset type, product class, or a single asset when per-asset routing is required. The mapping from an individual token or asset identifier to assetClass is application defined.

Authorization

Registrar authorization is implementation defined. A registry MAY use ownership, role-based access control, governance, signatures, or another documented mechanism.

Whatever mechanism is selected, unauthorized callers MUST NOT be able to call setRoute, revokeRoute, initiateRevocation, or cancelRevocation successfully.

Interface Detection

Compliant registries MUST implement ERC-165 and return true for type(ITransferDomainRegistry).interfaceId.

Registries implementing graceful revocation MUST also return true for type(IGracefulRouteRevocation).interfaceId.

ERC-165 indicates interface support only. It does not prove that route data is correct, that the registry is governed appropriately, or that a token or controller enforces registry decisions.

Consumer Enforcement

A consumer enforcing a route decision SHOULD perform the following within the same transaction as the governed transfer:

Resolve the sender and receiver to the applicable source and destination domains using an authoritative application-defined mechanism.
Resolve the token or asset to the applicable asset class.
Call isRoutePermitted(sourceDomain, destinationDomain, assetClass).
Reject the transfer when the result is false.
Apply all independent token, identity, balance, freeze, sanctions, and settlement checks required by the application.

Checking route permission off-chain before submitting a later transfer does not provide atomic enforcement because route state can change between the check and execution.

Rationale

Why Directional Routes?

Compatibility can be asymmetric. A domain may allow outbound transfers to another domain without accepting inbound transfers from it. Encoding each direction separately avoids an unsafe assumption of reciprocity.

Why Opaque Domains?

Standardizing one universal domain taxonomy would couple the interface to a particular legal, organizational, or application model. Opaque identifiers let independent systems use the same route interface while defining their own meaning and resolution mechanism.

Why Scope Routes by Asset Class?

The same pair of domains can permit one category of assets and prohibit another. Asset-class scoping allows multiple assets governed by the same route policy to share one entry without requiring per-token route storage.

Why an External Registry?

An external registry allows multiple tokens and controllers to consult one route-policy surface. It also separates route administration from token implementation and avoids requiring every supported token standard to adopt the same storage model.

Why `isRoutePermitted` Instead of `canTransfer`?

The registry evaluates only the supplied route triple. A name such as canTransfer would imply checks that the interface does not perform, including balances, account eligibility, freezes, sanctions, and token-specific rules.

Why Require Nonzero Evidence Commitments?

A zero hash is ambiguous between absent evidence and a meaningful commitment. Requiring a nonzero value makes absence explicit at the application layer and prevents route records from silently appearing documented when no commitment was supplied.

Why Is Immediate Revocation Idempotent Over Route Existence?

An authorized registrar should be able to establish a route as non-permitted without first proving that it was previously enabled. This supports defensive revocation and repeated emergency actions while retaining each action in the event history.

Why Graceful Revocation as an Extension?

Some systems need immediate emergency closure. Others have in-flight settlement or notice obligations that require a future effective time. Keeping delayed revocation optional preserves a small core interface while standardizing the additional lifecycle only for deployments that need it.

Why Lazy Effectiveness?

If route closure depended on a later finalization transaction, a missing or censored transaction could leave the route permitted indefinitely. Lazy effectiveness makes the announced timestamp authoritative. Finalization exists to persist state and emit the terminal event, not to activate the revocation.

Why Keep Grace-Period Configuration Implementation Defined?

Appropriate delay depends on the applicable settlement cycle and policy. The interface exposes the resulting effectiveAt timestamp, which consumers need for interoperability, without prescribing one configuration mechanism or duration.

Prior Art

ERC-3643 defines a regulated-token architecture with identity registries, compliance modules, and token lifecycle functions. This ERC does not define holder eligibility or token behavior; it provides one route-policy input that such systems may optionally consume.

ERC-7943 defines a universal real-world asset (RWA) token interface including transfer eligibility, freezing, and forced transfer behavior. This ERC is an external registry keyed by domains and asset classes rather than a token behavior interface.

Backwards Compatibility

This ERC introduces new interfaces and does not modify existing token standards. Existing ERC-20, ERC-721, ERC-1155, ERC-3643, ERC-7943, and custom tokens remain unaffected unless their transfer path is explicitly integrated with a registry.

The registry does not require a token to expose a new interface. A token, compliance module, transfer controller, bridge, or settlement contract can call the registry as an external dependency.

Implementations that do not need delayed revocation implement only ITransferDomainRegistry. Implementations that need delayed revocation additionally implement IGracefulRouteRevocation.

Test Cases

Implementations should test at least:

directional independence of (A, B, C) and (B, A, C);
asset-class independence for the same domain pair;
caller-independent route queries;
default false and zero state for unknown routes;
nonzero validation for route identifiers and every evidence field;
setting, repeated setting, immediate revocation, repeated revocation, and re-enablement;
immediate revocation of an unknown route;
route evidence retrieval and event history;
batch output equivalence with individual queries;
mismatched batch lengths and implementation batch limits;
graceful initiation only for a currently permitted route;
permission before, and non-permission at, graceful effectiveAt;
lazy getRoute behavior before finalization;
cancellation before expiry and rejection at or after expiry;
finalization persistence and duplicate-event prevention;
immediate revocation and re-enablement while graceful state exists;
positive and negative ERC-165 detection; and
unauthorized lifecycle calls.

Reference Implementation

A Solidity reference implementation includes immediate and graceful registry contracts, a canonical route-key library, unit and fuzz tests, Medusa property tests, deployment scripts, and an independent audit. These materials are linked from the official discussion thread.

The reference implementation uses role-based registrar authorization, a deployment-time fixed grace period, a maximum batch size of 256, and:

keccak256(
   abi.encodePacked(sourceDomain, destinationDomain, assetClass)
)

as its internal route key. Those storage and administration choices are not required for conforming implementations.

Security Considerations

No Enforcement Guarantee

The registry is advisory. A token or controller that does not query and enforce the result can transfer regardless of route state. ERC-165 support by either contract does not prove that enforcement occurs.

Domain and Asset-Class Resolution

The registry evaluates caller-supplied identifiers. Incorrect, stale, or malicious resolution of an address or token to a domain or asset class can bypass the intended policy even when the registry itself is correct. Consumers must secure and document their resolution mechanism.

Registry and Registrar Trust

A malicious or compromised registrar can permit prohibited routes, revoke valid routes, replace evidence commitments, or repeatedly change state. Users must evaluate the registry’s authorization, governance, upgrade, and key management policies.

Evidence Limitations

An evidence hash proves only commitment to unknown bytes if the preimage is available. It does not establish authenticity, legal effect, correctness, authority, or continued availability. Consumers relying on evidence must obtain and verify the preimage under an agreed hashing and document scheme.

Transaction Atomicity and Races

An off-chain route query can become stale before a transfer executes. Enforcing consumers should query the registry and complete or reject the transfer within the same transaction.

Graceful Revocation Risk

The route remains permitted before effectiveAt, so the grace period creates a known window in which transfers can continue. Applications must choose a delay appropriate to their threat and settlement models. Emergency closure should use immediate revocation.

An authorized registrar can clear graceful state by calling setRoute or revokeRoute. Consumers requiring governance constraints around reinstatement must enforce them in the registry’s authorization policy.

Lazy Revocation and Event-Only Indexers

A graceful revocation becomes effective without a transaction at effectiveAt. An indexer that waits only for RouteRevoked can report stale permission until finalization. Consumers must evaluate timestamps or call the view interface.

Batch Gas Consumption

Although batch lookup is a view function, another contract can invoke it from a state-changing transaction. Unbounded arrays can consume excessive gas or make the calling operation unavailable. Implementations and callers should apply appropriate limits.

Identifier Collisions and Cross-Registry Meaning

Opaque identifiers have no global namespace. Two applications or registries can assign the same value to different domains or asset classes. Consumers must scope interpretation to the selected registry and its documented namespace.

Timestamp Dependence

Graceful revocation depends on block.timestamp. Block producers can influence timestamps within protocol bounds. Applications requiring exact wall-clock cutoffs must account for this uncertainty.

Copyright

Subject-Linked Compliance Event Log

Sun, 05 Jul 2026 00:00:00 +0000

EIP #8328 - Subject-Linked Compliance Event Log is in Last Call status. It is authored by Chris Turner , David Hay (@david-hay), Reagan Simpson (@krumg111), Collins Musyimi (@Musyimi97) and was originally created 2026-07-05. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/erc-8328-subject-linked-compliance-event-log/28937

Abstract

This Ethereum Request for Comments (ERC) defines an append-only interface for subject-linked compliance event records. Each record includes a subject, event type, outcome, technical actor, claimed authority, involved parties, evidence commitment, optional evidence location, versioned payload profile, operation reference, occurrence time, and recording time.

Events are indexed per subject and by event type. Corrections are recorded as new events linked to earlier records. A forward pointer on the corrected record prevents correction forks and allows consumers to resolve the terminal event in a correction chain.

This ERC is a reporting interface. It does not define compliance policy, identity verification, transfer restrictions, legal authority, or regulatory compliance. Stored records are attributable assertions, not proof that the reported action occurred or was lawful.

Motivation

Compliance-relevant lifecycle actions are currently represented through application-specific events, token-local state changes, generic attestations, and off-chain databases. This fragmentation makes it difficult for contracts, indexers, auditors, and reporting systems to query comparable records across implementations.

Existing token and compliance standards primarily define token behavior, holder eligibility, transfer validation, or entity classification. Those capabilities do not provide a common stored record for subject-level lifecycle actions such as issuance, redemption, freezing, know-your-customer (KYC) status changes, regulatory holds, policy changes, and forced transfers.

A shared event-log interface provides:

one query surface for records attached to an application-defined subject;
explicit separation between the recorder and the claimed authority;
structured party roles rather than untyped address arrays;
evidence commitments and optional retrieval references;
versioned payload profiles for interoperable event-specific data;
per-type indexing without scanning an entire subject history; and
append-only, fork-free correction provenance.

The log can be called by a token, compliance module, governance executor, multisig, or other authorized recorder. It does not require any particular token standard or enforcement architecture.

Specification

Definitions

A subject is an application-defined entity identified by subjectId and, optionally, contextualized by subjectType.

A compliance event is a stored assertion about a compliance-relevant action or state transition concerning a subject.

An actor is msg.sender at the time recordEvent is called. It identifies the technical recorder, not necessarily the human decision-maker or legal authority.

An authority is the recorder’s claimed legal, regulatory, contractual, or governance basis for the event. The claim is not verified by the log.

A party is an EVM address associated with an explicit role in the event.

A payload profile is a versioned schema declaring how payload is encoded.

A correction chain is a linear sequence of events linked by correctsIndex and correctedByIndex.

A terminal event is an event whose correctedByIndex equals NO_CORRECTED_BY.

Sentinel Values

Implementations MUST use:

uint256 constant NO_CORRECTION = type(uint256).max;
uint256 constant NO_CORRECTED_BY = 0;

NO_CORRECTION indicates that an event does not correct an earlier event.

NO_CORRECTED_BY indicates that an event has no successor correction. Event index zero is safe for this sentinel because a correction’s index is always greater than the index it corrects and therefore can never be zero.

Core Interface

A compliant log MUST implement:

pragma solidity ^0.8.20;

interface IComplianceEventLog {
    struct Party {
        address addr;
        bytes32 role;
    }

    struct ComplianceEvent {
        bytes32 subjectId;
        bytes32 subjectType;
        bytes32 eventType;
        bytes32 outcome;
        address actor;
        bytes32 authority;
        Party[] parties;
        bytes32 evidenceHash;
        string evidenceURI;
        bytes32 payloadProfileId;
        bytes payload;
        bytes32 operationRef;
        uint64 occurredAt;
        uint64 recordedAt;
        uint256 correctsIndex;
        uint256 correctedByIndex;
    }

    event ComplianceEventRecorded(
        bytes32 indexed subjectId,
        bytes32 indexed eventType,
        address indexed actor,
        uint256 eventIndex,
        bytes32 outcome,
        bytes32 authority,
        uint64 occurredAt,
        uint256 correctsIndex
    );

    function recordEvent(
        bytes32 subjectId,
        bytes32 subjectType,
        bytes32 eventType,
        bytes32 outcome,
        bytes32 authority,
        Party[] calldata parties,
        bytes32 evidenceHash,
        string calldata evidenceURI,
        bytes32 payloadProfileId,
        bytes calldata payload,
        bytes32 operationRef,
        uint64 occurredAt,
        uint256 correctsIndex
    ) external returns (uint256 eventIndex);

    function getEvent(
        bytes32 subjectId,
        uint256 eventIndex
    ) external view returns (ComplianceEvent memory);

    function currentEventIndex(
        bytes32 subjectId,
        uint256 eventIndex
    ) external view returns (uint256);

    function isEventCurrent(
        bytes32 subjectId,
        uint256 eventIndex
    ) external view returns (bool);

    function eventCount(
        bytes32 subjectId
    ) external view returns (uint256);

    function eventCountByType(
        bytes32 subjectId,
        bytes32 eventType
    ) external view returns (uint256);

    function eventByTypeAt(
        bytes32 subjectId,
        bytes32 eventType,
        uint256 ordinal
    ) external view returns (uint256 eventIndex);

    function lastRecordedEventByType(
        bytes32 subjectId,
        bytes32 eventType
    ) external view returns (uint256 eventIndex);
}

Recording Semantics

Event indices MUST be zero-based and scoped per subjectId. The returned eventIndex MUST equal the subject’s event count immediately before the new event is appended.

recordEvent MUST be restricted to authorized recorders. The authorization mechanism is implementation defined and MUST be documented.

For every accepted event, the implementation MUST:

store every supplied field without changing its value, except as explicitly specified by this ERC;
set actor to msg.sender;
set recordedAt to uint64(block.timestamp);
initialize correctedByIndex to NO_CORRECTED_BY;
append the event index to the subject and event-type index;
emit ComplianceEventRecorded; and
return the new event index.

The implementation MUST reject the call if block.timestamp cannot be represented as uint64.

evidenceHash MUST NOT be bytes32(0). evidenceURI MAY be empty when the evidence location is private, unavailable on-chain, or exchanged out of band. An empty URI does not weaken the requirement for a nonzero commitment.

The parties array MUST contain no more than 10 entries. payload MUST contain no more than 2048 bytes. Empty party arrays and empty payloads are allowed.

This ERC does not require nonzero values for subjectId, subjectType, eventType, outcome, authority, operationRef, party addresses, party roles, or payloadProfileId. Applications requiring stricter semantics MUST enforce and document them before calling recordEvent.

Temporal Semantics

occurredAt represents when the reported action occurred. recordedAt represents when the record was appended on-chain.

recordEvent MUST revert when occurredAt > block.timestamp.

Implementations SHOULD impose and document a maximum backdating interval. Different deployments can require different intervals, so the duration is not standardized by this ERC.

The log does not independently verify occurredAt. It is an assertion by the recorder.

Append-Only Semantics

Once recorded, every event field MUST remain immutable except correctedByIndex. Events MUST NOT be deleted.

Updating correctedByIndex is permitted only when accepting a valid correction under the correction rules below.

Correction Semantics

An original or non-correction event MUST use NO_CORRECTION and MUST NOT use EVT_CORRECTION, which is defined in the Event Types section below:

correctsIndex = NO_CORRECTION
eventType != EVT_CORRECTION

A correction event MUST use:

correctsIndex = index of the corrected event
eventType = EVT_CORRECTION

For a correction, recordEvent MUST:

require correctsIndex to identify an earlier event under the same subjectId;
require the target event’s correctedByIndex to equal NO_CORRECTED_BY;
authorize the correction under the implementation’s documented correction policy;
set the target’s correctedByIndex to the new correction event index; and
append the correction as a new event.

The correction policy MUST NOT permit an ordinary recorder to correct another actor’s event merely because both addresses can record events. It MAY authorize the original actor, a designated corrector, or an administrator. The policy MUST be documented.

Each event can be corrected at most once, preventing forks. A correction event can itself be corrected later, producing a linear chain.

The correcting record does not rewrite the original event’s event type or payload. Recorders MUST place the corrected assertion in the new event’s fields or an application-defined correction payload. Consumers MUST interpret the terminal event under the applicable profile and application policy.

Current-State Queries

currentEventIndex MUST revert when eventIndex >= eventCount(subjectId). Otherwise, it MUST follow correctedByIndex until reaching NO_CORRECTED_BY and return the terminal event index. Calling it on a terminal event MUST return the supplied index.

isEventCurrent MUST revert when eventIndex >= eventCount(subjectId) and otherwise return whether correctedByIndex == NO_CORRECTED_BY.

Because corrections always point to earlier events and each event has at most one successor, conforming correction chains cannot contain cycles or branches.

Event Retrieval and Counting

getEvent MUST return the complete stored event and MUST revert when eventIndex >= eventCount(subjectId).

eventCount MUST return the number of events stored under a subject.

eventCountByType MUST return the number of events recorded with the exact eventType under a subject.

eventByTypeAt MUST return the event index at the specified zero-based ordinal and MUST revert when the ordinal is outside the type-specific index.

lastRecordedEventByType MUST return the greatest event index recorded with the exact event type and MUST revert when no matching event exists.

lastRecordedEventByType describes recording order. It does not select the event with the greatest occurredAt and does not resolve correction chains.

Correction events are indexed under EVT_CORRECTION, not under the event type they correct. Consumers resolving an earlier event MUST use currentEventIndex rather than assuming the last event of the original type is its current state.

Subject Identifiers

subjectId and subjectType are opaque to the log. Applications SHOULD use a documented, domain-separated derivation and MUST NOT assume that equal subject identifiers from independent logs have equal meaning without an explicit coordination agreement.

The following subject-type identifiers are defined:

bytes32 constant SUBJECT_TOKEN =
    keccak256("ERC-8328:SUBJECT_TYPE:TOKEN");
bytes32 constant SUBJECT_ADDRESS =
    keccak256("ERC-8328:SUBJECT_TYPE:ADDRESS");
bytes32 constant SUBJECT_ASSET =
    keccak256("ERC-8328:SUBJECT_TYPE:ASSET");
bytes32 constant SUBJECT_CASE =
    keccak256("ERC-8328:SUBJECT_TYPE:CASE");

Applications MAY define custom subject types using a documented namespace and version.

Event Types

The following event-type identifiers are defined:

bytes32 constant EVT_ISSUANCE =
    keccak256("ERC-8328:EVENT_TYPE:ISSUANCE:V1");
bytes32 constant EVT_TRANSFER =
    keccak256("ERC-8328:EVENT_TYPE:TRANSFER:V1");
bytes32 constant EVT_REDEMPTION =
    keccak256("ERC-8328:EVENT_TYPE:REDEMPTION:V1");
bytes32 constant EVT_FREEZE =
    keccak256("ERC-8328:EVENT_TYPE:FREEZE:V1");
bytes32 constant EVT_UNFREEZE =
    keccak256("ERC-8328:EVENT_TYPE:UNFREEZE:V1");
bytes32 constant EVT_FORCED_TRANSFER =
    keccak256("ERC-8328:EVENT_TYPE:FORCED_TRANSFER:V1");
bytes32 constant EVT_KYC_APPROVED =
    keccak256("ERC-8328:EVENT_TYPE:KYC_APPROVED:V1");
bytes32 constant EVT_KYC_REVOKED =
    keccak256("ERC-8328:EVENT_TYPE:KYC_REVOKED:V1");
bytes32 constant EVT_KYC_UPDATED =
    keccak256("ERC-8328:EVENT_TYPE:KYC_UPDATED:V1");
bytes32 constant EVT_REGULATORY_HOLD =
    keccak256("ERC-8328:EVENT_TYPE:REGULATORY_HOLD:V1");
bytes32 constant EVT_HOLD_RELEASED =
    keccak256("ERC-8328:EVENT_TYPE:HOLD_RELEASED:V1");
bytes32 constant EVT_ALLOWLIST_ADDED =
    keccak256("ERC-8328:EVENT_TYPE:ALLOWLIST_ADDED:V1");
bytes32 constant EVT_ALLOWLIST_REMOVED =
    keccak256("ERC-8328:EVENT_TYPE:ALLOWLIST_REMOVED:V1");
bytes32 constant EVT_POLICY_CHANGE =
    keccak256("ERC-8328:EVENT_TYPE:POLICY_CHANGE:V1");
bytes32 constant EVT_CORRECTION =
    keccak256("ERC-8328:EVENT_TYPE:CORRECTION:V1");

EVT_TRANSFER is intended for compliance-significant transfer records, not as a replacement for a token’s ordinary transfer event. Applications SHOULD avoid duplicating every routine token transfer unless the additional compliance record is required by their reporting policy.

Custom event types SHOULD use a domain-separated namespace and explicit version.

Party Roles

The following party-role identifiers are defined:

bytes32 constant ROLE_SENDER =
    keccak256("ERC-8328:PARTY_ROLE:SENDER");
bytes32 constant ROLE_RECEIVER =
    keccak256("ERC-8328:PARTY_ROLE:RECEIVER");
bytes32 constant ROLE_TARGET =
    keccak256("ERC-8328:PARTY_ROLE:TARGET");
bytes32 constant ROLE_BENEFICIARY =
    keccak256("ERC-8328:PARTY_ROLE:BENEFICIARY");
bytes32 constant ROLE_CONTROLLER =
    keccak256("ERC-8328:PARTY_ROLE:CONTROLLER");
bytes32 constant ROLE_SUBJECT =
    keccak256("ERC-8328:PARTY_ROLE:SUBJECT");

Custom party roles SHOULD use a documented namespace and version.

The base Party type contains an EVM address. It cannot carry an arbitrary hashed identity without changing the interface. Applications needing private or non-address party identifiers require a separate extension or SHOULD omit those parties from the public record.

Outcomes

The following outcome identifiers are defined:

bytes32 constant OUTCOME_APPROVED =
    keccak256("ERC-8328:OUTCOME:APPROVED");
bytes32 constant OUTCOME_DENIED =
    keccak256("ERC-8328:OUTCOME:DENIED");
bytes32 constant OUTCOME_PENDING =
    keccak256("ERC-8328:OUTCOME:PENDING");
bytes32 constant OUTCOME_EXECUTED =
    keccak256("ERC-8328:OUTCOME:EXECUTED");
bytes32 constant OUTCOME_EXPIRED =
    keccak256("ERC-8328:OUTCOME:EXPIRED");
bytes32 constant OUTCOME_REVOKED =
    keccak256("ERC-8328:OUTCOME:REVOKED");

This ERC does not define or enforce an event-type and outcome compatibility matrix. Applications MAY constrain combinations before recording. Consumers MUST NOT infer that a combination was validated merely because the log accepted it.

Authority Identifiers

The following common authority identifiers are defined:

bytes32 constant AUTHORITY_INTERNAL_POLICY =
    keccak256("ERC-8328:AUTHORITY:INTERNAL_POLICY:V1");
bytes32 constant AUTHORITY_COURT_ORDER =
    keccak256("ERC-8328:AUTHORITY:COURT_ORDER:V1");
bytes32 constant AUTHORITY_REGULATOR =
    keccak256("ERC-8328:AUTHORITY:REGULATOR:V1");

Custom authority identifiers SHOULD use a documented namespace and version. The field records a claim and does not authenticate the named authority.

Payload Profiles

The following payload-profile identifiers and ABI encodings are defined:

bytes32 constant PAYLOAD_TRANSFER_V1 =
    keccak256("ERC-8328:PAYLOAD:TRANSFER:V1");
// abi.encode(
//     address from,
//     address to,
//     uint256 amount,
//     bytes32 routeRef
// )

bytes32 constant PAYLOAD_FREEZE_V1 =
    keccak256("ERC-8328:PAYLOAD:FREEZE:V1");
// abi.encode(
//     address target,
//     uint256 amount,
//     uint64 expiresAt,
//     bytes32 reason
// )

bytes32 constant PAYLOAD_KYC_V1 =
    keccak256("ERC-8328:PAYLOAD:KYC:V1");
// abi.encode(
//     address subject,
//     bytes32 jurisdiction,
//     bytes32 riskTier,
//     uint64 expiresAt
// )

bytes32 constant PAYLOAD_FORCED_TRANSFER_V1 =
    keccak256("ERC-8328:PAYLOAD:FORCED_TRANSFER:V1");
// abi.encode(
//     address from,
//     address to,
//     uint256 amount,
//     bytes32 legalBasis
// )

A recorder declaring one of these profiles MUST encode the payload exactly as specified. Consumers MUST inspect payloadProfileId before decoding.

The log is not required to decode payloads or validate compatibility between a payload profile, event type, parties, and outcome. Consumers SHOULD reject a malformed known profile. Unknown profile identifiers MUST be treated as opaque bytes.

Custom payload profiles SHOULD use a documented namespace and version and MUST define an exact encoding.

Operation References

operationRef is an application-defined correlation identifier linking the record to an underlying action or workflow. It MAY be bytes32(0) when no such reference is available.

A contract cannot access its transaction hash or final log index while executing. Therefore, this ERC does not require a transaction-hash and log-index derivation. Applications SHOULD compute a correlation identifier before the underlying action and recordEvent calls when both occur in one transaction.

Recording an event in the same transaction as the underlying action provides stronger linkage than recording it later, but the log still does not prove that the record accurately describes that action.

Interface Detection

Compliant logs MUST implement ERC-165 and return true for type(IComplianceEventLog).interfaceId.

ERC-165 indicates interface support only. It does not establish recorder trustworthiness, evidence validity, authority, policy correctness, or legal compliance.

Rationale

Why Subject-Linked Records?

An address-only or token-only key would exclude projects, assets, cases, policies, and application-defined entities. An opaque subject identifier allows one query model while leaving identity and namespace semantics to the application.

Why Separate Actor and Authority?

The technical account recording an event and the claimed basis for the action are different facts. A module can execute several actions under different mandates, while multiple modules can act under the same mandate.

Why Structured Parties?

An untyped address list cannot distinguish a sender, receiver, target, beneficiary, or controller. Explicit roles improve machine interpretation while keeping the set extensible.

Why Require an Evidence Commitment but Permit an Empty URI?

Every record should commit to the evidence representation used by the recorder, but public retrieval can be inappropriate for confidential or regulated data. A nonzero hash preserves the commitment while an optional URI permits private distribution.

Why Versioned Payload Profiles?

Opaque bytes without a declared schema prevent interoperable decoding. Versioned profile identifiers let consumers recognize stable base encodings and safely preserve unknown custom payloads.

Why Correction Events Instead of Mutable Records?

Replacing an event would erase the prior assertion. A correction chain retains the full history and identifies the current terminal record. The forward pointer and single-successor rule prevent competing corrections to the same event.

Why Index Corrections Under Their Own Type?

A correction is a distinct lifecycle action. Indexing it under EVT_CORRECTION preserves the original event-type history and lets consumers query correction activity directly. Chain-resolution helpers provide current state when needed.

Why Store Records Rather Than Emit Events Only?

EVM contracts cannot read historical logs. Storing records allows on-chain consumers to retrieve event details, traverse correction chains, and iterate by event type. Emitted events remain useful for off-chain indexing.

Why Keep Policy Validation Outside the Log?

The same event and outcome identifiers can be used under different legal and application policies. The log standardizes representation and provenance, not the rule engine deciding which combinations are valid.

Prior Art

ERC-20 defines fungible-token transfers and balance changes. This ERC records subject-linked lifecycle assertions and does not require each record to correspond to an ERC-20 balance change.

ERC-3643 defines regulated-token behavior, identity registries, compliance modules, and lifecycle operations. This ERC is a reporting layer that such a system may call; it does not replace enforcement or identity checks.

ERC-7943 defines real-world asset (RWA) token behavior including transfer eligibility, freezing, and forced transfers. This ERC records attributed lifecycle assertions independently of any token interface.

Backwards Compatibility

This ERC introduces a new interface and does not modify existing token, identity, attestation, or compliance standards.

An existing token or compliance module can call a companion IComplianceEventLog without changing its base token interface. Systems that do not integrate with the log are unaffected.

The subject identifier is application defined, so adoption does not require a particular asset registry or token standard.

Test Cases

Implementations should test at least:

zero-based, per-subject event indexing;
subject isolation and event-type indexing;
actor assignment to msg.sender;
recording-time assignment and future-event rejection;
the configured backdating policy;
rejection of zero evidence commitments;
empty and non-empty evidence URIs;
party and payload size boundaries;
original-event and correction-event guards;
correction target bounds and same-subject behavior;
original-actor, administrator, and unauthorized correction paths;
correction fork prevention and multi-step linear chains;
currentEventIndex from original, intermediate, and terminal events;
isEventCurrent for corrected and terminal events;
invalid event and ordinal queries;
recording-order behavior of lastRecordedEventByType;
correction indexing under EVT_CORRECTION;
exact base payload-profile encodings;
opaque handling of unknown payload profiles;
acceptance of unconstrained event-type and outcome combinations; and
positive and negative ERC-165 detection.

Reference Implementation

A Solidity reference implementation, constants library, unit tests, Medusa property tests, and independent audit are linked from the official discussion thread.

The reference implementation:

uses recorder and administrator roles;
permits the original actor or an administrator with recorder authority to correct an event;
limits party arrays to 10 entries;
limits payloads to 2048 bytes;
rejects events backdated by more than 30 days;
stores unknown payload profiles without decoding them; and
does not validate event-type and outcome combinations.

Role design and the 30-day backdating window are reference deployment choices. The size limits and externally observable interface behavior are requirements of this ERC.

Security Considerations

Recorder Trust

The log proves that an authorized address recorded particular bytes. It does not prove that the record is true. A compromised, malicious, or incorrectly authorized recorder can submit false or misleading events.

Claimed Authority

authority is self-asserted. A recorder can claim a court order, regulator, or internal policy that does not exist or does not authorize the action. Consumers must verify authority evidence independently.

Underlying Action Verification

A compliance event is not proof that the underlying issuance, transfer, freeze, KYC decision, or other action occurred. Consumers requiring that proof must verify the referenced operation and its relationship to the record.

Correction Authorization

Fork prevention does not determine who is entitled to correct a record. A weak correction policy can let one recorder supersede another recorder’s assertions. Implementations must document and enforce correction authority.

Long Correction Chains

currentEventIndex traverses on-chain correction pointers. Although chains are linear and acyclic, a long chain can consume substantial gas or make an on-chain call impractical. Applications should avoid unnecessary repeated corrections and may resolve long histories off-chain.

Backdating

occurredAt is supplied by the recorder. Rejecting future timestamps prevents one class of invalid input but does not establish historical accuracy. A documented backdating limit reduces, but does not eliminate, fabricated history.

Privacy and Data Protection

All event fields, dynamic payloads, party addresses, and URIs stored on a public chain are permanently observable. Implementations must not place personal, confidential, investigative, or legally restricted information on-chain merely because the interface permits it.

Public-chain deployments should use opaque or salted subject identifiers, minimal party arrays, generalized outcomes, redacted payloads, and evidence commitments whose preimages are distributed through appropriate access controls. Hashing low-entropy personal data without a secret salt does not provide meaningful privacy.

Evidence Availability and Ambiguity

A nonzero evidence hash does not make evidence available or identify the hashing and document scheme by itself. Implementations must document how evidence commitments are derived and how authorized consumers obtain the preimage.

Payload Confusion

The log can store malformed known payloads and arbitrary unknown profiles. A consumer that decodes without first checking payloadProfileId can misinterpret attacker-controlled bytes. Consumers must use profile-aware decoding and reject malformed known profiles.

Event-Type and Outcome Confusion

The base log does not validate event-type and outcome combinations. Consumers must not treat a stored combination as policy-approved unless the recorder’s application enforces the applicable matrix.

Storage Growth and Retrieval Costs

The log is append-only and grows monotonically. Authorization, bounded dynamic fields, reporting-frequency policy, and operational monitoring are necessary to control storage costs and spam.

Event and Storage Interpretation

Off-chain indexers can reconstruct timelines from events, but on-chain contracts cannot read historical logs. On-chain consumers must use storage getters. Indexers should reconcile events with storage when resolving correction chains and current state.

Copyright

Subject-Linked Impact Snapshot Log

Sun, 05 Jul 2026 00:00:00 +0000

EIP #8329 - Subject-Linked Impact Snapshot Log is in Last Call status. It is authored by Chris Turner , David Hay (@david-hay), Reagan Simpson (@krumg111), Collins Musyimi (@Musyimi97) and was originally created 2026-07-05. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/erc-8329-subject-linked-impact-snapshot-log/28938

Abstract

This Ethereum Request for Comments (ERC) defines an append-only interface for reporting quantitative impact indicator snapshots against application-defined subjects. Each snapshot records a signed value, decimal precision, unit, completed measurement period, methodology commitment and location, reporter, recording time, and correction provenance.

The core interface supports per-subject storage, per-indicator indexing, exact period lookup, and fork-free correction chains. Optional interfaces support append-only endorsement or dispute attestations and future methodology supersession with active and pending methodology discovery.

This ERC standardizes representation and lifecycle behavior. It does not define which indicators or methodologies are valid, verify reported measurements, credential reporters or attestors, prevent overlapping claims, or provide an impact score.

Motivation

Impact measurements such as emissions, carbon offsets, renewable energy, water treatment, employment, beneficiaries, biodiversity area, and diverted waste are commonly distributed through reports and application-specific data formats. On-chain systems lack a common interface for associating these values with a subject, measurement period, unit, and methodology while preserving later corrections.

A single mutable value cannot distinguish a new reporting period from a restatement of an earlier measurement. It also erases the prior assertion when updated. Generic attestations can represent individual claims but do not by themselves define per-indicator time-series indexing, exact-period uniqueness, correction chains, or methodology transitions.

This ERC provides:

subject-linked, period-bounded quantitative snapshots;
signed values with explicit decimals and units;
one original snapshot per exact subject, indicator, and period;
additive, fork-free corrections;
per-indicator iteration and exact-period current-state lookup;
required methodology commitments and retrieval references;
optional append-only endorsement and dispute attestations; and
optional active and scheduled methodology version discovery.

The interfaces can be deployed independently of any token, registry, identity, or accounting system.

Specification

Definitions

A subject is an application-defined entity identified by subjectId.

An indicator is an application-defined measured quantity identified by indicatorId.

A snapshot is one reported value for an indicator, subject, and measurement period.

A measurement period is the half-open interval [periodStart, periodEnd).

An original snapshot is the first snapshot occupying an exact subject, indicator, and period slot.

A correction chain is a linear sequence of snapshots connected by correctsIndex and correctedByIndex.

A terminal snapshot is a snapshot whose correctedByIndex equals zero.

A methodology is the documented process used to measure or calculate a reported value.

An attestation is an append-only endorsement or dispute attached to a specific snapshot.

Sentinel Value

Implementations MUST use:

uint256 constant NO_CORRECTION = type(uint256).max;

correctsIndex == NO_CORRECTION identifies an original snapshot. correctedByIndex == 0 identifies a snapshot with no successor correction.

Index zero is safe as the corrected-by sentinel because every correction index is greater than the snapshot it corrects and therefore cannot be zero.

Core Snapshot Interface

A compliant log MUST implement:

pragma solidity ^0.8.20;

interface IImpactSnapshotLog {
    struct IndicatorSnapshot {
        bytes32 subjectId;
        bytes32 indicatorId;
        int256 value;
        uint8 decimals;
        bytes32 unit;
        uint64 periodStart;
        uint64 periodEnd;
        bytes32 methodologyHash;
        string methodologyURI;
        address reportedBy;
        uint64 reportedAt;
        uint256 correctsIndex;
        uint256 correctedByIndex;
    }

    event SnapshotRecorded(
        bytes32 indexed subjectId,
        bytes32 indexed indicatorId,
        uint256 indexed snapshotIndex,
        int256 value,
        uint8 decimals,
        bytes32 unit,
        uint64 periodStart,
        uint64 periodEnd,
        bytes32 methodologyHash,
        uint256 correctsIndex,
        address reportedBy
    );

    function recordSnapshot(
        bytes32 subjectId,
        bytes32 indicatorId,
        int256 value,
        uint8 decimals,
        bytes32 unit,
        uint64 periodStart,
        uint64 periodEnd,
        bytes32 methodologyHash,
        string calldata methodologyURI,
        uint256 correctsIndex
    ) external returns (uint256 snapshotIndex);

    function getSnapshot(
        bytes32 subjectId,
        uint256 snapshotIndex
    ) external view returns (IndicatorSnapshot memory);

    function snapshotCount(
        bytes32 subjectId
    ) external view returns (uint256);

    function indicatorSnapshotCount(
        bytes32 subjectId,
        bytes32 indicatorId
    ) external view returns (uint256);

    function indicatorSnapshotAt(
        bytes32 subjectId,
        bytes32 indicatorId,
        uint256 ordinal
    ) external view returns (uint256 snapshotIndex);

    function latestIndicatorSnapshot(
        bytes32 subjectId,
        bytes32 indicatorId
    ) external view returns (uint256 snapshotIndex);

    function currentSnapshotForPeriod(
        bytes32 subjectId,
        bytes32 indicatorId,
        uint64 periodStart,
        uint64 periodEnd
    ) external view returns (uint256 snapshotIndex);
}

Value, Decimal, and Unit Semantics

The represented quantity is:

value * 10^(-decimals)

value is signed because an impact measurement can be negative. This ERC does not impose a maximum decimal precision below the uint8 type limit. Consumers MUST handle the declared precision safely and MUST NOT assume the value is nonnegative.

unit SHOULD be the keccak256 hash of a documented canonical unit string. Applications SHOULD use International System of Units (SI) or Unified Code for Units of Measure (UCUM)-compatible representations when available and MUST document exact case, spelling, pluralization, and conversion rules for custom or zero-valued unit identifiers.

This ERC does not require a nonzero subjectId, indicatorId, or unit. Applications requiring stricter namespaces MUST enforce and document them.

Measurement Periods

periodStart is inclusive and periodEnd is exclusive.

recordSnapshot MUST revert unless:

periodStart < periodEnd <= block.timestamp

Only completed measurement periods can be recorded.

An exact period slot is identified by (subjectId, indicatorId, periodStart, periodEnd). A log MUST accept at most one original snapshot for an exact slot. Once occupied, revisions to that slot MUST use correction provenance.

Different periods MAY overlap. This ERC does not determine whether overlapping measurements are additive, duplicative, or methodologically compatible.

Recording Semantics

Snapshot indices MUST be zero-based and scoped per subjectId. The returned snapshotIndex MUST equal the subject’s snapshot count before the new snapshot is appended.

recordSnapshot MUST be restricted to authorized reporters. The authorization mechanism is implementation defined and MUST be documented.

For every accepted snapshot, the log MUST:

store the supplied snapshot fields;
set reportedBy to msg.sender;
set reportedAt to uint64(block.timestamp);
initialize correctedByIndex to zero;
append the snapshot index to the indicator-specific index;
make the snapshot discoverable for its exact period; and
emit SnapshotRecorded.

methodologyHash MUST NOT be bytes32(0), and methodologyURI MUST NOT be empty.

The methodology hash MUST be keccak256 of the exact methodology document bytes under a documented representation. Consumers MUST retrieve the document and reproduce the commitment before relying on it.

Correction Semantics

An original snapshot MUST use correctsIndex == NO_CORRECTION.

A correction MUST:

identify an earlier snapshot under the same subjectId;
use the same indicatorId, periodStart, and periodEnd as its target;
target a snapshot whose correctedByIndex is zero; and
be authorized under the implementation’s documented correction policy.

When a correction is accepted, the log MUST set the target snapshot’s correctedByIndex to the new snapshot index. No other target field may change.

Each snapshot can be corrected at most once, preventing forks. A correction snapshot can itself be corrected, producing a linear chain.

The correction policy MUST NOT permit an ordinary reporter to correct another reporter’s snapshot merely because both addresses can report. It MAY authorize the original reporter, a designated corrector, or an administrator.

A correction MAY change value, decimals, unit, methodology, and reporter, subject to the active methodology rules of an implementation supporting the methodology extension.

Snapshot Queries

getSnapshot MUST return the complete stored snapshot and MUST revert when snapshotIndex >= snapshotCount(subjectId).

snapshotCount MUST return the number of snapshots recorded for a subject.

indicatorSnapshotCount MUST return the number of snapshots recorded for an exact subject and indicator, including corrections.

indicatorSnapshotAt MUST return the per-subject snapshot index at the specified zero-based indicator ordinal and MUST revert when the ordinal is outside the indicator-specific index.

latestIndicatorSnapshot MUST return the most recently recorded snapshot index for the indicator and MUST revert when none exists. It describes recording order, not the greatest periodEnd, and does not necessarily identify the current value for a particular period.

currentSnapshotForPeriod MUST return the terminal snapshot index for the exact subject, indicator, periodStart, and periodEnd. It MUST revert when no snapshot occupies that period slot.

Consumers querying a specific reporting period SHOULD use currentSnapshotForPeriod rather than latestIndicatorSnapshot.

Indicator Identifiers

The following indicator identifiers are defined:

bytes32 constant CARBON_OFFSET =
    keccak256("ERC-8329:INDICATOR:CARBON_OFFSET");
bytes32 constant CARBON_EMITTED =
    keccak256("ERC-8329:INDICATOR:CARBON_EMITTED");
bytes32 constant ENERGY_GENERATED =
    keccak256("ERC-8329:INDICATOR:ENERGY_GENERATED");
bytes32 constant ENERGY_SAVED =
    keccak256("ERC-8329:INDICATOR:ENERGY_SAVED");
bytes32 constant WATER_TREATED =
    keccak256("ERC-8329:INDICATOR:WATER_TREATED");
bytes32 constant JOBS_CREATED =
    keccak256("ERC-8329:INDICATOR:JOBS_CREATED");
bytes32 constant BENEFICIARIES =
    keccak256("ERC-8329:INDICATOR:BENEFICIARIES");
bytes32 constant BIODIVERSITY_AREA =
    keccak256("ERC-8329:INDICATOR:BIODIVERSITY_AREA");
bytes32 constant WASTE_DIVERTED =
    keccak256("ERC-8329:INDICATOR:WASTE_DIVERTED");

Custom indicators SHOULD use:

keccak256("ERC-8329:INDICATOR:<NAMESPACE>:<NAME>:<VERSION>")

Applications MUST document indicator definitions, boundaries, calculation rules, and any mapping to external taxonomies. A generic identifier such as keccak256("CUSTOM") SHOULD NOT be used because it does not provide semantic separation.

Unit Identifiers

The following unit identifiers are defined:

bytes32 constant UNIT_TCO2E = keccak256("tCO2e");
bytes32 constant UNIT_KWH = keccak256("kWh");
bytes32 constant UNIT_M3 = keccak256("m3");
bytes32 constant UNIT_FTE = keccak256("FTE");
bytes32 constant UNIT_PERSONS = keccak256("persons");
bytes32 constant UNIT_HECTARES = keccak256("hectares");
bytes32 constant UNIT_TONNES = keccak256("tonnes");

UNIT_FTE uses FTE to denote full-time equivalent; the preimage string remains "FTE" for stability.

The defined indicator identifiers do not mandate one unit. Reporters and consumers MUST inspect the stored unit and methodology rather than inferring a unit from indicatorId alone.

Attestation Extension

Attestation is OPTIONAL. An implementation supporting it MUST implement:

pragma solidity ^0.8.20;

interface IImpactAttestation {
    struct Attestation {
        address attestor;
        bool endorsed;
        bytes32 evidenceHash;
        string evidenceURI;
        uint64 attestedAt;
    }

    event SnapshotAttested(
        bytes32 indexed subjectId,
        uint256 indexed snapshotIndex,
        address indexed attestor,
        bool endorsed,
        bytes32 evidenceHash,
        uint256 attestationIndex
    );

    function attestSnapshot(
        bytes32 subjectId,
        uint256 snapshotIndex,
        bool endorsed,
        bytes32 evidenceHash,
        string calldata evidenceURI
    ) external returns (uint256 attestationIndex);

    function attestationCount(
        bytes32 subjectId,
        uint256 snapshotIndex
    ) external view returns (uint256);

    function getAttestation(
        bytes32 subjectId,
        uint256 snapshotIndex,
        uint256 attestationIndex
    ) external view returns (Attestation memory);
}

attestSnapshot MUST reject an unknown snapshot and a zero evidenceHash. evidenceURI MAY be empty.

The implementation MUST set attestor to msg.sender, set attestedAt to uint64(block.timestamp), append the attestation, emit SnapshotAttested, and return its zero-based per-snapshot index.

The reporter address stored on the snapshot MUST NOT attest that snapshot. This is address-level separation only; it does not establish organizational, affiliate, financial, or legal independence.

Attestations MUST be immutable and non-deletable. The same attestor MAY submit multiple attestations for the same snapshot, including a later assessment that differs from an earlier one. Consumers MUST evaluate the complete history.

Attestations MAY be added to corrected or nonterminal snapshots. Consumers MUST decide whether an attestation to an earlier snapshot applies to any correction. This ERC does not carry attestations forward automatically.

Attestor authorization and credentialing are implementation defined and MUST be documented.

attestationCount MUST return the number of attestations for the exact snapshot. getAttestation MUST return the requested record and MUST revert when the attestation index is outside that snapshot’s history.

Methodology Versioning Extension

Methodology versioning is OPTIONAL. An implementation supporting it MUST implement:

pragma solidity ^0.8.20;

interface IMethodologyVersioning {
    event MethodologySuperseded(
        bytes32 indexed subjectId,
        bytes32 indexed indicatorId,
        bytes32 oldMethodologyHash,
        bytes32 newMethodologyHash,
        uint256 effectiveFromOrdinal
    );

    function supersedeMethodology(
        bytes32 subjectId,
        bytes32 indicatorId,
        bytes32 oldMethodologyHash,
        bytes32 newMethodologyHash,
        string calldata newMethodologyURI,
        uint256 effectiveFromOrdinal
    ) external;

    function activeMethodology(
        bytes32 subjectId,
        bytes32 indicatorId
    ) external view returns (
        bytes32 methodologyHash,
        string memory methodologyURI
    );

    function pendingMethodology(
        bytes32 subjectId,
        bytes32 indicatorId
    ) external view returns (
        bytes32 newMethodologyHash,
        string memory newMethodologyURI,
        uint256 effectiveFromOrdinal,
        bool pending
    );
}

Methodology Initialization and Enforcement

The first snapshot for a subject and indicator MUST initialize its active methodology to the snapshot’s methodologyHash and methodologyURI.

After initialization, each new snapshot for that subject and indicator MUST use the methodology hash active at its indicator-specific ordinal.

The snapshot’s methodologyURI MUST remain nonempty, but this ERC does not require it to equal the URI returned by activeMethodology. Multiple locators can reference the same committed methodology bytes. Consumers MUST verify the retrieved bytes against the active hash.

activeMethodology MUST return the methodology required for the next snapshot. Before initialization, it MUST return bytes32(0) and an empty URI.

Methodology Supersession

supersedeMethodology MUST be restricted under a documented authorization policy and MUST revert unless:

a methodology has already been initialized;
oldMethodologyHash equals the active methodology;
newMethodologyHash is nonzero;
newMethodologyURI is nonempty;
no future supersession is already pending; and
effectiveFromOrdinal is greater than or equal to the current indicatorSnapshotCount.

If effectiveFromOrdinal equals the current indicator count, the new methodology becomes active immediately for the next snapshot.

If it is greater than the current count, the supersession is pending. Existing snapshots and snapshots before the effective ordinal continue to use the old methodology. The new methodology becomes active when the current indicator count reaches effectiveFromOrdinal.

Every successful supersession MUST emit MethodologySuperseded. Existing snapshot fields MUST NOT change.

Implementations MAY impose a documented maximum future lookahead.

Pending Methodology Discovery

While a future supersession has not reached its effective ordinal, pendingMethodology MUST return the scheduled hash, URI, ordinal, and pending == true.

When no supersession is scheduled, or once its effective ordinal has been reached, it MUST return bytes32(0), an empty URI, zero, and false.

Once the ordinal has been reached, activeMethodology MUST expose the new methodology even if no state-changing call has yet persisted an internal transition.

Historical values recalculated under a new methodology MUST be submitted as corrections. They MUST NOT mutate existing snapshots.

Interface Detection

Compliant core logs MUST implement ERC-165 and return true for type(IImpactSnapshotLog).interfaceId.

Implementations supporting optional extensions MUST also return true for the corresponding IImpactAttestation and IMethodologyVersioning interface IDs.

ERC-165 indicates interface support only. It does not establish measurement accuracy, methodology validity, reporter or attestor credentials, evidence quality, or independence.

Rationale

Why Append-Only Snapshots?

Impact data changes through new periods, corrected measurements, and revised methodologies. Append-only storage preserves each assertion and makes revisions visible instead of replacing history.

Why One Original Per Exact Period?

Allowing multiple unrelated originals for the same indicator and exact period would create competing current values. Requiring later revisions to use correction provenance provides one resolvable chain.

Why Permit Overlapping Periods?

Monthly, quarterly, annual, project-phase, and rolling measurements can legitimately overlap. The interface cannot determine whether an overlap is valid. Consumers aggregating values must apply methodology-specific rules to avoid double counting.

Why Use `int256`?

Measurements can be negative. Net emissions, energy savings relative to a baseline, or other indicators can move in either direction.

Why Both Latest and Period-Specific Queries?

The most recently recorded snapshot can concern an old period, such as a late correction. latestIndicatorSnapshot supports monitoring recording activity, while currentSnapshotForPeriod resolves the current value for an exact period.

Why Require Methodology Metadata?

A value and unit are insufficient without the process that produced them. Requiring both a commitment and a retrieval reference makes the declared methodology independently verifiable when the document remains available.

Why Methodology Versioning as an Extension?

Some deployments need only immutable per-snapshot methodology references. Others require a governed active methodology for future reports. Separating the extension allows the core log to remain usable without prescribing methodology governance.

Why Attestation as an Extension?

Not every deployment requires endorsement or dispute records. The optional interface permits independent assessment histories without making credential policy part of the core snapshot log.

Why Not Replace Earlier Attestations?

An attestor’s changed view is itself relevant history. Appending the later assessment preserves both statements and lets consumers apply their own recency and credential policies.

Backwards Compatibility

This ERC introduces new interfaces and does not modify existing token, registry, credential, attestation, or accounting standards.

An existing application can deploy a companion snapshot log and use its own application-defined subject namespace. No token contract changes are required unless the token itself records snapshots.

Implementations can adopt only the core interface or additionally expose either optional extension. Consumers use ERC-165 to detect supported interfaces.

Test Cases

Implementations should test at least:

zero-based per-subject indexing and subject isolation;
per-indicator counts, ordinals, and latest-recorded lookup;
completed, zero-length, and future period validation;
positive, zero, and negative values with varying decimals;
methodology hash and URI requirements;
one original per exact period;
overlapping but nonidentical periods;
correction bounds, authorization, period matching, and fork prevention;
multi-step correction chains and exact-period terminal lookup;
methodology initialization and active-methodology enforcement;
immediate and future methodology supersession;
pending methodology hash, URI, ordinal, and activation discovery;
pending-supersession exclusivity and implementation lookahead limits;
attestation evidence requirements and empty evidence URIs;
same-address self-attestation rejection;
repeated endorsement and dispute histories;
attestations to current and corrected snapshots;
unknown snapshot and attestation queries; and
positive and negative ERC-165 detection for every supported interface.

Reference Implementation

A Solidity reference implementation, constants library, example integrations, unit tests, Medusa property tests, deployment scripts, and independent audit are linked from the official discussion thread.

The reference implementation:

uses reporter, attestor, and administrator roles;
allows a reporter to correct its own snapshot and an administrator-reporter to correct another reporter’s snapshot;
rejects completed-period duplicates unless correction provenance is used;
implements all three interfaces;
blocks same-address self-attestation; and
limits scheduled methodology supersession to 1,000 future indicator ordinals.

Role assignments and the 1,000-ordinal lookahead are reference deployment choices rather than core interface requirements.

Security Considerations

Reporter Trust

The log proves that an authorized address reported a value. It does not verify the measurement, source data, calculation, unit, period boundaries, or methodology application. False data remains false when recorded immutably.

Methodology Integrity and Availability

A methodology commitment is useful only when consumers can obtain the exact document representation and reproduce its hash. A URI can disappear, change content, require authorization, or expose sensitive information. Deployments should use durable storage and document the hashing representation.

Methodology Governance

An authorized party can supersede a methodology with one that produces more favorable results. Events and pending-methodology queries make the transition visible but do not establish its legitimacy. Consumers must evaluate methodology governance independently.

Correction Authorization and Chain Length

A weak correction policy can let one reporter supersede another’s measurement. Implementations must document correction authority.

Period lookup traverses correction pointers. Although chains are linear and acyclic, excessive corrections can make on-chain resolution expensive.

Attestor Credentials and Independence

Blocking the exact reporter address prevents only direct self-attestation. The same organization can control multiple addresses, and an attestor role does not prove professional qualification, financial independence, or legal authority. Consumers must evaluate credential and conflict policies.

Conflicting Attestations

The interface permits multiple endorsements and disputes without computing a consensus result. Counting addresses is not a reliable trust model because addresses are cheap and credentials can differ. Consumers need an external attestor-selection and weighting policy.

Double Counting and Overlapping Claims

Exact-period uniqueness applies only within one subject and indicator slot. Overlapping periods, related indicators, multiple subjects, and independent registries can represent the same underlying impact. Consumers must reconcile boundaries and methodologies before aggregation.

Privacy

Subjects, values, periods, methodology URIs, and attestation evidence can reveal commercial, personal, geographic, or site-sensitive information. Public-chain deployments should use opaque subject identifiers, redacted documents, and access-controlled evidence distribution where appropriate. Hashing low-entropy sensitive data without a secret salt does not provide meaningful privacy.

Unit and Decimal Handling

Consumers that ignore units, decimals, sign, or conversion rules can produce materially incorrect aggregates. Implementations should use checked arithmetic, explicit normalization, and methodology-aware conversion.

Timestamp Dependence

Completed-period validation uses block.timestamp, which block producers can influence within protocol bounds. Applications requiring exact wall-clock cutoffs must account for that uncertainty.

Storage Growth

Snapshots and attestations are append-only. Authorization, reporting-frequency policy, and operational monitoring are necessary to control storage costs and spam.

Copyright

Subject-Linked NAV Snapshot Oracle

Sun, 05 Jul 2026 00:00:00 +0000

EIP #8330 - Subject-Linked NAV Snapshot Oracle is in Last Call status. It is authored by Chris Turner , David Hay (@david-hay), Reagan Simpson (@krumg111), Collins Musyimi (@Musyimi97) and was originally created 2026-07-05. It is in the ERC category of type Standards Track. Please review and note any changes that should block acceptance.

The author has requested that discussions happen at the following URL: https://ethereum-magicians.org/t/erc-8330-subject-linked-nav-snapshot-oracle/28939

Abstract

This Ethereum Request for Comments (ERC) defines an interface for publishing and querying subject-linked net asset value (NAV) snapshots. Each stream is keyed by (subjectId, currency) and has one configured NAV basis. Snapshots include signed NAV, decimal precision, valuation and publication timestamps, provider attribution, methodology references, and correction provenance.

The core interface supports raw and staleness-aware latest-value queries, provider-specific history, correction-chain resolution, and administrative invalidation that preserves records while excluding invalid snapshots from current-value queries. An optional aggregation interface defines deterministic lower-median aggregation across provider submissions sharing a valuation timestamp.

This ERC standardizes publication and query semantics. It does not calculate NAV, credential providers, verify methodologies, establish asset backing, or guarantee that NAV is an executable market or redemption price.

Motivation

Periodic valuations for funds, private credit, real estate, infrastructure, commodities, and other illiquid or administratively priced assets differ from continuous exchange prices. Consumers need to know what the value represents, when the underlying valuation was measured, when it was published, who supplied it, and whether it is too old for the intended use.

Existing price and quote interfaces do not necessarily preserve valuation history, provider identity, methodology references, restatement provenance, or separate publication-age and valuation-age checks. Bespoke NAV contracts also use incompatible stream keys and latest-value semantics.

This ERC provides:

independent (subjectId, currency) NAV streams;
stream-level basis configuration preventing provider disagreement over per-unit, per-share, or total interpretation;
provider-attributed historical snapshots;
one original provider submission per valuation timestamp;
fork-free corrections and current-chain helpers;
administrative invalidation for compromised or disputed terminal snapshots;
separate publication and valuation staleness signals; and
optional deterministic aggregation with quorum and deviation reporting.

The interface can serve vaults, settlement systems, reporting applications, and other consumers while leaving valuation policy and provider governance to each deployment.

Specification

Definitions

A stream is the namespace identified by (subjectId, currency).

A NAV basis states whether NAV represents one underlying unit, one share or token, or the total value of the subject.

A provider is the address recorded as publishing a snapshot.

A valuation timestamp is the asserted as-of time of the valuation.

A publication timestamp is the block timestamp at which the snapshot was recorded.

A terminal snapshot is a snapshot whose correctedByIndex equals NO_CORRECTED_BY.

A current snapshot is a terminal snapshot that has not been invalidated.

A publication heartbeat is the maximum accepted time since publication.

A maximum valuation age is the maximum accepted time since the valuation timestamp.

Sentinel Values

Implementations MUST use:

uint256 constant NO_CORRECTION = type(uint256).max;
uint256 constant NO_CORRECTED_BY = 0;

NO_CORRECTION identifies an original snapshot. NO_CORRECTED_BY identifies a snapshot with no successor correction.

Index zero is safe as the corrected-by sentinel because a correction index is always greater than its target and therefore cannot be zero.

Core Interface

A compliant oracle MUST implement:

pragma solidity ^0.8.20;

interface INAVSnapshotOracle {
    struct NAVSnapshot {
        bytes32 subjectId;
        bytes32 currency;
        bytes32 navBasis;
        int256 nav;
        uint8 decimals;
        uint64 valuationTimestamp;
        uint64 publishedAt;
        address provider;
        bytes32 methodologyHash;
        string methodologyURI;
        uint256 correctsIndex;
        uint256 correctedByIndex;
    }

    event NAVPublished(
        bytes32 indexed subjectId,
        bytes32 indexed currency,
        address indexed provider,
        uint256 snapshotIndex,
        int256 nav,
        uint8 decimals,
        bytes32 navBasis,
        uint64 valuationTimestamp,
        bytes32 methodologyHash,
        uint256 correctsIndex
    );

    event StalenessConfigUpdated(
        bytes32 indexed subjectId,
        bytes32 indexed currency,
        uint64 heartbeat,
        uint64 maxValuationAge
    );

    event NAVBasisConfigured(
        bytes32 indexed subjectId,
        bytes32 indexed currency,
        bytes32 navBasis
    );

    event NAVSnapshotInvalidated(
        bytes32 indexed subjectId,
        bytes32 indexed currency,
        address indexed provider,
        uint256 snapshotIndex,
        address invalidatedBy,
        bytes32 reasonHash
    );

    function publishNAV(
        bytes32 subjectId,
        bytes32 currency,
        bytes32 navBasis,
        int256 nav,
        uint8 decimals,
        uint64 valuationTimestamp,
        bytes32 methodologyHash,
        string calldata methodologyURI,
        uint256 correctsIndex
    ) external returns (uint256 snapshotIndex);

    function setNAVBasis(
        bytes32 subjectId,
        bytes32 currency,
        bytes32 navBasis
    ) external;

    function invalidateSnapshot(
        bytes32 subjectId,
        bytes32 currency,
        uint256 snapshotIndex,
        bytes32 reasonHash
    ) external;

    function isSnapshotInvalidated(
        bytes32 subjectId,
        bytes32 currency,
        uint256 snapshotIndex
    ) external view returns (bool);

    function setStalenessConfig(
        bytes32 subjectId,
        bytes32 currency,
        uint64 heartbeat,
        uint64 maxValuationAge
    ) external;

    function streamNAVBasis(
        bytes32 subjectId,
        bytes32 currency
    ) external view returns (bytes32 navBasis);

    function latestNAV(
        bytes32 subjectId,
        bytes32 currency
    ) external view returns (
        int256 nav,
        uint8 decimals,
        bytes32 navBasis,
        uint64 valuationTimestamp,
        uint64 publishedAt,
        address provider
    );

    function latestNAVStatus(
        bytes32 subjectId,
        bytes32 currency
    ) external view returns (
        int256 nav,
        uint8 decimals,
        bytes32 navBasis,
        uint64 valuationTimestamp,
        uint64 publishedAt,
        address provider,
        bool isPublishStale,
        bool isValuationStale
    );

    function getSnapshot(
        bytes32 subjectId,
        bytes32 currency,
        uint256 snapshotIndex
    ) external view returns (NAVSnapshot memory);

    function currentSnapshotIndex(
        bytes32 subjectId,
        bytes32 currency,
        uint256 snapshotIndex
    ) external view returns (uint256);

    function isSnapshotCurrent(
        bytes32 subjectId,
        bytes32 currency,
        uint256 snapshotIndex
    ) external view returns (bool);

    function snapshotCount(
        bytes32 subjectId,
        bytes32 currency
    ) external view returns (uint256);

    function latestNAVByProvider(
        bytes32 subjectId,
        bytes32 currency,
        address provider
    ) external view returns (NAVSnapshot memory);

    function providerSnapshotCount(
        bytes32 subjectId,
        bytes32 currency,
        address provider
    ) external view returns (uint256);

    function providerSnapshotAt(
        bytes32 subjectId,
        bytes32 currency,
        address provider,
        uint256 ordinal
    ) external view returns (uint256 snapshotIndex);

    function heartbeat(
        bytes32 subjectId,
        bytes32 currency
    ) external view returns (uint64);

    function maxValuationAge(
        bytes32 subjectId,
        bytes32 currency
    ) external view returns (uint64);
}

Stream Scope

Snapshot indices MUST be zero-based and scoped independently to each (subjectId, currency) stream.

This ERC does not require nonzero subjectId or currency values. Applications requiring stricter namespaces MUST enforce and document them.

NAV Basis

The following basis identifiers are defined:

bytes32 constant PER_UNIT =
    keccak256("ERC-8330:NAV_BASIS:PER_UNIT");
bytes32 constant PER_SHARE =
    keccak256("ERC-8330:NAV_BASIS:PER_SHARE");
bytes32 constant TOTAL =
    keccak256("ERC-8330:NAV_BASIS:TOTAL");

PER_UNIT represents one unit of the underlying asset. PER_SHARE represents one share or token in a fund or pool. TOTAL represents the total NAV of the subject.

An authorized configurer MUST call setNAVBasis before the first publication to a stream. The function MUST:

accept only PER_UNIT, PER_SHARE, or TOTAL;
reject a stream that already contains snapshots;
reject a stream whose basis was already configured;
store the basis permanently; and
emit NAVBasisConfigured.

streamNAVBasis MUST return the configured basis or bytes32(0) for an unconfigured stream.

publishNAV MUST reject an unconfigured stream and any supplied basis that does not equal its configured basis.

Provider-selected basis changes are prohibited. Stream-level configuration prevents incompatible submissions from disabling aggregation at a shared valuation timestamp.

NAV and Decimal Semantics

The represented NAV is:

nav * 10^(-decimals)

nav is signed because liabilities can exceed assets. Consumers MUST handle negative and zero values explicitly.

publishNAV MUST reject:

decimals > 18;
nav == type(int256).min; and
a magnitude greater than:

uint256(type(int256).max) / (10 ** uint256(18 - decimals))

This bound ensures that a conforming aggregation implementation can safely normalize every accepted value to 18 decimal places.

Currency Identifiers

The following fiat currency identifiers are defined:

bytes32 constant USD = keccak256("ERC-8330:CURRENCY:USD");
bytes32 constant EUR = keccak256("ERC-8330:CURRENCY:EUR");
bytes32 constant GBP = keccak256("ERC-8330:CURRENCY:GBP");
bytes32 constant KES = keccak256("ERC-8330:CURRENCY:KES");
bytes32 constant ZMW = keccak256("ERC-8330:CURRENCY:ZMW");

Additional ISO 4217 currencies SHOULD use:

keccak256("ERC-8330:CURRENCY:<CODE>")

Token-denominated streams SHOULD derive currency as:

keccak256(
    abi.encodePacked(
        "ERC-8330:CURRENCY:TOKEN",
        chainId,
        tokenAddress
    )
)

Including both chain ID and token address prevents equal addresses on different chains from sharing a currency identifier.

Other denominations SHOULD use an application-documented, domain-separated identifier and MUST NOT reuse an ISO code unless the denomination is that fiat currency.

Publication Semantics

publishNAV MUST be restricted to authorized providers. Provider authorization is implementation defined and MUST be documented.

For every accepted snapshot, the oracle MUST:

set provider to msg.sender;
set publishedAt to uint64(block.timestamp);
initialize correctedByIndex to NO_CORRECTED_BY;
append the snapshot to the stream and provider history;
update current-value and provider/timestamp indexes;
emit NAVPublished; and
return the new stream-scoped index.

valuationTimestamp MUST NOT be greater than block.timestamp. methodologyHash MUST NOT be bytes32(0).

methodologyURI MAY be empty only when the deployment documents how consumers retrieve the exact methodology representation out of band. The hash derivation MUST be documented. It MAY commit to raw document bytes or a deterministic document-bundle commitment.

The oracle MUST reject the call if block.timestamp cannot be represented as uint64.

Provider and Valuation Uniqueness

A provider MAY publish at most one current original snapshot for an exact stream and valuationTimestamp.

If that provider/timestamp slot is occupied, a revision MUST use correction provenance. Other providers MAY publish independent originals for the same stream and valuation timestamp.

Correction Semantics

An original snapshot MUST use correctsIndex == NO_CORRECTION.

A correction MUST:

identify an earlier snapshot in the same stream;
target a terminal, non-invalidated snapshot;
be published by the same provider as the target;
use the same valuationTimestamp and navBasis as the target; and
target the provider’s current snapshot for that valuation timestamp.

When accepted, the target’s correctedByIndex MUST be set to the new snapshot index. No other target field may change.

Before invalidation, each snapshot can have at most one successor correction. A correction can itself be corrected, creating a linear current chain. A correction MAY change NAV, decimals, methodology, and methodology URI.

Invalidation

invalidateSnapshot MUST be restricted under a documented administrative or governance policy. It MUST reject a zero reasonHash, unknown snapshot, nonterminal snapshot, or already invalidated snapshot.

On success, the oracle MUST:

preserve the invalidated snapshot record;
permanently mark it invalidated;
exclude it from latest-value, provider-latest, current-chain, quorum, aggregation, and deviation calculations defined by the optional Aggregation Extension below;
recompute affected latest and quorum pointers; and
emit NAVSnapshotInvalidated.

If an original snapshot is invalidated, its provider/timestamp slot MUST become available for a replacement original.

If a correction is invalidated, its direct predecessor MUST become terminal again and the provider/timestamp slot MUST point to that predecessor. The provider can then publish a replacement correction.

In a longer correction chain, invalidating the terminal restores only its direct predecessor. Administrators MAY unwind additional snapshots by invalidating each newly restored terminal in turn.

Invalidation does not erase correctsIndex history. Replacement corrections can create multiple historical records that reference the same predecessor, but only one non-invalidated branch can be current. Consumers reconstructing history MUST account for NAVSnapshotInvalidated events.

An invalidated snapshot MUST NOT be corrected or restored.

isSnapshotInvalidated MUST revert for an unknown index and otherwise return the permanent invalidation state.

Current-Chain Queries

currentSnapshotIndex MUST revert for an unknown index. It MUST follow correctedByIndex to a terminal snapshot and return that index only if the terminal is not invalidated. It MUST revert when no current terminal remains.

isSnapshotCurrent MUST revert for an unknown index and otherwise return true only when the snapshot is terminal and not invalidated.

Latest NAV Queries

latestNAV MUST return the current snapshot with the greatest valuationTimestamp, regardless of staleness. When multiple current snapshots share that valuation timestamp, it MUST return the most recently published one; if publication timestamps are equal, the greater snapshot index wins.

A late correction to an older valuation timestamp MUST NOT replace a current snapshot with a later valuation timestamp as the stream’s latest NAV.

latestNAV MUST revert when no current snapshot exists.

latestNAVByProvider MUST apply the same valuation and publication ordering to that provider’s current snapshots and MUST revert when the provider has no current snapshot.

Historical Queries

getSnapshot MUST return the preserved record for any valid index, including a corrected or invalidated snapshot, and MUST revert for an unknown index.

snapshotCount MUST include every published snapshot, including corrections and invalidated records.

providerSnapshotCount and providerSnapshotAt MUST expose the provider’s complete publication history, including corrected and invalidated snapshots. providerSnapshotAt MUST revert for an out-of-range ordinal.

Staleness Configuration

An authorized configurer MUST be able to set a nonzero publication heartbeat and nonzero maxValuationAge independently for each stream. Successful changes MUST emit StalenessConfigUpdated.

heartbeat and maxValuationAge MUST return zero while the corresponding value is unconfigured.

Configuration authorization is implementation defined and MUST be documented.

Staleness Semantics

latestNAVStatus MUST return the same snapshot selected by latestNAV plus two independent flags:

isPublishStale = block.timestamp > publishedAt + heartbeat
isValuationStale =
    block.timestamp > valuationTimestamp + maxValuationAge

A value is not stale exactly at its threshold boundary.

latestNAVStatus MUST revert when either staleness threshold is unconfigured or when no current snapshot exists. It MUST NOT mutate state or emit events.

Consumers MUST evaluate both flags. Recent publication of an old valuation can be publication-fresh but valuation-stale.

Aggregation Extension

Aggregation is OPTIONAL. An implementation supporting it MUST implement:

pragma solidity ^0.8.20;

interface INAVAggregation {
    event NAVDeviationDetected(
        bytes32 indexed subjectId,
        bytes32 indexed currency,
        uint64 valuationTimestamp,
        int256 minNav,
        int256 maxNav,
        uint256 deviationBps
    );

    event AggregationConfigUpdated(
        bytes32 indexed subjectId,
        bytes32 indexed currency,
        uint256 quorum,
        uint256 deviationThresholdBps
    );

    function setAggregationConfig(
        bytes32 subjectId,
        bytes32 currency,
        uint256 quorum,
        uint256 deviationThresholdBps
    ) external;

    function aggregatedNAV(
        bytes32 subjectId,
        bytes32 currency
    ) external view returns (
        int256 nav,
        uint8 decimals,
        bytes32 navBasis,
        uint64 valuationTimestamp,
        uint256 providerCount,
        bool isPublishStale,
        bool isValuationStale
    );

    function providerSubmissionCount(
        bytes32 subjectId,
        bytes32 currency
    ) external view returns (uint256);

    function providerSubmissionAt(
        bytes32 subjectId,
        bytes32 currency,
        uint256 index
    ) external view returns (
        uint256 snapshotIndex,
        address provider,
        int256 nav,
        uint8 decimals,
        bytes32 navBasis,
        uint64 valuationTimestamp,
        uint64 publishedAt
    );

    function latestAggregationTimestamp(
        bytes32 subjectId,
        bytes32 currency
    ) external view returns (uint64);

    function quorum(
        bytes32 subjectId,
        bytes32 currency
    ) external view returns (uint256);

    function deviationThreshold(
        bytes32 subjectId,
        bytes32 currency
    ) external view returns (uint256);
}

Aggregation Configuration

setAggregationConfig MUST be restricted to authorized configurers. It MUST reject a zero quorum and a deviation threshold greater than 10,000 basis points. Implementations MAY impose a documented maximum provider count and MUST reject a quorum above that maximum.

Successful configuration MUST emit AggregationConfigUpdated and MUST account for historical timestamps that already satisfy the new quorum.

quorum and deviationThreshold MUST return zero while unconfigured.

Eligible Provider Submissions

For one valuation timestamp, at most one submission per provider is eligible. That submission is the provider’s current snapshot for the timestamp. Corrected, invalidated, and detached historical snapshots MUST be excluded.

A valuation timestamp is aggregation-eligible when its number of eligible providers is at least the configured quorum.

The latest aggregation timestamp MUST be the greatest eligible valuation timestamp, not the timestamp of the most recent publication.

latestAggregationTimestamp, providerSubmissionCount, providerSubmissionAt, and aggregatedNAV MUST revert when quorum is unconfigured or no valuation timestamp meets quorum.

providerSubmissionCount MUST return the eligible provider count at the latest aggregation timestamp.

providerSubmissionAt MUST return eligible submissions in provider first-seen order for that timestamp and MUST revert when index is outside the eligible set.

Median Aggregation

aggregatedNAV MUST normalize all eligible values to the greatest submitted decimal precision:

normalizedNav = nav * 10^(maxDecimals - decimals)

It MUST sort normalized values in ascending order and return:

values[(providerCount - 1) / 2]

This selects the lower median for an even provider count.

The returned basis MUST equal the configured stream basis. The returned valuation timestamp MUST equal the latest aggregation timestamp. The returned provider count MUST equal the number of eligible submissions.

For aggregate publication staleness, publishedAt MUST be treated as the greatest publication timestamp among eligible submissions. Aggregate valuation staleness uses the shared valuation timestamp.

aggregatedNAV MUST revert until both staleness thresholds are configured.

Deviation Detection

After a successful publication at a valuation timestamp that meets quorum, the non-view publication path MUST calculate:

spread = maxNav - minNav
deviationBps = spread * 10_000 / abs(medianNav)

The calculation MUST account safely for signed values. If the spread is zero, deviation is zero. If the median is zero while spread is nonzero, or if the calculation would overflow, deviation MUST saturate at type(uint256).max.

When deviationBps > deviationThresholdBps, the oracle MUST emit NAVDeviationDetected from the publication transaction. Equality does not trigger the event.

Deviation events are alerts. They do not invalidate submissions or prevent aggregation.

Interface Detection

Compliant core oracles MUST implement ERC-165 and return true for type(INAVSnapshotOracle).interfaceId.

Implementations supporting aggregation MUST also return true for type(INAVAggregation).interfaceId.

ERC-165 indicates interface support only. It does not establish provider credentials, NAV accuracy, methodology validity, liquidity, redemption rights, or use of the oracle by a consuming contract.

Rationale

Why Key Streams by Subject and Currency?

A subject can be valued in multiple denominations. Treating each pair as an independent stream removes ambiguity and permits separate history, staleness, and aggregation configuration.

Why Configure NAV Basis at Stream Level?

Per-unit, per-share, and total NAV differ materially. If providers can choose basis independently, one mismatched submission can make a quorum set incomparable or unavailable. Immutable stream-level basis configuration rejects the mismatch before it enters the stream.

Why Separate Valuation and Publication Timestamps?

A value can be published recently while describing an old valuation. Consumers need both times to assess operational feed health and economic recency.

Why Signed NAV?

Liabilities can exceed assets. A signed representation avoids silently excluding insolvent or leveraged subjects, while consumers remain responsible for handling nonpositive values safely.

Why Corrections?

Valuations can be restated after administrator error, late information, audit adjustments, or model changes. Correction links preserve the earlier assertion and identify its successor.

Why Administrative Invalidation?

Correction requires the original provider. If that provider is compromised, revoked, or unavailable, a poisoned terminal snapshot could otherwise remain current and continue to satisfy quorum. Invalidation excludes it without deleting history and allows a valid replacement.

Why Latest by Valuation Time?

A late correction for an older valuation should not displace a more recent valuation as the stream’s raw latest value. Period recency and publication recency answer different questions.

Why Lower-Median Aggregation?

Median aggregation resists a minority of extreme submissions. Selecting the lower median for even sets makes the result deterministic without introducing rounding between two signed values.

Why Dual Staleness?

Publication heartbeat detects a feed that stopped updating. Maximum valuation age detects publication of economically old data. Either condition can matter independently.

Prior Art

ERC-4626 defines tokenized vault accounting and conversion functions. This ERC can provide an external valuation input but does not define vault accounting, deposits, withdrawals, or redemption guarantees.

ERC-7540 extends ERC-4626 for asynchronous requests, and ERC-7575 supports multi-asset vaults. Both may consume NAV but do not define this provider-attributed snapshot lifecycle.

Backwards Compatibility

This ERC introduces new interfaces and does not modify existing token, vault, oracle, or accounting standards.

Existing systems can deploy a companion oracle and map their asset or fund identifier to subjectId. Integration is optional.

Vault integrations should not call latestNAVStatus or aggregatedNAV from critical conversion paths unless configuration is guaranteed. These functions revert when staleness configuration is absent. Adapters can validate and cache an accepted NAV for non-reverting preview or conversion surfaces.

Test Cases

Implementations should test at least:

stream isolation by subject and currency;
one-time known-basis configuration and publication-before-configuration rejection;
rejection of provider basis mismatch;
signed NAV, decimal, magnitude, and future-valuation bounds;
methodology hash requirements and documented empty-URI behavior;
provider/timestamp original uniqueness;
correction provider, timestamp, basis, terminal, and latest-slot guards;
correction-of-correction chains and current-state helpers;
latest selection by valuation timestamp rather than publication order;
provider history including corrected and invalidated records;
publication and valuation staleness before, at, and after each boundary;
staleness-aware query rejection while unconfigured;
original and correction invalidation;
predecessor restoration and replacement publication after invalidation;
latest-provider, latest-stream, and quorum recomputation after invalidation;
aggregation configuration and historical quorum discovery;
provider caps and quorum limits;
decimal normalization and lower-median selection;
latest eligible valuation-timestamp selection;
provider submission pagination and ordering;
corrected and invalidated submission exclusion;
deviation threshold, zero-median, and overflow saturation behavior;
fiat and token currency derivation; and
positive and negative ERC-165 detection.

Reference Implementation

A Solidity reference implementation, constants library, unit tests, Medusa property tests, deployment configuration, and independent audit are linked from the official discussion thread.

The reference implementation:

uses provider, configurer, and administrator roles;
supports all core and aggregation functions in one contract;
caps providers per valuation timestamp at 64;
uses deterministic lower-median aggregation;
emits deviation alerts from publishNAV; and
recomputes affected indexes after administrative invalidation.

Role assignments and the provider cap are reference deployment choices. The stream basis, correction, invalidation, staleness, and deterministic aggregation semantics are requirements of this ERC.

Security Considerations

NAV Is Not an Executable Price

NAV is an accounting or valuation assertion. A token can trade above or below NAV, and redemption can be gated, delayed, limited, or unavailable. Consumers must not treat NAV as a liquid market price without separately validating liquidity and redemption assumptions.

Provider and Configurer Trust

A provider can publish fabricated or mistaken values and methodologies. A configurer can choose unsafe staleness or quorum settings. Implementations must document authorization, governance, upgrade, and key-management policies.

Revoking a provider role does not invalidate its existing snapshots. An authorized invalidator must separately invalidate any snapshot that should no longer participate in current queries.

Methodology Verification

A methodology hash is useful only when consumers can obtain the committed document representation and reproduce the hash. An empty or unavailable URI can make independent verification impossible unless an out-of-band retrieval process is documented.

Staleness Enforcement

Staleness flags protect only consumers that check them. latestNAV deliberately returns raw data without a staleness decision. Pricing and settlement paths should use validated status or a controlled adapter.

Negative and Zero NAV

Consuming contracts that assume positive NAV can underflow, divide by zero, or misprice assets. They must define explicit behavior for zero and negative values.

Provider Collusion and Correlated Error

Median and quorum reduce single-provider influence but do not prevent collusion, shared data-source failures, or common methodology errors. Address count does not prove provider independence.

Invalidation Authority and Cost

Invalidation can remove legitimate data and change latest or aggregate values. The authority should be strongly controlled and every reason commitment should be independently reviewable.

Recomputing latest and quorum pointers can require work proportional to stream history. Production implementations with long histories should use bounded or checkpointed indexing while preserving the specified results.

Correction and Invalidation Interpretation

Invalidation can detach a historical correction and permit a replacement branch. Consumers must combine correction pointers with invalidation state and events; following correctsIndex alone does not identify the current branch.

Front-Running Valuation Updates

Material NAV changes visible before inclusion can enable transactions against an older accepted value. Deployments should consider private submission, commit-reveal publication, settlement pauses, or delayed activation when the economic risk justifies the complexity.

Timestamp Dependence

Valuation timestamps are provider assertions, and staleness uses block.timestamp. Block producers can influence timestamps within protocol bounds. Consumers must account for this uncertainty.

Decimal Normalization

Aggregation multiplies lower-precision signed values. Implementations must enforce the numeric bounds in this ERC before normalization and use checked arithmetic.

Privacy and Commercial Sensitivity

Methodology URIs, valuation timing, and provider behavior can reveal sensitive fund or asset information. Deployments should avoid publishing confidential documents or predictable private references on public chains.