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

Slashing Protection Interchange Format

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

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

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

Abstract

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

Motivation

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

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

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

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

Specification

JSON Schema

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

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

Example JSON Instance

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

Conditions

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

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

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

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

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

Additional Information

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

Rationale

Supporting Different Strategies

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

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

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

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

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

Integer Representation

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

Versioning

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

Backwards Compatibility

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

Security Considerations

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

Advice for Complete Databases

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

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

Advice for Minimal Databases

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

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

General Recommendations

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

Copyright

EVM trace specification

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

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

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

Abstract

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

Motivation

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

This EIP has multiple goals:

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

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

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

Specification

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

Datatypes

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

Output

The CUT MUST output a json object for EACH operation.

Required Fields

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

Optional Fields

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

Example:

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

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

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

Example:

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

Summary and Error Handling

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

Required Fields

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

Optional Fields

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

Example:

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

Rationale

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

Backwards Compatibility

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

Clients

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

Test Cases

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

Security Considerations

Tracing is expensive.

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

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

Copyright

ERC-721 Nonce Extension

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

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

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

Abstract

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

Motivation

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

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

Specification

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

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

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

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

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

Rationale

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

Backwards Compatibility

This standard is compatible with ERC-721.

Test Cases

Test cases are included in test.js.

Run:

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

Reference Implementation

See ERC5008.sol.

Security Considerations

No security issues found.

Copyright

Soulbound Badge

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

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

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

Abstract

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

Specification

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

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

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

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

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

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

Rationale

Immutability

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

Content Addressable URIs Required

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

No Specification for `badgeUri` Data Format

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

Backwards Compatibility

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

Security Considerations

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

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

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

Copyright

Cross-Chain Execution

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

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

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

Abstract

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

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

Motivation

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

Specification

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

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

MessageDispatcher
MessageExecutor

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

MessageDispatcher

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

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

MessageDispatcher Methods

dispatchMessage

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

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

MessageDispatchers MUST revert if toChainId is not supported.

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

MessageDispatchers MUST use a unique messageId for each message.

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

MessageDispatchers MAY require payment.

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

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

MessageDispatcher Events

MessageDispatched

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

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

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

MessageExecutor

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

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

Execution

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

MessageExecutors MUST NOT successfully execute a message more than once.

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

Calldata

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

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

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

MessageExecutor Events

MessageIdExecuted

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

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

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

MessageExecutor Errors

MessageAlreadyExecuted

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

interface MessageExecutor {
  error MessageIdAlreadyExecuted(
    bytes32 messageId
  );
}

MessageFailure

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

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

Rationale

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

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

Backwards Compatibility

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

Security Considerations

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

Copyright

ERC-1155 Allowance Extension

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

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

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

Abstract

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

Motivation

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

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

Specification

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

Contracts using this ERC MUST implement the IERC5216 interface.

Interface implementation

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

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

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

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

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

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

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

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

In addition, the safeBatchTransferFrom MUST:

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

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

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

Rationale

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

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

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

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

Backwards Compatibility

This standard is compatible with ERC-1155.

Reference Implementation

The reference implementation can be found here.

Security Considerations

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

Copyright

Endorsement - Permit for Any Functions

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

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

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

Abstract

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

Motivation

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

Specification

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

Interfaces

The interfaces and structures referenced here are as follows

pragma solidity ^0.8.9;

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

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

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

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

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

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

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


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

See IERC5453.sol.

Behavior specification

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

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

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

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

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

The functionParamStructHash MUST be computed as follows

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

whereas

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

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

Rationale

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

Backwards Compatibility

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

Reference Implementation

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

pragma solidity ^0.8.9;

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

import "./IERC5453.sol";

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

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

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

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

See AERC5453.sol

Reference Implementation of `EndorsableERC721`

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

pragma solidity ^0.8.9;

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

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

See EndorsableERC721.sol

Reference Implementation of `ThresholdMultiSigForwarder`

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

pragma solidity ^0.8.9;

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

}

See ThresholdMultiSigForwarder.sol

Security Considerations

Replay Attacks

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

Phishing

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

Copyright

Multi-privilege Management NFT Extension

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

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

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

Abstract

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

Motivation

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

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

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

Specification

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

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

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

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

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

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

The PrivilegeAssigned event MUST be emitted when setPrivilege is called.

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

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

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

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

The PrivilegeCloned event MUST be emitted when clonePrivilege is called.

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

Rationale

Shareable Privileges

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

Expire Date Type

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

Beneficiary of Referrer

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

Proposal: NFT Transfer

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

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

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

    _burn(tokenId);

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

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

Backwards Compatibility

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

Test Cases

Test cases are implemented with the reference implementation.

Test Code

test.js

Run in terminal:

truffle test ./test/test.js

testCloneable.js

Run in terminal:

truffle test ./test/testCloneable.js

Reference Implementation

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

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

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

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

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

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

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

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

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

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

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

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

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

Security Considerations

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

Copyright

Contracts Dependencies Registry

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

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

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

