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

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

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

Confidential Transactions Supported Token

Fri, 09 May 2025 00:00:00 +0000

EIP #7945 - Confidential Transactions Supported Token is in Last Call status. It is authored by Siyuan Zheng (@andrewcoder666) , Zhe Han (@iampkuhz) , Xiaoyu Liu (@elizabethxiaoyu) , Wenwei Ma (@madyinglight) , Jun Meng Tan (@chadxeth) , Yuxiang Fu (@tmac4096) , Kecheng Gao (@thanks-v-me-50) , Alwin Ng Jun Wei (@alwinngjw) , Chenxin Wang (@3235773541) , Xiang Gao (@GaoYiRu) , yuanshanhshan (@xunayuan) , Hao Zou (@BruceZH0915) , Yanyi Liang , Yuehua Zhang (@astroyhzcc) and was originally created 2025-05-09. 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/interface-of-confidential-transactions-supported-token-contract/23586

Abstract

Classic token contracts like ERC-20 enable their token holders to make transfers and/or approve others to make transfers on their behalves. The generality of token standard ERC-20 catalyzed decentralized finance and many other blockchain applications. However, when it comes to privacy, although some technical schemes have been proposed, few standards have been established, which limits the evolution of privacy-preserving blockchain applications.

This proposal draws up a standard interface for fungible token contracts supporting confidential transactions. It provides basic transfer functionality without loss of generality, and allowance and approve functionalities. Contracts following the standard can provide confidentiality for users’ balances and token transfer value, and can enable other blockchain applications to make transfers on behalf of owners, which empowers more privacy-preserving capabilities for blockchain applications.

Motivation

Confidential transactions have been implemented in many blockchains, either natively through blockchain protocols like Monero and Zcash, or through smart contracts like Zether¹ without modifying the blockchain protocol.

However, few standards are proposed on Ethereum (and/or other EVM-compatible blockchains) to illustrate privacy-preserving contracts without modifying the underlying protocol. Users and applications cannot easily detect whether a token contract supports confidential transactions or not, and so cannot reliably make transfers without revealing the actual amount.

Consequently, this proposal is to standardize confidential-transaction-supported token contracts, without loss of generality, by only specifying core methods and events.

Such a standard interface allows confidential transactions of tokens to be applied by certain parties that are sensitive to transfer amounts, or by privacy-preserving applications.

Compared with application-specific confidential token designs, such as Confidential Fungible Token using bytes32 pointers representing confidential balances, open-source projects Tornado Cash and Zeto implementing a UTXO model in smart contracts, this proposal standardizes only the minimum interoperable surface in the setting of an account-based model: balance queries, transfers, delegated transfers, approvals, and related events. This allows different proof systems, ciphertext encodings, and compliance workflows to coexist behind a common interface, so wallets, bridges, exchanges, and other applications can support confidential tokens without being tightly coupled to one implementation.

Specification

Contract Interface

Compliant contracts MUST implement the following interface:

interface IERC7945 {
    function confidentialBalanceOf(address owner) external view returns (bytes memory confidentialBalance);

    function confidentialTransfer(
        address _to,
        bytes memory _confidentialTransferValue,
        bytes memory _proof
    ) external;

    function confidentialTransferFrom(
        address _from,
        address _to,
        bytes memory _confidentialTransferValue,
        bytes memory _proof
    ) external;

    function confidentialApprove(
        address _spender,
        bytes memory _confidentialValue,
        bytes memory _proof
    ) external;

    function confidentialAllowance(
        address _owner,
        address _spender
    ) external view returns (bytes memory _confidentialValue);

    event ConfidentialTransfer(
        address indexed _spender,
        address indexed _from,
        address indexed _to,
        bytes _confidentialTransferValue
    );

    event ConfidentialApproval(
        address indexed _owner,
        address indexed _spender,
        bytes _currentAllowancePart,
        bytes _allowancePart
    );
}

Additionally, compliant contracts MAY implement the following interface:

interface IERC7945Metadata {
    function name() external view returns (string memory);
    function symbol() external view returns (string memory);
    function decimals() external view returns (uint8);
}

`IERC7945Metadata`

Methods

`name`

function name() external view returns (string memory)

Returns the name of the token - e.g. "MyConfidentialToken".

OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect this value to be present.

`symbol`

function symbol() external view returns (string memory)

Returns the symbol of the token, e.g. "cHIX".

OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect this value to be present.

`decimals`

function decimals() external view returns (uint8)

Returns the number of decimals the token uses - e.g. 8, meaning the token amount should be divided by 100000000 to get its user representation.

OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect this value to be present.

`IERC7945`

Methods

`confidentialBalanceOf`

function confidentialBalanceOf(address owner) 
external view returns (bytes memory confidentialBalance)

Returns the confidential balance of the account with address owner.

`confidentialTransfer`

function confidentialTransfer(
  address _to,
  bytes memory _confidentialTransferValue, 
  bytes memory _proof
) external

Transfers value amount of tokens (behind _confidentialTransferValue) to address _to, and MUST fire the ConfidentialTransfer event. The function SHOULD revert if the message caller’s _proof of this transfer fails to be verified.

Note:

Implementations can fully customize the proof system, (de)serialization strategies of bytes, and/or the business workflow. For example, when implementing “Zether”¹ confidential token contracts, the _confidentialTransferValue and accounts’ confidential balances will be encrypted homomorphically under ElGamal public keys, and _proof will consist of 3 parts to check:
- _confidentialTransferValue is well encrypted under both the caller’s public key and _to’s;
- The plaintext value behind _confidentialTransferValue is non-negative;
- The caller’s confidential balance is actually enough to pay the plaintext value behind _confidentialTransferValue.

`confidentialTransferFrom`

function confidentialTransferFrom(
  address _from,
  address _to,
  bytes memory _confidentialTransferValue,
  bytes memory _proof
) external

Transfers value amount of tokens (behind _confidentialTransferValue) from address _from to address _to, and MUST fire the ConfidentialTransfer event.

The confidentialTransferFrom method is used for a withdrawal workflow, allowing contracts to transfer tokens on your behalf. This can be used, for example, to allow a contract to transfer tokens on your behalf and/or to charge fees in sub-currencies. The function SHOULD revert unless the _from account has deliberately authorized the sender of the message via some mechanism, and SHOULD revert if the message caller’s _proof of this transfer fails to be verified.

Note:

Implementations can fully customize the proof system, (de)serialization strategies of bytes, and/or the business workflow. For example, when implementing “Zether” confidential token contracts, the _confidentialTransferValue and accounts’ confidential balances will be encrypted homomorphically under ElGamal public keys, and _proof will consist of 3 parts to check:
- _confidentialTransferValue is well encrypted under public keys of _from’s, _to’s, and caller’s;
- The plaintext value behind _confidentialTransferValue is non-negative;
- The caller’s confidential allowance is actually enough to pay the plaintext value behind _confidentialTransferValue.

`confidentialApprove`

function confidentialApprove(
  address _spender,
  bytes memory _confidentialValue, 
  bytes memory _proof
) external

Allows _spender to withdraw from caller’s split part of balances multiple times, up to the amount (allowance value) behind _confidentialValue to 0. This function SHOULD revert if the message caller’s _proof of this transfer fails to be verified.

Caution:

This function behaves much differently from approve(address,uint256) in ERC-20.

Calling confidentialApprove splits the confidential balance of caller’s account into allowance part and the left part.

The values behind two parts above after calling confidentialApprove, and the value behind the original confidential balance of caller’s account before calling confidentialApprove, satisfy the equation:

\[value_{Behind\ Allowance\ Part} + value_{Behind\ Left\ Part} = value_{Behind\ Original\ Confidential\ Balance}\]

The allowance part of the confidential balance allows _spender to withdraw multiple times through calling confidentialTransferFrom until _spender does not call it any more or the value behind this part is 0.
- Every time _spender calls confidentialTransferFrom, the value behind this part will be decreased by the value behind _confidentialTransferValue.
The left part remains as the new confidential balance of the caller’s account.

If this function is called again, it:

merges the existing allowance part into the confidential balance of the caller’s account; and then
overwrites the current allowance part with _confidentialValue.

Note:

Implementations can fully customize the proof system, (de)serialization strategies of bytes, and/or the business workflow. For example, when implementing “Zether” confidential token contracts, the _confidentialValue and accounts’ confidential balances will be encrypted homomorphically under ElGamal public keys, and _proof will consist of 3 parts to check:
- _confidentialValue is well encrypted under public keys of caller’s and _spender’s;
- The plaintext value behind _confidentialValue is non-negative;
- The caller’s confidential balance is actually enough to pay the plaintext value behind _confidentialValue.