Abstract

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

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

Motivation

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

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

The advantages of using the provided system might be:

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

Specification

Overview

The system consists of two smart contracts:

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

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

ContractsRegistry

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

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

The ContractsRegistry MUST implement the following interface:

pragma solidity ^0.8.0;

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

Dependant

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

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

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

The Dependant contract MUST implement the following interface:

pragma solidity ^0.8.0;

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

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

Rationale

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

ContractsRegistry Rationale

Contracts Identifier

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

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

Reverts

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

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

Dependant Rationale

Dependencies

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

Injector

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

Reference Implementation

Note that the reference implementation depends on OpenZeppelin contracts 4.9.2.

ContractsRegistry Implementation

pragma solidity ^0.8.0;

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

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

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

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

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

    function injectDependencies(string memory name) external;

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

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

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

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

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

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

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

    function removeContract(string memory name) external;
}

contract ProxyUpgrader {
    using Address for address;

    address private immutable _OWNER;

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

    constructor() {
        _OWNER = msg.sender;
    }

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

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

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

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

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

contract ContractsRegistry is IContractsRegistry, OwnableUpgradeable {
    ProxyUpgrader private _proxyUpgrader;

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

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

        __Ownable_init();
    }

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

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

        return contractAddress_;
    }

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

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

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

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

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

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

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

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

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

        _proxyUpgrader.upgrade(contractToUpgrade_, newImplementation_, data_);

        emit ProxyContractUpgraded(name_, newImplementation_);
    }

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

        _contracts[name_] = contractAddress_;

        emit ContractAdded(name_, contractAddress_);
    }

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

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

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

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

        emit ProxyContractAdded(name_, proxyAddr_, contractAddress_);
    }

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

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

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

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

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

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

        emit ContractRemoved(name_);
    }

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

Dependant Implementation

pragma solidity ^0.8.0;

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

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

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

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

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

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

        assembly {
            injector_ := sload(slot_)
        }
    }

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

        assembly {
            sstore(slot_, injector_)
        }
    }

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

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

Security Considerations

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

ContractsRegistry Security

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

Dependant Security

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

Copyright

Single-contract Multi-delegatecall

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

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

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

Abstract

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

Motivation

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

Specification

Contracts implementing this EIP must implement the following interface:

pragma solidity ^0.8.0;

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

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

Rationale

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

Backwards Compatibility

This is compatible with most existing multicall functions.

Test Cases

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

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

Reference Implementation

pragma solidity ^0.8.0;

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

Security Considerations

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

Copyright

Empty accounts deprecation

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

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

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

Abstract

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

Motivation

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

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

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

Specification

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

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

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

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

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

Rationale

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

Alternative approaches include:

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

These approaches were rejected as being unnecessarily complicated.

Backwards Compatibility

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

Security Considerations

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

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

Copyright

Revert creation in case of non-empty storage

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

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

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

Abstract

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

Specification

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

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

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

Rationale

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

Backwards Compatibility

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

Test Cases

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

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

Security Considerations

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

Copyright

Network Upgrade Inclusion Stages

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

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

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

Abstract

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

Motivation

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

Specification

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

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

Upgrade Meta EIPs

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

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

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

Upgrade Devnets

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

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

Proposed for Inclusion

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

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

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

Considered for Inclusion

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

Considered for Inclusion signals that client developers are positive towards the EIP. A Core EIP that is Considered for Inclusion SHOULD be implemented in future Upgrade Devnets. Assuming it meets all the requirements for mainnet deployment it MAY be included in the network upgrade. This stage is similar to “concept ACK” in other open source projects, and is not sufficient to result in deployment to mainnet.

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

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

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

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

Declined for Inclusion

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

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

Scheduled for Inclusion

When client teams agree to implement a Core EIP in the next Upgrade Devnet, the EIP SHOULD move to the Scheduled for Inclusion stage, and the Upgrade Meta EIP SHOULD be updated to reflect this. Non-Core EIPs SHOULD move to Scheduled for Inclusion when client teams agree to immediately prioritize their implementation.

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

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

Scheduled for Inclusion signals that implementation and testing work are underway. The EIP SHOULD be included in the network upgrade if no issues arise. The latest Upgrade Devnet must contain all Scheduled for Inclusion Core EIPs.

An EIP MAY be moved from Scheduled for Inclusion to Declined for Inclusion if client teams are against including the EIP in the network upgrade. An EIP MAY also be moved from Scheduled for Inclusion to Considered for Inclusion if client teams are in favor of including the EIP in the network upgrade but cannot commit to including it in the next Upgrade Devnet.

Included

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

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

Rationale

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

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

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

Backwards Compatibility

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

Security Considerations

None.

Copyright

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

uRWA - Universal Real World Asset Interface

Tue, 10 Jun 2025 00:00:00 +0000

EIP #7943 - uRWA - Universal Real World Asset Interface is in Last Call status. It is authored by Dario Lo Buglio (@xaler5), Tino Martinez Molina (@tinom9), Mihai Colceriu (@mihaic195) and was originally created 2025-06-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/erc-universal-rwa-interface/23972