`confidentialAllowance`

function confidentialAllowance(address _owner, address _spender)
external view returns (bytes memory _confidentialValue)

Returns the allowance part that _spender is still allowed to withdraw from _owner.

Events

`ConfidentialTransfer`

event ConfidentialTransfer(
  address indexed _spender,
  address indexed _from, 
  address indexed _to, 
  bytes _confidentialTransferValue
)

MUST trigger when tokens are transferred.

Specifically, if tokens are transferred through function confidentialTransferFrom, _spender address MUST be set to caller’s; otherwise, it SHOULD be set to 0x0.

A confidential token contract:

which creates new tokens SHOULD trigger a ConfidentialTransfer with the _from address set to 0x0 when tokens are minted;
which destroys existing tokens SHOULD trigger a ConfidentialTransfer with the _to address set to 0x0 when tokens are burned.

`ConfidentialApproval`

event ConfidentialApproval(
  address indexed _owner,
  address indexed _spender,
  bytes _currentAllowancePart,
  bytes _allowancePart
)

MUST trigger on any successful call to confidentialApprove(address,bytes,bytes).

Rationale

Optional Accessor of “Confidential Total Supply”

function confidentialTotalSupply() external view returns (bytes memory)

Confidentiality of transfer amount makes it hard to support a field like totalSupply() in ERC-20. When it comes to token minting or burning, if every user in this contract can access totalSupply() as well as decrypt it, these users will know the actual token value minted or burned by comparing the totalSupply() before and after such operations, which means that confidentiality no longer exists.

Contract implementations can optionally support confidentialTotalSupply() by evaluating whether anti-money laundering (see next part) and audit are required. That would be much more plausible by allowing a small group of parties to know the plaintext total supply behind confidentialTotalSupply().

Anti-money Laundering and Audit

To support audit of confidential transactions and total supply, especially when such token issuers are banks or other financial institutions supervised by governments or monetary authorities, confidential transactions can be implemented without changing the confidentialTransfer method signature, by encoding more information into parameters.

For example, in a Zether-like implementation², if token transfers are required to be audited, the confidentialTransfer caller encrypts transfer value redundantly under public keys of caller’s, to’s, and a group of auditors’, which makes it possible for related parties to know the real value behind it exactly. So does confidentialTotalSupply().

Fat Token

A confidential-transactions-supported token can also implement ERC-20 at the same time.

Token accounts in such tokens can hold two kinds of balances. Such token contracts can optionally provide methods to hide ERC-20 plaintext balances into confidential balances, and vice versa, to reveal confidential balances back to ERC-20 plaintext balances.

ERC-20 interfaces will bring much more usability and utility to confidential-transaction-supported tokens, realizing general confidentiality in the meantime.

Backwards Compatibility

No backward compatibility issues found.

Security Considerations

To preserve confidentiality, implementations should avoid creating (minting) or destroying (burning) tokens with plaintext value parameters, since plaintext mint or burn flows may reveal sensitive amounts even if ordinary transfers remain confidential. Implementers should also ensure that any mint, burn, transfer, approval, and delegated transfer workflows use proof and encryption schemes that do not leak transfer values or balance information through calldata, events, or auxiliary state.

Copyright

{
  "type": "article",
  "id": 1,
  "author": [
    {
      "family": "Bünz",
      "given": "Benedikt"
    },
    {
      "family": "Agrawal",
      "given": "Shashank" 
    },
    {
      "family": "Zamani",
      "given": "Mahdi" 
    },
    {
      "family": "Boneh",
      "given": "Dan"
    }
  ],
  "DOI": "10.1007/978-3-030-51280-4_23",
  "title": "Zether: Towards Privacy in a Smart Contract World",
  "original-date": {
    "date-parts": [
      [2020, 2, 10]
    ]
  },
  "URL": "https://eprint.iacr.org/2019/191.pdf",
  "custom": {
    "additional-urls": [
      "https://dl.acm.org/doi/abs/10.1007/978-3-030-51280-4_23"
    ]
  }
}

↩ ↩²