Abstract

This EIP proposes the Universal RWA (uRWA) standard, a set of interfaces for tokenized Real World Assets (RWAs) such as securities, real estate, commodities, or other physical/financial assets on the blockchain.

Real World Assets often require regulatory compliance features not found in standard tokens, including the ability to freeze assets, perform enforcement transfers for legal compliance, and restrict transfers to authorized users. The uRWA standard extends common token standards like ERC-20, ERC-721, or ERC-1155 by introducing essential compliance functions while remaining minimal and not opinionated about specific implementation details.

This enables DeFi protocols and applications to interact with tokenized real-world assets in a standardized way, knowing they can check transfer permissions, whether users are allowed to interact, handle frozen assets appropriately, and integrate with compliant RWA tokens regardless of the underlying asset type or internal compliance logic. It also adopts ERC-165 for introspection.

Motivation

Real World Assets (RWAs) represent a significant opportunity to bridge traditional finance and decentralized finance (DeFi). By tokenizing assets like real estate, corporate bonds, commodities, art, or securities, we can unlock benefits such as fractional ownership, programmable compliance, enhanced liquidity through secondary markets for traditionally illiquid assets, and integration with decentralized protocols.

However, tokenizing real world assets introduces regulatory requirements often absent in purely digital assets, such as allowlists for users, transfer restrictions, asset freezing, or law enforcement rules. Existing token standards like ERC-20, ERC-721, and ERC-1155 lack the inherent structure to address these compliance needs directly within the standard itself.

Attempts at defining universal RWA standards historically imposed unnecessary complexity and gas overhead for simpler use cases that do not require the full spectrum of features like granular role-based access control, mandatory on-chain whitelisting, specific on-chain identity solutions, or metadata handling solutions mandated by the standard.

Additionally, the broad spectrum of RWA classes inherently suggests the need to move away from a one-size-fits-all solution. This means a minimalistic approach, an unopinionated features list, and maximal compatibility have been kept in mind as design goals.

The uRWA standard seeks a more refined balance by defining an essential interface, establishing a common ground for interaction regarding compliance and control, without dictating the underlying implementation mechanisms. This allows core token implementations to remain lean while providing standard functions for RWA-specific interactions.

The final goal is to build composable DeFi around RWAs, providing the same interface when dealing with compliance and regulation.

Specification

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

The following defines the standard interfaces for an ERC-7943 token contract, which MUST extend from one base token interface such as ERC-20, ERC-721, ERC-1155, or ERC-6909. Note that ERC-6909-based implementations can use the multi token interface:

/// @notice Interface for ERC-20 based implementations.
interface IERC7943Fungible is IERC165 {
    /// @notice Emitted when tokens are taken from one address and transferred to another.
    /// @param from The address from which tokens were taken.
    /// @param to The address to which seized tokens were transferred.
    /// @param amount The amount seized.
    event ForcedTransfer(address indexed from, address indexed to, uint256 amount);

    /// @notice Emitted when `setFrozenTokens` is called, changing the frozen `amount` of tokens for `account`.
    /// @param account The address of the account whose tokens are being frozen.
    /// @param amount The amount of tokens frozen after the change.
    event Frozen(address indexed account, uint256 amount);

    /// @notice Error reverted when an account is not allowed to send tokens.
    /// @param account The address of the account which is not allowed to send.
    error ERC7943CannotSend(address account);

    /// @notice Error reverted when an account is not allowed to receive tokens.
    /// @param account The address of the account which is not allowed to receive.
    error ERC7943CannotReceive(address account);

    /// @notice Error reverted when a transfer is not allowed according to internal rules.
    /// @param from The address from which tokens are being sent.
    /// @param to The address to which tokens are being sent.
    /// @param amount The amount sent.
    error ERC7943CannotTransfer(address from, address to, uint256 amount);

    /// @notice Error reverted when a transfer is attempted from `account` with an `amount` less than or equal to its balance, but greater than its unfrozen balance.
    /// @param account The address holding the tokens.
    /// @param amount The amount being transferred.
    /// @param unfrozen The amount of tokens that are unfrozen and available to transfer.
    error ERC7943InsufficientUnfrozenBalance(address account, uint256 amount, uint256 unfrozen);

    /// @notice Takes tokens from one address and transfers them to another.
    /// @dev Requires specific authorization. Used for regulatory compliance or recovery scenarios.
    /// @param from The address from which `amount` is taken.
    /// @param to The address that receives `amount`.
    /// @param amount The amount to force transfer.
    /// @return result True if the transfer executed correctly. Reverts on failure.
    function forcedTransfer(address from, address to, uint256 amount) external returns (bool result);

    /// @notice Changes the frozen status of `amount` tokens belonging to `account`.
    /// @dev Overwrites the current value, similar to an `approve` function.
    /// Requires specific authorization. Frozen tokens cannot be transferred by the account.
    /// @param account The address of the account whose tokens are to be frozen.
    /// @param amount The amount of tokens to freeze. It can be greater than the account balance.
    /// @return result True if the freezing executed correctly. Reverts on failure.
    function setFrozenTokens(address account, uint256 amount) external returns (bool result);

    /// @notice Checks if a specific account is allowed to send tokens according to token rules.
    /// @dev This is often used for allowlist/KYC/KYB/AML checks.
    /// @param account The address to check.
    /// @return allowed True if the account is allowed to send, false otherwise.
    function canSend(address account) external view returns (bool allowed);

    /// @notice Checks if a specific account is allowed to receive tokens according to token rules.
    /// @dev This is often used for allowlist/KYC/KYB/AML checks.
    /// @param account The address to check.
    /// @return allowed True if the account is allowed to receive, false otherwise.
    function canReceive(address account) external view returns (bool allowed);

    /// @notice Checks the frozen status/amount.
    /// @param account The address of the account.
    /// @dev It could return an amount higher than the account's balance.
    /// @return amount The amount of tokens currently frozen for `account`.
    function getFrozenTokens(address account) external view returns (uint256 amount);

    /// @notice Checks if a transfer is currently possible according to token rules. It enforces validations on the frozen tokens.
    /// @dev This can involve checks like allowlists, blocklists, transfer limits, and other policy-defined restrictions.
    /// @param from The address sending tokens.
    /// @param to The address receiving tokens.
    /// @param amount The amount being transferred.
    /// @return allowed True if the transfer is allowed, false otherwise.
    function canTransfer(address from, address to, uint256 amount) external view returns (bool allowed);
}

/// @notice Interface for ERC-721 based implementations.
interface IERC7943NonFungible is IERC165 {
    /// @notice Emitted when `tokenId` is taken from one address and transferred to another.
    /// @param from The address from which `tokenId` is taken.
    /// @param to The address to which seized `tokenId` is transferred.
    /// @param tokenId The ID of the token being transferred.
    event ForcedTransfer(address indexed from, address indexed to, uint256 indexed tokenId);

    /// @notice Emitted when `setFrozenTokens` is called, changing the frozen status of `tokenId` for `account`.
    /// @param account The address of the account whose `tokenId` is subjected to freeze/unfreeze.
    /// @param tokenId The ID of the token subjected to freeze/unfreeze.
    /// @param frozenStatus Whether `tokenId` has been frozen or unfrozen.
    event Frozen(address indexed account, uint256 indexed tokenId, bool indexed frozenStatus);

    /// @notice Error reverted when an account is not allowed to send tokens.
    /// @param account The address of the account which is not allowed to send.
    error ERC7943CannotSend(address account);

    /// @notice Error reverted when an account is not allowed to receive tokens.
    /// @param account The address of the account which is not allowed to receive.
    error ERC7943CannotReceive(address account);

    /// @notice Error reverted when a transfer is not allowed according to internal rules.
    /// @param from The address from which tokens are being sent.
    /// @param to The address to which tokens are being sent.
    /// @param tokenId The ID of the token being sent.
    error ERC7943CannotTransfer(address from, address to, uint256 tokenId);

    /// @notice Error reverted when a transfer is attempted from `account` with a `tokenId` which has been previously frozen.
    /// @param account The address holding the token with `tokenId`.
    /// @param tokenId The ID of the token being frozen and unavailable to be transferred.
    error ERC7943InsufficientUnfrozenBalance(address account, uint256 tokenId);

    /// @notice Takes `tokenId` from one address and transfers it to another.
    /// @dev Requires specific authorization. Used for regulatory compliance or recovery scenarios.
    /// @param from The address from which `tokenId` is taken.
    /// @param to The address that receives `tokenId`.
    /// @param tokenId The ID of the token being transferred.
    /// @return result True if the transfer executed correctly. Reverts on failure.
    function forcedTransfer(address from, address to, uint256 tokenId) external returns (bool result);

    /// @notice Changes the frozen status of `tokenId` belonging to an `account`.
    /// @dev Overwrites the current value, similar to an `approve` function.
    /// Requires specific authorization. Frozen tokens cannot be transferred by the account.
    /// @param account The address of the account whose tokens are to be frozen.
    /// @param tokenId The ID of the token to freeze.
    /// @param frozenStatus Whether `tokenId` is being frozen or not.
    /// @return result True if the freezing executed correctly. Reverts on failure.
    function setFrozenTokens(address account, uint256 tokenId, bool frozenStatus) external returns (bool result);

    /// @notice Checks if a specific account is allowed to send tokens according to token rules.
    /// @dev This is often used for allowlist/KYC/KYB/AML checks.
    /// @param account The address to check.
    /// @return allowed True if the account is allowed to send, false otherwise.
    function canSend(address account) external view returns (bool allowed);

    /// @notice Checks if a specific account is allowed to receive tokens according to token rules.
    /// @dev This is often used for allowlist/KYC/KYB/AML checks.
    /// @param account The address to check.
    /// @return allowed True if the account is allowed to receive, false otherwise.
    function canReceive(address account) external view returns (bool allowed);