{
  "type": "article",
  "id": 2,
  "author": [
    {
      "family": "Chen",
      "given": "Yu"
    },
    {
      "family": "Ma",
      "given": "Xuecheng"
    },
    {
      "family": "Tang",
      "given": "Cong"
    },
    {
      "family": "Au",
      "given": "Man Ho"
    }
  ],
  "DOI": "10.1007/978-3-030-58951-6_29",
  "title": "PGC: Decentralized Confidential Payment System with Auditability",
  "original-date": {
    "date-parts": [
      [2020, 9, 12]
    ]
  },
  "URL": "https://eprint.iacr.org/2019/319.pdf",
  "custom": {
    "additional-urls": [
      "https://link.springer.com/chapter/10.1007/978-3-030-58951-6_29"
    ]
  }
}

↩

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

Modular Dispatch Proxies

Mon, 16 Feb 2026 00:00:00 +0000

EIP #8167 - Modular Dispatch Proxies is in Last Call status. It is authored by William Morriss (@wjmelements), Radek Svarz (@radeksvarz) and was originally created 2026-02-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-8167-modular-dispatch-proxies/27781

Abstract

This proposal standardizes dispatch proxies, which dispatch calls to logic modules, called delegates, according to function selector. A modular proxy architecture facilitates upgrades, extensions, and hardening, while working around codesize limits. This minimal standard interface allows tooling to discover the ABI of these proxies and examine their upgrade history.

Motivation

Proxy contracts utilizing delegatecall are widely used for both code sharing and upgradeability. Most common proxies forward calldata to a single implementation contract. Sometimes the implementation address is hardcoded, a pattern used by cloning factories to reduce deployment costs, and sometimes the implementation address is mutable, a pattern used by upgradeable proxies. However, monolithic proxy architectures can bump into codesize limits. Additionally, replacing the implementation of an entire contract at once can be riskier than smaller, more incremental changes.

Shared Logic Modules

Many contracts share common code for things like tokens but cannot share their entire implementation because of their own unique characteristics. For example, two tokens might share their balance logic and transfer interface but differ in their name metadata and monetary policy. With a monolithic architecture, these differences require two separate contracts. With a logic module architecture, they can share a standardized token implementation but customize their metadata and monetary policy.

Extension

Sometimes new standards arise that provide new functionality or guarantees. For example, a popular token interface extension might arise to provide a new and better method for modifying allowances. With a monolithic architecture, token implementations must be wrapped or wholly replaced to support the new method. With logic modules, the interface could be extended with a new module to support the new method.

Modular designs are also appropriate for personal smart accounts such as EIP-7702 EOAs. User accounts could install features such as DEX-specific callbacks without temporarily disabling other functionality.

Upgrade

Monolithic proxy architectures require replacing the entire implementation during an upgrade. Such upgrades batch changesets but introduce risk and are difficult to test and verify. Modular dispatch proxies can still atomically batch upgrades, but their modular architecture allows incremental improvements and fixes without unintentionally breaking unrelated components.

Hardening

Upgradeable dispatch proxies can be permanently hardened into immutable systems by uninstalling the upgrade methods.

Standardization

A standard interface for the modular proxy architecture can help tools, user interfaces, and indexers determine the ABI of these proxies. Such systems may also want to surface the full upgrade history of these proxies to facilitate investigation.

Specification

A modular dispatch proxy MUST use delegatecall to relay the entire calldata to the delegate corresponding to the first four bytes of the calldata.

interface IERC8167 {
    // RECOMMENDED
    // Emitted when assigning a delegate logic module to a selector
    // An address(0) delegate signals removal
    event SelectorDelegated(bytes4 indexed selector, address indexed delegate);

    // REQUIRED
    // Returns the delegate for the selector, using address(0) for function not found
    function implementation(bytes4 selector) external view returns (address);

    // REQUIRED
    // Surfaces the ABI
    // SHOULD return all function selectors with implementations
    function selectors() external view returns (bytes4[] memory);

    // RECOMMENDED
    // If the delegate for that selector is not set, the proxy SHOULD revert, and with FunctionNotFound.
    error FunctionNotFound(bytes4 selector);
}

IERC8167 functions SHOULD be implemented by delegates rather than in the proxy.

A modular dispatch proxy constructor SHOULD configure at least one delegate.

Rationale

`bytes4 selector`

The most widely-supported ABI is Solidity’s 4-byte ABI, which uses the first four bytes of calldata, called the selector, to dispatch functions. The dispatch proxy also uses those same four bytes to dispatch function calls to their delegate.