    /// @notice Checks the frozen status of a specific `tokenId`.
    /// @dev It could return true even if the account does not hold the token.
    /// @param account The address of the account.
    /// @param tokenId The ID of the token.
    /// @return frozenStatus Whether `tokenId` is currently frozen for `account`.
    function getFrozenTokens(address account, uint256 tokenId) external view returns (bool frozenStatus);

    /// @notice Checks if a transfer is currently possible according to token rules. It enforces validations on the frozen tokens.
    /// @dev This can involve checks like allowlists, blocklists, transfer limits, and other policy-defined restrictions.
    /// @param from The address sending tokens.
    /// @param to The address receiving tokens.
    /// @param tokenId The ID of the token being transferred.
    /// @return allowed True if the transfer is allowed, false otherwise.
    function canTransfer(address from, address to, uint256 tokenId) external view returns (bool allowed);
}

/// @notice Interface for ERC-1155 based implementations.
interface IERC7943MultiToken is IERC165 {
    /// @notice Emitted when tokens are taken from one address and transferred to another.
    /// @param from The address from which tokens were taken.
    /// @param to The address to which seized tokens were transferred.
    /// @param tokenId The ID of the token being transferred.
    /// @param amount The amount seized.
    event ForcedTransfer(address indexed from, address indexed to, uint256 indexed tokenId, uint256 amount);

    /// @notice Emitted when `setFrozenTokens` is called, changing the frozen `amount` of `tokenId` tokens for `account`.
    /// @param account The address of the account whose tokens are being frozen.
    /// @param tokenId The ID of the token being frozen.
    /// @param amount The amount of tokens frozen after the change.
    event Frozen(address indexed account, uint256 indexed tokenId, uint256 amount);

    /// @notice Error reverted when an account is not allowed to send tokens.
    /// @param account The address of the account which is not allowed to send.
    error ERC7943CannotSend(address account);

    /// @notice Error reverted when an account is not allowed to receive tokens.
    /// @param account The address of the account which is not allowed to receive.
    error ERC7943CannotReceive(address account);

    /// @notice Error reverted when a transfer is not allowed according to internal rules.
    /// @param from The address from which tokens are being sent.
    /// @param to The address to which tokens are being sent.
    /// @param tokenId The ID of the token being sent.
    /// @param amount The amount sent.
    error ERC7943CannotTransfer(address from, address to, uint256 tokenId, uint256 amount);

    /// @notice Error reverted when a transfer is attempted from `account` with an `amount` of `tokenId` less than or equal to its balance, but greater than its unfrozen balance.
    /// @param account The address holding the `amount` of `tokenId` tokens.
    /// @param tokenId The ID of the token being transferred.
    /// @param amount The amount of `tokenId` tokens being transferred.
    /// @param unfrozen The amount of tokens that are unfrozen and available to transfer.
    error ERC7943InsufficientUnfrozenBalance(address account, uint256 tokenId, uint256 amount, uint256 unfrozen);

    /// @notice Takes tokens from one address and transfers them to another.
    /// @dev Requires specific authorization. Used for regulatory compliance or recovery scenarios.
    /// @param from The address from which `amount` is taken.
    /// @param to The address that receives `amount`.
    /// @param tokenId The ID of the token being transferred.
    /// @param amount The amount to force transfer.
    /// @return result True if the transfer executed correctly. Reverts on failure.
    function forcedTransfer(address from, address to, uint256 tokenId, uint256 amount) external returns (bool result);

    /// @notice Changes the frozen status of `amount` of `tokenId` tokens belonging to an `account`.
    /// @dev Overwrites the current value, similar to an `approve` function.
    /// Requires specific authorization. Frozen tokens cannot be transferred by the account.
    /// @param account The address of the account whose tokens are to be frozen.
    /// @param tokenId The ID of the token to freeze.
    /// @param amount The amount of tokens to freeze. It can be greater than the account balance.
    /// @return result True if the freezing executed correctly. Reverts on failure.
    function setFrozenTokens(address account, uint256 tokenId, uint256 amount) external returns (bool result);

    /// @notice Checks if a specific account is allowed to send tokens according to token rules.
    /// @dev This is often used for allowlist/KYC/KYB/AML checks.
    /// @param account The address to check.
    /// @return allowed True if the account is allowed to send, false otherwise.
    function canSend(address account) external view returns (bool allowed);

    /// @notice Checks if a specific account is allowed to receive tokens according to token rules.
    /// @dev This is often used for allowlist/KYC/KYB/AML checks.
    /// @param account The address to check.
    /// @return allowed True if the account is allowed to receive, false otherwise.
    function canReceive(address account) external view returns (bool allowed);

    /// @notice Checks the frozen status/amount of a specific `tokenId`.
    /// @dev It could return an amount higher than the account's balance.
    /// @param account The address of the account.
    /// @param tokenId The ID of the token.
    /// @return amount The amount of `tokenId` tokens currently frozen for `account`.
    function getFrozenTokens(address account, uint256 tokenId) external view returns (uint256 amount);