`implementation(bytes4)`

While implementations can be discovered with eth_getStorageAt, a common interface can support a variety of possible storage layouts and implementations.

This function’s naming is consistent with monolithic proxies, but with a selector parameter.

`selectors()`

This is a minimal function to surface ABI to tools. While selectors are ambiguous, they can be resolved if their delegate has a verified ABI. Together, these steps produce the ABI of the proxy:

For each selector in selectors(), query implementation(selector).
For each unique implementation, check if its code is verified. If verified, retrieve the ABI. If not, allow the user to supply the missing ABI.
Identify the functions supported by the proxy by matching its selectors with their implementation’s ABI.

Although selectors are also retrievable by querying SelectorDelegated events, the selectors function provides a way to get this information without access to the logs. Log queries can be slow without a database index.

While a packed encoding would reduce memory allocation, an array of bytes4 is the simplest for tooling to decode. It is anticipated that this method will primarily be used by tooling.

Upgrades

This standard does not specify an upgrade function. Other standards could extend this one with versioning frameworks for atomic batch upgrades.

Storage Layout

This standard does not specify a storage layout. Other standards could suggest patterns to protect against storage collisions and other mistakes.

Backwards Compatibility

This standard improves upon ERC-2535 in the following ways:

Removal of diamond jargon.
Fewer and simpler introspection functions.
Simpler upgrade event.

Existing upgradeable monolithic proxies can upgrade to this standard using the following upgrade plan:

Upgrade to an implementation with a method to populate the selector delegate mapping.
Populate the selector delegate mapping for all methods in the ABI plus the introspection functions.
Set the implementation to a dispatch proxy using the populated selector delegate mapping.

Existing modular proxies can upgrade to this standard by adding the introspection functions and optionally emitting a SelectorDelegated event for every installed function.

Reference Implementation

The reference implementation contains three files.

The interface
A namespace-based storage layout
A proxy implementation with delegates for inspection and administration

Security Considerations

Access control

Upgrade functions should have some form of access control. Access control designs are outside the scope of this standard.

Avoid self-destruct

Delegates should not self-destruct. If a delegate can self-destruct, it can break proxies that use it.

Storage Layout

Proxy upgrades must take care not to shift storage indices because this corrupts contract data.

Delegates should be designed to minimize the risk of storage layout overlap between them. There are two known approaches to protect storage layouts against such collisions.

The first is to define a single shared proxy storage layout in a common superclass inherited by all of the proxy’s delegates. Such subclasses should not declare additional storage.

The second is to use storage namespaces, such as ERC-7201 and ERC-8042. This approach is appropriate for shared libraries.

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.

Ethereum EIPs - Last Call Review

Add chain id to mixed-case checksum address encoding

Simple Summary

Abstract

Motivation

Specification

Rationale

Implementation

Test Cases

Usage

Usage Table

Implementation Table

Copyright

Atomic Swap-based American Call Option Contract Standard

Simple Summary

Abstract

Motivation

Specification

Definitions

Storage Variables

swap

initiatorAsset

participantAsset

premiumAsset

Methods

setup

initiate

fillPremium

participate

redeemAsset

refundAsset

redeemPremium

refundPremium

Events

SetUp

Initiated

Participated

PremiumFilled

InitiatorAssetRedeemed/ParticipantAssetRedeemed

InitiatorAssetRefunded/ParticipantAssetRefunded

PremiumRedeemed

PremiumRefunded

Rationale

Security Considerations

Backwards Compatibility

Implementation

Copyright

References

ERC-721 Nonce Extension

Abstract

Motivation

Specification

Rationale

Backwards Compatibility

Test Cases

Reference Implementation

Security Considerations

Copyright

Soulbound Badge

Abstract

Specification

Rationale

Immutability

Content Addressable URIs Required

No Specification for badgeUri Data Format

Backwards Compatibility

Security Considerations

Copyright

Cross-Chain Execution

Abstract

Motivation

Specification

MessageDispatcher

MessageDispatcher Methods

MessageDispatcher Events

MessageExecutor

Execution

MessageExecutor Events

MessageExecutor Errors

Rationale

No Specification for `badgeUri` Data Format

Reference Implementation of `EndorsableERC721`

Reference Implementation of `ThresholdMultiSigForwarder`