    /// @notice Checks if a transfer is currently possible according to token rules. It enforces validations on the frozen tokens.
    /// @dev This can involve checks like allowlists, blocklists, transfer limits, and other policy-defined restrictions.
    /// @param from The address sending tokens.
    /// @param to The address receiving tokens.
    /// @param tokenId The ID of the token being transferred.
    /// @param amount The amount being transferred.
    /// @return allowed True if the transfer is allowed, false otherwise.
    function canTransfer(address from, address to, uint256 tokenId, uint256 amount) external view returns (bool allowed);
}

`canSend`, `canReceive`, `canTransfer`, and `getFrozenTokens`

These provide views into the implementing contract’s compliance, transfer policy logic, and freezing status.

canSend and canReceive are account-level eligibility checks, independent of any specific transfer parameters (counterparty, amount, or token identifier). These functions:
- MUST NOT revert.
- MUST NOT change the storage of the contract.
- MAY depend on on-chain state such as current timestamp, block number, or msg.sender.
- MUST NOT encode transfer-specific or quantitative rules (e.g., balance checks, amount limits). Those belong in canTransfer.
canTransfer is a transfer-level authorization check that evaluates whether a specific transfer is permissible under permissioned compliance rules. This function:
- MUST NOT revert.
- MUST NOT change the storage of the contract.
- MAY depend on on-chain state such as current timestamp, block number, or msg.sender.
- MUST validate that the amount being transferred doesn’t exceed the unfrozen amount (which is the difference between the current balance and the frozen balance).
- MUST perform a canSend check on the from parameter and a canReceive check on the to parameter. Note that ERC-3643 does not perform this check within canTransfer as this standard requires.
- MUST return false if any permissioned rule would prevent a given transfer from succeeding. A transfer refers to any operation that emits the token’s canonical transfer event. A permissioned check can be a pausing mechanism, a call to canSend/canReceive, or anything else that requires privileged actors.
- MUST NOT return false based on token-specific, non-permissioned validations such as balance or allowance checks. These checks belong to the underlying base token standard (e.g., ERC-20, ERC-721, ERC-1155).
getFrozenTokens will return the absolute frozen amount, which MAY exceed the account’s current balance. In ERC-721 tokens, it MAY return true even if the account does not hold the token.

`forcedTransfer`

This function provides a standard mechanism for forcing a transfer from a from address to a to address. The function:

MUST directly manipulate balances or ownership to transfer the asset from from to to either by transferring or burning from from and minting to to.
MUST be restricted in access.
MUST perform necessary validation checks (e.g., sufficient balance/ownership of a specific token).
MUST emit the base standard’s canonical transfer event(s), consistent with the mechanism used (transfer or burn and mint), and MUST emit the ForcedTransfer event.
In single-party permissioned contexts:
- It MAY bypass the canTransfer checks. If this happens, and the transfer involves tokens that are currently counted as frozen, it MUST unfreeze the assets first and emit a Frozen event before the underlying base token transfer event reflecting the change. Having the unfrozen amount changed before the actual transfer is critical for tokens that might be susceptible to reentrancy attacks doing external checks on recipients, as is the case for ERC-721 and ERC-1155 tokens.
- It SHOULD at least perform a canReceive check on the to parameter to ensure compliance.
In multi-party permissioned contexts:
- It SHOULD perform the canTransfer checks and SHOULD NOT bypass the frozen constraints.
MUST revert in cases where validations and/or canReceive checks return false or fail.

`setFrozenTokens`

It provides a way to freeze or unfreeze assets held by a specific account. This is useful for temporary lock mechanisms. This function:

MUST emit the Frozen event.
MUST be restricted in access.
MUST allow freezing more assets than those held. This allows for future balances withholding.
MUST revert in cases of logical issues or validation checks failure.

Additional Specifications

The contract MUST implement the ERC-165 supportsInterface function and MUST return true for the bytes4 value (representing the interfaceId):

0x3edbb4c4 for the fungible interface.
0xbf1ef5fe for the non-fungible interface.
0x41c4fbad for the multi token interface.

Implementations of these interfaces MUST implement the necessary functions of their chosen base standard (e.g., ERC-20 for the fungible interface, ERC-721 for the non-fungible interface, ERC-1155 or ERC-6909 for the multi token interface) and MUST also restrict access to sensitive functions like forcedTransfer and setFrozenTokens using an appropriate access control mechanism (e.g., onlyOwner, Role-Based Access Control). The specific mechanism is NOT mandated by this interface standard.

Implementations MUST ensure their transfer methods exhibit the following behavior:

Public transfers (transfer, transferFrom, safeTransferFrom, etc.) MUST NOT succeed in cases where canTransfer would return false, or where canSend would return false for the from address, or canReceive would return false for the to address.
Minting in permissionless contexts (e.g., public mint functions) MUST NOT succeed for accounts where canReceive on the recipient would return false. In permissioned contexts (e.g., authorized minting by privileged roles), minting SHOULD respect canReceive checks on the recipient, though implementations MAY bypass these checks when necessary for operational or compliance reasons.
Burning in permissionless contexts (e.g., public burn functions) MUST respect the canTransfer check, MUST respect the canSend check on the token holder, and MUST NOT allow burning more assets than the unfrozen amount. In permissioned contexts (e.g., authorized burning by privileged roles), burning MAY succeed for accounts where canSend on the token holder would return false, and MAY burn more assets than the unfrozen amount, in which case the contract MUST update the frozen status accordingly and emit a Frozen event before the underlying base token transfer event.

The ERC7943CannotSend/ERC7943CannotReceive/ERC7943CannotTransfer errors MAY be used as a general revert mechanism whenever internal calls to canSend/canReceive/canTransfer return false. They MAY be replaced by more specific errors depending on the custom checks performed inside those calls, or simply not used.

In general, the standard prioritizes error specificity, meaning that specific errors such as ERC7943InsufficientUnfrozenBalance SHOULD be thrown when applicable. The ERC7943InsufficientUnfrozenBalance error SHOULD be triggered when a transfer is attempted from account with an amount less than or equal to its balance, but greater than its unfrozen balance, or with a tokenId which is currently frozen. If the amount is greater than the whole balance or the tokenId is not owned by the account, unrelated to the frozen amount, more specific errors from the base standard SHOULD be used instead.

Rationale

Minimalism: Defines only the essential functions (forcedTransfer, setFrozenTokens, canSend, canReceive, canTransfer, getFrozenTokens) and associated events/errors needed for common RWA compliance and control patterns, avoiding mandated complexity or opinionated features. The reason to introduce specific errors (ERC7943CannotSend, ERC7943CannotReceive, ERC7943CannotTransfer, and ERC7943InsufficientUnfrozenBalance) is to provide completeness with the introduced functionalities (canSend, canReceive, canTransfer, and getFrozenTokens). As dictated in the specifications, error specificity is prioritized, leaving space for implementations to accommodate more explicit errors. Regarding the events Frozen and ForcedTransfer, the reason for their existence is to signal uncommon transfers (like in forcedTransfer) but also to help off-chain indexers correctly keep track and account for asset seizures and freezing. As mentioned in the specifications, the order in which these events are emitted in relation to the base token contract events is important in practice and merits special attention.
Separation of concerns: The standard separates account-level eligibility (canSend, canReceive) from transfer-level authorization (canTransfer). canSend and canReceive evaluate whether an account is eligible to participate independently of any specific transfer parameters such as counterparty, amount, or token identifier. canTransfer evaluates whether a specific transfer is permissible under permissioned compliance rules, taking into account frozen balances, transfer limits, counterparty restrictions, and account eligibility. This separation provides clear semantics for integrators and avoids confusion between account eligibility and transfer-specific validation. It also enables one-way restrictions where an account may be blocked from receiving but still allowed to send, which is common in regulated environments.
Flexible compliance: Provides standard view functions (canSend, canReceive, canTransfer, getFrozenTokens) for compliance checks without dictating how those checks are implemented internally by the token contract. This allows diverse compliance strategies.
Compatibility: Designed as an interface layer compatible with existing base standards like ERC-20, ERC-721, ERC-1155, and ERC-6909. Implementations extend from ERC-7943 alongside their base standard interface.
Essential enforcement rules: Includes forcedTransfer and setFrozenTokens as standard functions, acknowledging their importance for regulatory enforcement in the RWA space, distinct from standard transfers. Mandates access control for these sensitive functions. To maintain a lean EIP, a single setFrozenTokens function (which overwrites the frozen asset quantity) and one Frozen event were favored over distinct freeze/unfreeze functions and events.
ERC-165: Ensures implementing contracts can signal support for this interface.

As an example, an AMM pool or a lending protocol can integrate with ERC-7943-based ERC-20 tokens by calling canSend, canReceive, or canTransfer to handle these assets in a compliant manner. Enforcement actions like forcedTransfer and setFrozenTokens can either be called by third-party entities or be integrated by external protocols to allow for automated and programmable compliance. Users can then expand these tokens with additional features to fit the specific needs of individual asset types, such as on-chain identity systems, historical balance tracking for dividend distributions, semi-fungibility with token metadata, and other custom functionalities.

Extensibility

While this ERC provides the necessary primitives for regulated assets, any additional feature can be added through extensions. A few examples:

1) If for any administrative function like setFrozenTokens it is necessary to attach a proof to the call, the contract can have a function that batches operations like:

contract TokenWithLegalProofs is IERC7943MultiToken {
    ...

    function setFrozenTokensWithProof(address account, uint256 tokenId, uint256 amount, bytes calldata legalProof) external onlyOwner returns (bool result) {
        /// do anything with `legalProof`
        return setFrozenTokens(account, tokenId, amount);
    }
}

2) Since the setFrozenTokens function overwrites the absolute frozen amount and given the fact that the standard allows for multiple privileged accounts, some race-conditions might happen. If that’s the case, one can build an extension function that works with expected values of amounts frozen, like:

function setFrozenTokensIf(address account, uint256 expectedPrev, uint256 newAmount) external onlyOwner returns (bool result) {
     require(frozenTokens[account] == expectedPrev, ERC7943ExpectedValueMismatch(expectedPrev, frozenTokens[account]));
     return setFrozenTokens(account, newAmount);
}

Alternatively, another solution can be using delta amounts:

function setFrozenTokensDelta(address account, int256 deltaAmount) external onlyOwner returns (bool result) {
     uint256 actualValue = frozenTokens[account];
     if(deltaAmount >= 0) actualValue += uint256(deltaAmount);
     else {
        uint256 sub = uint256(-deltaAmount);
        require(sub <= actualValue, ERC7943ExpectedValueMismatch(sub, actualValue));
        actualValue -= sub;
     }
     return setFrozenTokens(account, actualValue);
}

Note: These helpers reduce accidental overwrites and expand in functionalities but do not prevent same-block conflicting updates or mempool ordering races by different privileged actors.

3) Developers can also perform several operations through the use of multicall patterns similar to the one defined in ERC-6357 so that a mix of the given primitives with additional features can be batched in one transaction:

contract ERC7943Fungible is IERC7943Fungible, Multicall {
    // Now any combination of `setFrozenTokens`/`forcedTransfer`
    // coupled with other functionalities like the ones to blacklist/whitelist users
    // can be submitted in one transaction through the use of `multicall` function
}

4) Functionalities like pausability can be added on top, either through the use of modifiers or directly within functions implementations:

function canTransfer(address from, address to, uint256 amount) external view returns (bool allowed) {
    if(paused()) return allowed;
    // ... other checks
}

Notes on Naming

The naming conventions in this ERC were carefully chosen to establish clarity and semantic consistency within the broader RWA ecosystem while maintaining neutrality and broad applicability.

forcedTransfer: This term was selected for its neutrality. While names like confiscation, revocation, or recovery describe specific motivations, forcedTransfer purely denotes the direct action of transferring assets, irrespective of the underlying reason. forcedTransfer was preferred over forceTransfer to maintain backward compatibility with ERC-3643.
canSend / canReceive: These names were chosen to clearly express the directional nature of account eligibility: whether an account is allowed to send or receive tokens. This separation enables one-way restrictions (e.g., an account blocked from receiving but still allowed to send), which are common in regulated environments such as KYC expiry, AML alerts, or jurisdictional constraints.
canTransfer: This name was preferred over isTransferAllowed for consistency with established RWA standards including ERC-3643 and ERC-7518. This alignment promotes interoperability and reduces cognitive overhead when working across different RWA tokens.
setFrozenTokens / getFrozenTokens: These names were chosen for managing transfer restrictions and align with ERC-3643 naming patterns. Frozen was also selected for its general applicability to both fungible (amount-based) and non-fungible (status-based) assets, as terms like amount or asset(s) might not be universally fitting.
ERC7943InsufficientUnfrozenBalance: Discussions around insufficient being similar to unavailable arose, where unavailable might have better suggested a temporal condition like a freezing status. However, the term available/unavailable was also overlapping with frozen/unfrozen creating more confusion and duality. Finally, coupling insufficient with the specified unfrozen balance better represents the domain, prefix, and subject of the error, according to ERC-6093 guidelines.

Backwards Compatibility

This EIP defines a new interface standard and does not alter existing ones like ERC-20, ERC-721, and ERC-1155. Standard wallets and explorers can interact with the base token functionality of implementing contracts, subject to the rules enforced by that contract’s implementation of canSend, canReceive, canTransfer, and getFrozenTokens functions. Full support for the ERC-7943 functions requires explicit integration.

Reference Implementation

Reference implementations of uRWA for ERC-20, ERC-721, and ERC-1155 token implementations are provided in the assets folder. They use the OpenZeppelin library and include separate send/receive whitelists and enumerable role-based access control. These examples are provided for educational purposes only and are not audited.

Security Considerations

Access Control for forcedTransfer and setFrozenTokens: The security of the mechanism chosen by the implementer to restrict access to these functions is paramount. Unauthorized access could lead to asset theft. Secure patterns (multisig, timelocks) are highly recommended.
Front-running of the forcedTransfer and setFrozenTokens functions: Both functions are susceptible to front-running, similar to the approve function of ERC-20. Furthermore, if the suggestion to allow freezing more than what an account owns is not followed, any account may be incentivized to front-run attempts to freeze its balance when receiving new funds. Additional features to gradually increment or decrement the frozen status MAY be considered for implementation.
Standard Contract Security: Implementations MUST adhere to general smart contract security best practices (reentrancy guards where applicable, checks-effects-interactions, etc.). Specifically, in the checks-effects-interactions consideration, implementations need to be aware of tokens having hooks, especially on recipients as in ERC-721 or ERC-1155. In such circumstances, it might be convenient to adopt reentrancy guards to prevent unwanted executions.