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

RTA-Controlled Security Token

Tue, 25 Sep 2018 00:00:00 +0000

EIP #1450 - RTA-Controlled Security Token is in Last Call status. It is authored by Howard Marks (@howardmarks) , Devender Gollapally (@devender-startengine) , Joe Mathews (@se-joe) , Jordan Jahja (@jordan-jahja) , John Shiple (@johnshiple), David Zhang (@david-colab) and was originally created 2018-09-25. 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-1450-rta-controlled-security-token-standard/26385

Abstract

ERC-1450 facilitates the recording of ownership and transfer of securities sold in compliance with Securities Act Regulations CF, D, and A. This standard is informed by practical operational experience from SEC-registered transfer agents, broker-dealers, and alternative trading systems that have collectively managed billions in compliant securities offerings. The design addresses the full lifecycle of digital securities from issuance through secondary trading.

The standard introduces a unique RTA-controlled model where the Registered Transfer Agent maintains exclusive authority over all token operations. Unlike permissionless tokens, ERC-1450 enforces strict compliance by requiring the RTA to execute all mints, burns, and transfers, while disabling direct value movement via transfer() and approve(). Holder-initiated transfer requests are permitted via requestTransferWithFee(), but no value moves unless the RTA authorizes and executes the transfer. The standard also enables compliant secondary markets through a broker registration system, where vetted brokers can request transfers with fees on behalf of holders. This design ensures regulatory compliance with SEC requirements and state blue sky laws while providing liquidity options and maintaining read-only compatibility with existing ERC-20 infrastructure.

Key features include RTA-exclusive control, restricted ERC-20 interface for ecosystem integration, and built-in mechanisms for regulatory compliance including recovery procedures for lost tokens and support for court-ordered transfers. The standard MAY optionally implement EIP-3668 (CCIP-Read) for off-chain compliance pre-checks, improving user experience by allowing wallets to validate transfers before gas payment.

Motivation

With the advent of the JOBS Act in 2012 and subsequent regulations (Regulation Crowdfunding in 2016, amended Reg A and Reg D), there has been significant expansion in exemptions for securities offerings. The regulated securities market has grown substantially, with billions in offerings across thousands of companies.

Experience from operating SEC-registered transfer agents has revealed critical gaps in existing token standards for securities. While standards like ERC-3643 provide on-chain compliance mechanisms, they don’t address the unique regulatory requirements of U.S. securities law, particularly the role of Registered Transfer Agents.

Current challenges that ERC-1450 addresses:

Transfer Controller Authority: SEC regulations require Registered Transfer Agents to maintain exclusive control over securities transfers, similar to designated controller requirements in other jurisdictions
Recovery Mechanisms: Legal requirements for recovering lost or stolen securities
Court Orders: Ability to execute court-ordered transfers (divorce, estate, fraud recovery)
Regulatory Reporting: Clear audit trails for regulatory examinations
Cost Efficiency: Leveraging existing transfer agent infrastructure for compliance

ERC-20 tokens do not support the regulated roles of Funding Portal, Broker Dealer, RTA, and Investor and do not support the Bank Secrecy Act/USA Patriot Act KYC and AML requirements. Other improvements (notably Simple Restricted Token Standards) have tried to tackle KYC and AML regulatory requirements. This approach assigns exclusive control over transferFrom, mint, and burnFrom to a designated transfer agent who performs KYC and AML compliance.

This standard codifies operational requirements into a technical specification that bridges traditional securities regulation with blockchain technology.

Specification

ERC-1450 extends ERC-20.

Optional Dependencies

The following standards MAY be implemented for enhanced functionality but are NOT required for compliance:

EIP-3668 (CCIP-Read): MAY be used for off-chain compliance pre-checks. Implementations choosing to support this MUST implement the preCheckCompliance and preCheckComplianceCallback functions as specified.
ERC-1820 (Registry): MAY be used for interface registration. Implementations can optionally register their interfaces in the ERC-1820 registry for improved discoverability.

In addition to the optional standards above, the following interface components defined in this specification are OPTIONAL extensions. Implementations MAY omit them; implementations that provide them MUST follow the behavior specified for them (including emitting the specified events):

Document management (setDocument, getDocument, removeDocument, getAllDocuments)
Structured recovery workflow (initiateRecovery, cancelRecovery, executeRecovery, getRecoveryDetails, hasPendingRecovery) — the REQUIRED baseline for lost-wallet recovery and court-ordered transfers is controllerTransfer, which all implementations MUST provide
KYC status view (isKYCVerified)
Gasless fee approval (requestTransferWithPermit)
Off-chain compliance pre-checks (preCheckCompliance, preCheckComplianceCallback)
Transfer request status view (getRequestStatus) — implementations MAY instead expose equivalent request data through other read methods (e.g., a public storage mapping)

ERC-1450

ERC-1450 is an interface standard that defines a security token where only the Registered Transfer Agent (RTA) has authority to execute transfers, mints, and burns. The token represents securities issued by an owner (the issuer) and managed exclusively by an RTA.

The standard enforces strict role separation:

Owner/Issuer: The entity that creates and owns the security
RTA: The only entity authorized to transfer, mint, or burn tokens
Token Holders: Cannot initiate transfers directly (unlike standard ERC-20)

ERC-1450 explicitly disables direct value movement by requiring the transfer and approve functions to always revert. Only the RTA can execute token movements via transferFrom, mint, and burnFrom functions. Holder-initiated transfer requests are permitted via requestTransferWithFee(), but no value moves unless the RTA authorizes and executes the transfer. Registered brokers can also request transfers on behalf of holders through the same mechanism. This design ensures regulatory compliance by centralizing all token operations through the regulated RTA.

Critical security feature: The changeIssuer function can only be called by the RTA, not the owner. This protects against compromised issuer keys - even if an issuer’s private key is stolen, the attacker cannot change the RTA or steal tokens.

Issuers and RTAs

Implementations must initialize the following parameters upon deployment:

owner: The issuer’s address
transferAgent: The RTA’s address (preferably an RTAProxy contract)
name: The security’s name
symbol: The security’s trading symbol
decimals: The number of decimal places (0 for indivisible shares, up to 18 for fractional)

Access Control Model

The interface defines three levels of access control:

RTA-Only Functions:

changeIssuer: Change the token issuer/owner (only callable by RTA, not by issuer)
transferFrom: Transfer tokens between accounts
mint: Create new tokens
burnFrom: Destroy existing tokens
All batch operations and fee collection functions

Owner-Only Functions:

setTransferAgent: One-time setup to RTAProxy (locked after initial setup)

Public Functions:

isTransferAgent: Check if an address is the current RTA
Standard ERC-20 view functions (balanceOf, totalSupply, etc.)

Security and Compliance

The RTA maintains exclusive control over all token movements, ensuring:

Complete audit trail for regulatory reporting
Enforcement of transfer restrictions
Recovery mechanisms for lost tokens
Execution of court orders
Prevention of unauthorized transfers

ERC-20 Extension

ERC-20 tokens provide the following functionality:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IERC20 {
    function totalSupply() external view returns (uint256);
    function balanceOf(address account) external view returns (uint256);
    function transfer(address to, uint256 amount) external returns (bool);
    function allowance(address owner, address spender) external view returns (uint256);
    function transferFrom(address from, address to, uint256 amount) external returns (bool);
    function approve(address spender, uint256 amount) external returns (bool);

    event Transfer(address indexed from, address indexed to, uint256 value);
    event Approval(address indexed owner, address indexed spender, uint256 value);
}

ERC-165 interface for standard interface detection:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IERC165 {
    /**
     * @notice Query if a contract implements an interface
     * @param interfaceId The interface identifier, as specified in [ERC-165](/EIPS/eip-165)
     * @return bool True if the contract implements `interfaceId`
     */
    function supportsInterface(bytes4 interfaceId) external view returns (bool);
}

ERC-20 is extended as follows:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

/**
 * @title ERC-1450: RTA-Controlled Security Token (Restricted ERC-20 Interface)
 * @notice Facilitates compliance with Securities Act Regulations CF, D, and A
 * @dev This standard extends ERC-20 with RTA-controlled transfer restrictions
 *
 * Key Features:
 * - RTA (Registered Transfer Agent) exclusive control over transfers
 * - Direct value movement disabled (transfer, approve functions always revert)
 * - Holder-initiated transfer requests permitted via requestTransferWithFee (requires RTA execution)
 * - Built-in recovery mechanisms for lost tokens
 * - Support for court-ordered transfers
 * - Restricted ERC-20 interface for read operations and ecosystem integration
 * - ERC-6093 compliant error messages for tooling interoperability
 */
interface IERC1450 is IERC20, IERC165 {
    // ============ ERC-6093 Standard Errors ============
    // Using standard errors from ERC-6093 for consistent tooling support

    // Standard ERC-20 errors (from ERC-6093)
    error ERC20InsufficientBalance(address sender, uint256 balance, uint256 needed);
    error ERC20InvalidSender(address sender);
    error ERC20InvalidReceiver(address receiver);
    error ERC20InvalidApprover(address approver);
    error ERC20InvalidSpender(address spender);
    error ERC20InsufficientAllowance(address spender, uint256 allowance, uint256 needed);

    // Standard Access Control errors (from ERC-6093)
    // NOTE: We retain OpenZeppelin error names for tooling compatibility, but semantics differ:
    // - "Owner" in ERC-1450 means "Issuer" (the entity that created the token)
    // - Unlike OpenZeppelin's Ownable, only the RTA can change the issuer, not the issuer themselves
    error OwnableUnauthorizedAccount(address account);  // Non-issuer attempts issuer-only operation
    error OwnableInvalidOwner(address owner);  // Invalid issuer address (e.g., zero address)

    // ============ ERC-1450 Specific Errors ============
    // Custom errors only when ERC-6093 standard errors are insufficient

    error ERC1450TransferDisabled();  // For disabled transfer/approve functions
    error ERC1450OnlyRTA();  // Operation restricted to RTA only
    error ERC1450TransferAgentLocked();  // RTA proxy is locked from changes
    error ERC1450ComplianceCheckFailed(address from, address to);  // KYC/AML failure

    // Events
    event IssuerChanged(address indexed previousIssuer, address indexed newIssuer);
    event TransferAgentUpdated(address indexed previousAgent, address indexed newAgent);

    /**
     * @notice Emitted when tokens are minted with regulation tracking
     * @param to Recipient of the minted tokens
     * @param amount Number of tokens minted
     * @param regulationType Regulation under which tokens were issued
     * @param issuanceDate Original share issuance date
     * @param tokenizationDate When tokenized on blockchain (block.timestamp)
     * @dev MUST be emitted for every mint operation
     *      Allows reconstruction of entire cap table from events
     *      Critical for regulatory reporting and audit trails
     */
    event TokensMinted(
        address indexed to,
        uint256 amount,
        uint16 indexed regulationType,
        uint256 issuanceDate,
        uint256 tokenizationDate
    );

    /**
     * @notice Emitted when tokens are burned with regulation tracking
     * @param from Address from which tokens were burned
     * @param amount Number of tokens burned
     * @param regulationType Regulation type of burned tokens
     * @param issuanceDate Original issuance date of burned tokens
     * @dev MUST be emitted for every burn operation
     *      Critical for maintaining accurate cap table and regulatory reporting
     */
    event TokensBurned(
        address indexed from,
        uint256 amount,
        uint16 indexed regulationType,
        uint256 issuanceDate
    );

    /**
     * @notice Emitted when tokens are transferred with specific regulation tracking
     * @param from Source address
     * @param to Destination address
     * @param amount Number of tokens transferred
     * @param regulationType Regulation type of the transferred tokens
     * @param issuanceDate Original issuance date of the transferred tokens
     * @dev Provides complete traceability of regulated token movements
     *      Essential for compliance reporting and audit trails
     */
    event RegulatedTransfer(
        address indexed from,
        address indexed to,
        uint256 amount,
        uint16 indexed regulationType,
        uint256 issuanceDate
    );

    // Core RTA Functions

    /**
     * @notice Change the issuer (owner) of the token contract
     * @param newIssuer Address of the new issuer
     * @dev Only callable by the RTA. Must be restricted with onlyTransferAgent modifier.
     *      Emits IssuerChanged event (not OwnershipTransferred)
     *
     *      IMPORTANT: This differs from OpenZeppelin's Ownable pattern:
     *      - In Ownable: owner can transfer ownership themselves
     *      - In ERC-1450: ONLY the RTA can change the issuer
     *      - Terminology: "Issuer" = the token creator/owner, not the controller
     *      - This prevents compromised issuer keys from hijacking the token
     *
     *      The issuer maintains rights to:
     *      - Receive proceeds from offerings
     *      - Update corporate documents (via ERC-1643)
     *      - Make business decisions
     *      But CANNOT control token transfers or change the RTA
     */
    function changeIssuer(address newIssuer) external;

    /**
     * @notice Update the transfer agent address (one-time use or RTA-only after initial setup)
     * @param newTransferAgent Address of the new transfer agent (should be RTAProxy contract)
     * @dev After initial setup to RTAProxy, only the RTA can rotate itself via the proxy.
     *      This prevents compromised issuers from changing the RTA.
     */
    function setTransferAgent(address newTransferAgent) external;

    /**
     * @notice Check if an address is the current transfer agent
     * @param account Address to check
     * @return bool True if the address is the current transfer agent
     */
    function isTransferAgent(address account) external view returns (bool);

    // ERC-20 Overrides (Restricted Functions)

    /**
     * @notice Transfer tokens - DISABLED for security tokens
     * @dev Must always revert with ERC1450TransferDisabled()
     *      Uses specific error for disabled functionality per [ERC-6093](/EIPS/eip-6093) guidelines
     */
    function transfer(address to, uint256 amount) external override returns (bool);

    /**
     * @notice Approve spending - DISABLED for security tokens
     * @dev Must always revert with ERC1450TransferDisabled()
     *      Uses specific error for disabled functionality per [ERC-6093](/EIPS/eip-6093) guidelines
     */
    function approve(address spender, uint256 amount) external override returns (bool);

    /**
     * @notice Get spending allowance - DISABLED for security tokens
     * @dev Must always return 0
     */
    function allowance(address owner, address spender) external view override returns (uint256);

    /**
     * @notice Transfer tokens - DISABLED for security tokens
     * @dev Must always revert with ERC1450TransferDisabled()
     *      Uses specific error for disabled functionality per [ERC-6093](/EIPS/eip-6093) guidelines
     *      Use transferFromRegulated() for actual transfers with regulation tracking
     */
    function transferFrom(address from, address to, uint256 amount) external override returns (bool);

    // RTA-Controlled Functions

    /**
     * @notice Transfer tokens between accounts with regulation tracking (RTA only)
     * @param from Source address
     * @param to Destination address
     * @param amount Number of tokens to transfer
     * @param regulationType Type of regulation for the transferred tokens
     * @param issuanceDate Original issuance date of the transferred tokens
     * @dev Only callable by the registered transfer agent
     *      The regulation type and issuance date specify which tokens to transfer
     *      MUST revert if sender has insufficient tokens of the specified regulation/issuance
     *      Callers SHOULD first check holdings via getHolderRegulations() or getDetailedBatchInfo()
     *      This enables precise control over which token batches are moved
     *      The RTA determines the transfer strategy (FIFO, LIFO, tax optimization, etc.)
     */
    function transferFromRegulated(address from, address to, uint256 amount, uint16 regulationType, uint256 issuanceDate) external returns (bool);

    /**
     * @notice Mint new tokens with regulation tracking (RTA only)
     * @param to Address to receive the minted tokens
     * @param amount Number of tokens to mint
     * @param regulationType Type of regulation under which shares were issued (uint16 for global compatibility)
     * @param issuanceDate Unix timestamp when shares were originally issued (not tokenization date)
     * @dev Only callable by the registered transfer agent
     *      Every security MUST specify a regulation type - there are no "unregulated" securities
     *      For tokenizing existing securities, issuanceDate should be when investor originally purchased
     *      For new issuances, issuanceDate would typically be block.timestamp
     *      RTA uses issuanceDate to calculate holding periods for regulatory compliance
     */
    function mint(address to, uint256 amount, uint16 regulationType, uint256 issuanceDate) external returns (bool);

    /**
     * @notice Batch mint tokens with regulation tracking (RTA only)
     * @param recipients Array of addresses to receive the minted tokens
     * @param amounts Array of token amounts to mint for each recipient
     * @param regulationTypes Array of regulation types for each mint
     * @param issuanceDates Array of issuance timestamps for each mint
     * @dev Only callable by the registered transfer agent
     *      All arrays MUST be the same length
     *      Each mint operation follows the same rules as individual mint()
     *      Reverts if any single mint would fail
     *      Emits TokensMinted event for each successful mint
     *      Enables efficient bulk issuance while maintaining compliance tracking
     */
    function batchMint(
        address[] calldata recipients,
        uint256[] calldata amounts,
        uint16[] calldata regulationTypes,
        uint256[] calldata issuanceDates
    ) external returns (bool);

    /**
     * @notice Burn tokens from an account (RTA only) - Uses RTA's chosen strategy
     * @param from Address from which to burn tokens
     * @param amount Number of tokens to burn
     * @dev Only callable by the registered transfer agent
     *      The RTA determines which tokens to burn based on their strategy (FIFO, LIFO, tax optimization, etc.)
     *      Use burnFromRegulated() to burn specific regulation/issuance tokens
     */
    function burnFrom(address from, uint256 amount) external returns (bool);

    /**
     * @notice Burn tokens from an account with regulation tracking (RTA only)
     * @param from Address from which to burn tokens
     * @param amount Number of tokens to burn
     * @param regulationType Type of regulation for the tokens to burn
     * @param issuanceDate Original issuance date of the tokens to burn
     * @dev Only callable by the registered transfer agent
     *      Burns specific tokens identified by regulation type and issuance date
     *      MUST revert if holder has insufficient tokens of the specified regulation/issuance
     *      Callers SHOULD first check holdings via getHolderRegulations() or getDetailedBatchInfo()
     *      MUST emit TokensBurned event with the specific regulation details
     */
    function burnFromRegulated(address from, uint256 amount, uint16 regulationType, uint256 issuanceDate) external returns (bool);

    /**
     * @notice Burn tokens of a specific regulation type (RTA only)
     * @param from Address from which to burn tokens
     * @param amount Number of tokens to burn
     * @param regulationType Specific regulation type to burn
     * @dev Only callable by the registered transfer agent
     *      Useful for partial redemptions, buybacks, or regulation-specific corporate actions
     *      Reverts if holder has insufficient tokens of the specified regulation type
     *      MUST emit TokensBurned event with the specific regulation details
     */
    function burnFromRegulation(address from, uint256 amount, uint16 regulationType) external returns (bool);

    /**
     * @notice Get token decimals (OPTIONAL per [EIP-20](/EIPS/eip-20))
     * @return uint8 The number of decimal places (0-18)
     * @dev Set at deployment based on security type:
     *      - 0 for traditional indivisible shares
     *      - Greater than 0 for fractional shares (mutual funds, REITs, fractional trading)
     *      - Must be immutable after deployment
     *
     *      NOTE: Per [EIP-20](/EIPS/eip-20), name(), symbol(), and decimals() are OPTIONAL
     *      Implementations SHOULD provide these for better UX
     *      Wallets MUST NOT assume these functions exist
     */
    function decimals() external view returns (uint8);

    // Introspection for Restricted ERC-20 Interface Detection

    /**
     * @notice Check if this is a security token with restricted transfers
     * @return bool Always returns true for ERC-1450 tokens
     * @dev Critical for wallets/DEXs to detect restricted tokens and handle appropriately.
     *      Prevents users from attempting transfers that will always fail.
     */
    function isSecurityToken() external pure returns (bool);

    /**
     * @notice Returns the contract implementation version
     * @return string Semantic version string (e.g., "1.17.0")
     * @dev Enables upgrade detection for UUPS-upgradeable contracts.
     *      Version SHOULD match the reference implementation package version.
     *      Useful for:
     *      - Detecting available upgrades by comparing deployed vs local version
     *      - Audit trails showing which version was deployed
     *      - Debugging and support by identifying exact implementation
     */
    function version() external pure returns (string memory);

    /**
     * @notice [EIP-165](/EIPS/eip-165) support for interface detection
     * @param interfaceId The interface identifier to check
     * @return bool True if the contract implements the interface
     * @dev MUST return true for:
     *      - 0x01ffc9a7: [ERC-165](/EIPS/eip-165) interface ID
     *      - 0xXXXXXXXX: IERC1450 interface ID (see Interface Detection section for calculation)
     *
     *      MUST return false for:
     *      - 0x36372b07: [ERC-20](/EIPS/eip-20) interface ID
     *
     *      Returning false for [ERC-20](/EIPS/eip-20) prevents wallets from assuming standard transfer behavior.
     *      While we are ABI-compatible with [ERC-20](/EIPS/eip-20), we are not behaviorally compatible
     *      since transfer() and approve() always revert.
     */
    function supportsInterface(bytes4 interfaceId) external view returns (bool);

    // KYC/AML Status Check (OPTIONAL)

    /**
     * @notice Check if an address has been KYC verified (OPTIONAL)
     * @param account Address to check
     * @return verified Whether the address is linked to a verified person
     * @return expiryDate When the KYC verification expires (0 if not verified)
     * @dev This is a view function that queries the RTA's off-chain database
     *      Never returns actual identity information, only verification status
     *      Implementations MAY choose to implement this for transparency
     *      Returns false for addresses that have never been verified
     */
    function isKYCVerified(address account) external view returns (bool verified, uint256 expiryDate);

    // Regulation Tracking Query Functions

    /**
     * @notice Get regulation information for tokens held by an address
     * @param holder Address to query
     * @return regulationTypes Array of regulation types for holder's tokens
     * @return amounts Array of token amounts per regulation type
     * @return issuanceDates Array of original issuance dates
     * @dev MUST return arrays of equal length representing holder's token composition
     *      Implementation MUST store this data persistently on-chain
     *      RTA uses this for transfer calculations and compliance checks
     */
    function getHolderRegulations(address holder) external view returns (
        uint16[] memory regulationTypes,
        uint256[] memory amounts,
        uint256[] memory issuanceDates
    );

    /**
     * @notice Get total tokens minted under a specific regulation
     * @param regulationType The regulation type to query
     * @return totalSupply Total tokens minted under this regulation
     * @dev Useful for regulatory reporting and tracking offering limits
     */
    function getRegulationSupply(uint16 regulationType) external view returns (uint256 totalSupply);

    /**
     * @notice Get detailed batch information for a holder's tokens
     * @param holder Address to query
     * @return count Number of unique batches the holder has
     * @return regulationTypes Array of regulation types for each batch
     * @return issuanceDates Array of issuance dates for each batch
     * @return amounts Array of token amounts for each batch
     * @dev Returns comprehensive batch-level details for a holder
     *      Useful for detailed cap table management and regulatory reporting
     *      Each index represents a unique batch of tokens with specific regulation/issuance
     */
    function getDetailedBatchInfo(address holder) external view returns (
        uint256 count,
        uint16[] memory regulationTypes,
        uint256[] memory issuanceDates,
        uint256[] memory amounts
    );

    // Batch Operations for Gas Efficiency

    /**
     * @notice Batch transfer tokens between multiple address pairs with regulation tracking (RTA only)
     * @param froms Array of source addresses
     * @param tos Array of destination addresses
     * @param amounts Array of token amounts to transfer
     * @param regulationTypes Array of regulation types for each transfer
     * @param issuanceDates Array of issuance dates for each transfer
     * @return bool True if all transfers succeed
     * @dev All arrays must have equal length. Reverts if any transfer fails.
     *      Only callable by the registered transfer agent.
     *      MUST revert if any sender has insufficient tokens of the specified regulation/issuance
     *      The RTA determines the transfer strategy for each transfer
     *      Useful for dividend distributions, corporate actions, etc.
     */
    function batchTransferFrom(
        address[] calldata froms,
        address[] calldata tos,
        uint256[] calldata amounts,
        uint16[] calldata regulationTypes,
        uint256[] calldata issuanceDates
    ) external returns (bool);

    /**
     * @notice Batch burn tokens from multiple addresses with regulation tracking (RTA only)
     * @param froms Array of addresses from which to burn tokens
     * @param amounts Array of token amounts to burn from each address
     * @param regulationTypes Array of regulation types for each burn
     * @param issuanceDates Array of issuance dates for each burn
     * @return bool True if all burns succeed
     * @dev All arrays must have equal length. Reverts if any burn fails.
     *      Only callable by the registered transfer agent.
     *      MUST revert if any holder has insufficient tokens of the specified regulation/issuance
     *      Useful for redemptions, corporate buybacks, etc.
     */
    function batchBurnFrom(
        address[] calldata froms,
        uint256[] calldata amounts,
        uint16[] calldata regulationTypes,
        uint256[] calldata issuanceDates
    ) external returns (bool);

    // Fee Collection Mechanism

    /**
     * @notice Register or deregister a broker for this token (RTA only)
     * @param broker Address of the broker to register/deregister
     * @param isApproved Whether to approve or revoke broker status
     * @dev Only callable by RTA after due diligence. Brokers must:
     *      1. Apply off-chain to the RTA
     *      2. Pass KYC/AML and regulatory checks
     *      3. Sign broker agreement
     *      4. Be approved by RTA compliance team
     *
     *      RECOMMENDED: Brokers SHOULD use a proxy pattern similar to RTAProxy
     *      for key management and operational security. This allows:
     *      - Secure key rotation without re-registration
     *      - Multi-signature controls for broker operations
     *      - Business continuity during personnel changes
     *      - Protection against individual key compromise
     *
     *      The broker address registered here MAY be:
     *      - Direct broker-controlled address (simple but less secure)
     *      - BrokerProxy contract address (recommended for production)
     */
    function setBrokerStatus(address broker, bool isApproved) external;

    /**
     * @notice Check if an address is a registered broker
     * @param broker Address to check
     * @return bool True if the address is an approved broker
     */
    function isRegisteredBroker(address broker) external view returns (bool);

    /**
     * @notice Request a transfer with fee payment
     * @param from Source address for the transfer
     * @param to Destination address for the transfer
     * @param amount Number of tokens to transfer
     * @param feeAmount Amount of fee being paid (in the configured fee token)
     * @return requestId Unique identifier for this request (for idempotency and tracking)
     * @dev Creates a new transfer request with initial status: RequestStatus.Requested
     *
     *      Fee payment:
     *      - Fee MUST be paid in the configured fee token (see getFeeToken())
     *      - Caller MUST have approved the token contract to spend feeAmount
     *      - Fee is transferred via safeTransferFrom from msg.sender
     *
     *      Fee payment responsibility:
     *      - Holder-initiated (msg.sender == from): Holder pays the fee
     *      - Broker-initiated (msg.sender != from): Broker pays fee on behalf of client
     *      - Settlement failures: Fees are NOT automatically refunded (RTA discretion)
     *
     *      Request lifecycle:
     *      1. Request created with unique requestId (status: Requested)
     *      2. RTA reviews request (status: UnderReview - optional)
     *      3. RTA approves/rejects (status: Approved or Rejected)
     *      4. If approved, RTA executes transfer (status: Executed)
     *      5. Optional: Request expires after timeout (status: Expired)
     *
     *      Idempotency guarantee:
     *      - Each requestId is unique and can only be executed ONCE
     *      - Duplicate execution attempts MUST revert
     *      - Clients can safely retry requests with new requestId if needed
     *
     *      Authorization requirements:
     *      - If msg.sender == from: Token holder requesting their own transfer
     *      - If msg.sender != from: Must be a registered broker (via setBrokerStatus)
     *      - Reverts if neither condition is met
     *
     *      Implementation MUST:
     *      - Verify fee token is configured (revert if not)
     *      - Generate unique requestId for each request
     *      - Emit TransferRequested event
     *      - Store request details for later processing
     *      - Prevent double-spending by tracking request status
     */
    function requestTransferWithFee(
        address from,
        address to,
        uint256 amount,
        uint256 feeAmount
    ) external returns (uint256 requestId);

    /**
     * @notice Request transfer with [EIP-2612](/EIPS/eip-2612) permit for gasless fee approval (OPTIONAL)
     * @param from Source address for the transfer
     * @param to Destination address for the transfer
     * @param amount Number of tokens to transfer
     * @param feeAmount Amount of fee being paid (in the configured fee token)
     * @param deadline Permit signature deadline
     * @param v ECDSA signature v parameter
     * @param r ECDSA signature r parameter
     * @param s ECDSA signature s parameter
     * @return requestId Unique identifier for this transfer request
     * @dev OPTIONAL: Allows fee payment without prior approve() transaction
     *      Uses [EIP-2612](/EIPS/eip-2612) permit for gasless approval of fee token
     *      Particularly useful for first-time users who don't have fee token approvals
     *      MUST revert if the configured fee token doesn't support [EIP-2612](/EIPS/eip-2612)
     *      Example: USDC, DAI, and other modern stablecoins support permit
     *
     *      Implementation:
     *      1. Call permit on the configured fee token with the provided signature
     *      2. Then execute the same logic as requestTransferWithFee
     *      3. This avoids users needing a separate approve transaction for fees
     */
    function requestTransferWithPermit(
        address from,
        address to,
        uint256 amount,
        uint256 feeAmount,
        uint256 deadline,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) external returns (uint256 requestId);

    /**
     * @notice Get current fee for a transfer
     * @param from Source address
     * @param to Destination address
     * @param amount Transfer amount
     * @return feeAmount Required fee amount in the configured fee token
     * @dev Allows dynamic fee calculation based on transfer parameters
     *      Fee is always denominated in the configured fee token (see getFeeToken())
     *      Fee type determines calculation:
     *      - Type 0 (flat): Returns feeValue directly
     *      - Type 1 (percentage): Returns (amount * feeValue) / 10000
     */
    function getTransferFee(address from, address to, uint256 amount)
        external view returns (uint256 feeAmount);

    /**
     * @notice Get the configured fee token address
     * @return token The [ERC-20](/EIPS/eip-20) token used for fee payments
     * @dev Returns address(0) if no fee token is configured yet
     *      RTA MUST configure a fee token before transfers can be requested
     *      Common choices: USDC, USDT, or other stablecoins
     */
    function getFeeToken() external view returns (address token);

    /**
     * @notice Set the fee token (RTA only)
     * @param newFeeToken Address of the [ERC-20](/EIPS/eip-20) token to use for fees
     * @dev Only callable by RTA to configure or change the fee token
     *      MUST emit FeeTokenUpdated event
     *      MUST NOT accept address(0) - use a stablecoin like USDC
     *      Changing fee token does not affect pending transfer requests
     */
    function setFeeToken(address newFeeToken) external;

    /**
     * @notice Set fee parameters (RTA only)
     * @param feeType Type of fee structure (0: flat, 1: percentage in basis points)
     * @param feeValue Fee amount or percentage basis points
     * @dev Only callable by RTA to update fee structure
     *      MUST emit FeeParametersUpdated event
     *      For percentage fees, feeValue is in basis points (100 = 1%)
     */
    function setFeeParameters(uint8 feeType, uint256 feeValue) external;

    /**
     * @notice Withdraw collected fees (RTA only)
     * @param amount Amount to withdraw (in the configured fee token)
     * @param recipient Recipient address for fees
     * @dev Only callable by RTA to collect accumulated fees
     *      Withdraws from the configured fee token balance
     *      MUST revert if insufficient collected fees
     */
    function withdrawFees(uint256 amount, address recipient) external;

    /**
     * @notice Process pending transfer request (RTA only)
     * @param requestId ID of the transfer request
     * @param approved Whether to approve or reject the transfer
     * @dev RTA reviews and processes transfer requests after compliance checks
     *      MUST transition request through proper lifecycle states
     *      MUST emit events for each state transition
     */
    function processTransferRequest(uint256 requestId, bool approved) external;

    /**
     * @notice Reject transfer request with specific reason code (RTA only)
     * @param requestId ID of the transfer request to reject
     * @param reasonCode Rejection reason code (see Reason Codes section)
     * @param refundFee Whether to refund the fee to the requester
     * @dev Convenience function for rejections with detailed reason tracking
     *      MUST transition request status to Rejected
     *      MUST emit TransferRejected event with reasonCode and refundFee flag
     *      If refundFee is true, MUST return the fee to the original payer
     *      Alternative to processTransferRequest(requestId, false) with more detail
     */
    function rejectTransferRequest(uint256 requestId, uint16 reasonCode, bool refundFee) external;

    // Transfer Request Lifecycle Management

    /**
     * @notice Request lifecycle states
     * @dev Requests MUST follow this state machine:
     *      Requested → UnderReview → (Approved | Rejected) → Executed
     *
     *      State transitions:
     *      - Requested: Initial state when requestTransferWithFee is called
     *      - UnderReview: RTA begins compliance checks (optional intermediate state)
     *      - Approved: RTA approves after compliance checks pass
     *      - Rejected: RTA rejects for compliance or other reasons
     *      - Executed: Transfer completed and tokens moved
     *      - Expired: Request timed out without processing (if timeouts implemented)
     *
     *      Idempotency: Each requestId MUST be unique and can only be executed ONCE
     */
    enum RequestStatus {
        Requested,    // 0: Initial state
        UnderReview,  // 1: RTA is reviewing
        Approved,     // 2: Approved, awaiting execution
        Rejected,     // 3: Rejected, terminal state
        Executed,     // 4: Successfully executed, terminal state
        Expired       // 5: Timed out, terminal state
    }

    /**
     * @notice Get current status of a transfer request (OPTIONAL)
     * @param requestId The transfer request ID
     * @dev OPTIONAL: Implementations MAY instead expose equivalent request data
     *      through other read methods (e.g., a public storage mapping).
     * @return status Current RequestStatus
     * @return from Source address
     * @return to Destination address
     * @return amount Transfer amount
     * @return requestedAt Timestamp when request was created
     * @return processedAt Timestamp when request was processed (0 if pending)
     */
    function getRequestStatus(uint256 requestId) external view returns (
        RequestStatus status,
        address from,
        address to,
        uint256 amount,
        uint256 requestedAt,
        uint256 processedAt
    );

    /**
     * @notice Update request status (RTA only)
     * @param requestId The transfer request ID
     * @param newStatus New status to transition to
     * @dev MUST validate state transitions according to lifecycle rules
     *      MUST emit RequestStatusChanged event
     *      Invalid transitions MUST revert
     */
    function updateRequestStatus(uint256 requestId, RequestStatus newStatus) external;

    // Events for transfer request lifecycle
    event TransferRequested(
        uint256 indexed requestId,
        address indexed from,
        address indexed to,
        uint256 amount,
        uint256 feePaid,
        address requestedBy  // holder or broker
    );

    event RequestStatusChanged(
        uint256 indexed requestId,
        RequestStatus indexed oldStatus,
        RequestStatus indexed newStatus,
        uint256 timestamp
    );

    event TransferExecuted(
        uint256 indexed requestId,
        address indexed from,
        address indexed to,
        uint256 amount
    );

    event TransferRejected(
        uint256 indexed requestId,
        uint16 reasonCode,  // Gas-efficient reason codes (see Reason Codes section)
        bool feeRefunded    // Whether fee was refunded
    );

    event TransferExpired(
        uint256 indexed requestId,
        uint256 expiredAt
    );

    // Fee-related events
    event FeeParametersUpdated(uint8 feeType, uint256 feeValue);
    event FeeTokenUpdated(address indexed previousToken, address indexed newToken);
    event FeesWithdrawn(uint256 amount, address indexed recipient);
    event BrokerStatusUpdated(address indexed broker, bool isApproved, address indexed updatedBy);

    // Account restriction events
    event AccountFrozen(address indexed account, bool frozen, address indexed frozenBy);

    // Reason Codes for Transfer Rejection
    // Gas-efficient uint16 codes instead of strings
    uint16 constant REASON_COMPLIANCE_FAILED = 1;        // KYC/AML check failed
    uint16 constant REASON_INSUFFICIENT_BALANCE = 2;     // Sender lacks tokens
    uint16 constant REASON_RESTRICTED_ACCOUNT = 3;       // Account is frozen/restricted
    uint16 constant REASON_TRANSFER_WINDOW_CLOSED = 4;   // Outside allowed transfer window
    uint16 constant REASON_EXCEEDS_HOLDING_LIMIT = 5;    // Would exceed max holding
    uint16 constant REASON_REGULATORY_HALT = 6;          // Trading halted by regulator
    uint16 constant REASON_COURT_ORDER = 7;              // Blocked by court order
    uint16 constant REASON_INVALID_RECIPIENT = 8;        // Recipient not whitelisted
    uint16 constant REASON_LOCK_PERIOD = 9;              // Tokens are locked
    uint16 constant REASON_RECIPIENT_NOT_VERIFIED = 10;  // Recipient hasn't completed KYC/AML
    uint16 constant REASON_ADDRESS_NOT_LINKED = 11;      // Address not linked to verified identity
    uint16 constant REASON_SENDER_VERIFICATION_EXPIRED = 12; // Sender's KYC expired
    uint16 constant REASON_JURISDICTION_BLOCKED = 13;    // Recipient in restricted jurisdiction
    uint16 constant REASON_ACCREDITATION_REQUIRED = 14;  // Recipient not accredited (Reg D)
    uint16 constant REASON_OTHER = 999;                  // Other/unspecified reason

    // Fee Refund Policy
    /**
     * @notice Fee refund policy for rejected/expired transfers
     * @dev Implementations MUST clearly document their refund policy:
     *      Option 1: AUTO_REFUND - Fees automatically refunded on rejection/expiry
     *      Option 2: NO_REFUND - Fees retained for processing costs
     *      Option 3: CONDITIONAL_REFUND - Refund based on reason code
     *
     *      The refund policy SHOULD be:
     *      - Clearly documented in the contract
     *      - Communicated to users before fee payment
     *      - Consistently applied across all transfers
     *      - Emit TransferRejected event with feeRefunded flag
     */

    // Optional: Off-chain Compliance Pre-check (EIP-3668 CCIP-Read)

    /**
     * @notice Pre-check transfer compliance off-chain (OPTIONAL)
     * @param from Source address for the transfer
     * @param to Destination address for the transfer
     * @param amount Number of tokens to transfer
     * @return bool True if transfer would likely pass compliance
     * @dev OPTIONAL: Implements EIP-3668 (CCIP-Read) for off-chain compliance checks
     *
     *      This check SHOULD verify:
     *      1. Sender KYC/AML status is current (not expired)
     *      2. Recipient has passed KYC/AML verification
     *      3. Recipient address ownership is verified and linked to identity
     *      4. Transfer doesn't violate jurisdiction restrictions
     *      5. Accreditation requirements are met (if applicable for Reg D/Reg A)
     *
     *      This function MAY revert with OffchainLookup error containing:
     *      - URLs for off-chain compliance services
     *      - Callback function to process off-chain response
     *
     *      Purpose: Allow wallets to pre-screen transfers before users pay gas
     *      Benefits:
     *      - Show specific compliance failure reasons upfront
     *      - Improve UX by preventing failed transactions
     *      - Reduce wasted gas on non-compliant transfers
     *
     *      IMPORTANT: This check is ADVISORY ONLY and NOT BINDING
     *      - The actual transfer still requires RTA approval
     *      - Compliance status may change between pre-check and execution
     *      - RTA has final authority on all transfers
     *
     *      Example implementation:
     *      ```solidity
     *      error OffchainLookup(address sender, string[] urls, bytes callData,
     *                          bytes4 callbackFunction, bytes extraData);
     *
     *      function preCheckCompliance(address from, address to, uint256 amount)
     *          external view returns (bool) {
     *          revert OffchainLookup(
     *              address(this),
     *              urls,  // RTA's compliance API endpoints
     *              abi.encodeWithSignature("checkCompliance(address,address,uint256)", from, to, amount),
     *              this.preCheckComplianceCallback.selector,
     *              ""
     *          );
     *      }
     *      ```
     *
     *      Wallets supporting [EIP-3668](/EIPS/eip-3668) will:
     *      1. Catch the OffchainLookup error
     *      2. Query the specified URLs with the provided callData
     *      3. Call the callback function with response and UNMODIFIED extraData
     *      4. Display compliance status to user based on callback result
     *      5. Allow/prevent transfer request submission accordingly
     */
    function preCheckCompliance(address from, address to, uint256 amount)
        external view returns (bool);

    /**
     * @notice Callback for processing off-chain compliance response (OPTIONAL)
     * @param response Encoded response from off-chain compliance service
     * @param extraData Additional data from original request (passed through unmodified)
     * @return bool Compliance check result
     * @dev Only called by wallets supporting EIP-3668
     *      Validates and interprets off-chain compliance service response
     *
     *      Per [EIP-3668](/EIPS/eip-3668) specification:
     *      - Clients MUST pass extraData unmodified from the OffchainLookup error
     *      - The callback signature MUST match EIP-3668's standard format
     *      - This enables stateless operation and future extensibility
     *
     *      Example client implementation:
     *      1. Catch OffchainLookup(sender, urls, callData, callbackFunction, extraData)
     *      2. Query off-chain service with callData
     *      3. Call callbackFunction(response, extraData) with UNMODIFIED extraData
     */
    function preCheckComplianceCallback(bytes calldata response, bytes calldata extraData)
        external pure returns (bool);

    // ============ ERC-1643 Document Management Interface (OPTIONAL) ============
    // Implementations MAY support on-chain anchoring of document references.
    // RTAs already maintain authoritative books and records off-chain per their
    // regulatory obligations; on-chain anchoring is an optional transparency
    // enhancement, not a compliance requirement.

    /**
     * @notice Set a document for the token (RTA only) (OPTIONAL)
     * @param _name Document name (unique identifier)
     * @param _uri Document location (IPFS hash or HTTPS URL)
     * @param _documentHash Hash of the document for verification
     * @dev Part of ERC-1643 standard. Only callable by RTA.
     *      Used for storing references to legal documents, compliance certificates,
     *      court orders, recovery evidence, physical addresses, etc.
     *      Never store PII directly on-chain - use document URIs and hashes only.
     *
     *      Common document names:
     *      - "PHYSICAL_ADDRESS": Issuer's registered address
     *      - "PROSPECTUS": Offering documents
     *      - "COURT_ORDER": Legal judgments
     *      - "RECOVERY_EVIDENCE": Lost wallet documentation
     *
     *      Implementations providing this function MUST emit DocumentUpdated.
     */
    function setDocument(
        bytes32 _name,
        string calldata _uri,
        bytes32 _documentHash
    ) external;

    /**
     * @notice Get a specific document's details (OPTIONAL)
     * @param _name Document name to retrieve
     * @return documentUri Document location
     * @return documentHash Document hash for verification
     * @return timestamp When document was last updated
     * @dev Part of ERC-1643 standard. Publicly accessible.
     */
    function getDocument(bytes32 _name)
        external view
        returns (
            string memory documentUri,
            bytes32 documentHash,
            uint256 timestamp
        );

    /**
     * @notice Remove a document (RTA only) (OPTIONAL)
     * @param _name Document name to remove
     * @dev Part of ERC-1643 standard. Only callable by RTA.
     *      Implementations providing this function MUST emit DocumentRemoved.
     */
    function removeDocument(bytes32 _name) external;

    /**
     * @notice Get all document names (OPTIONAL)
     * @return Array of all document names that have been set
     * @dev Part of ERC-1643 standard. Publicly accessible.
     *      Allows discovery of all documents associated with the token.
     */
    function getAllDocuments() external view returns (bytes32[] memory);

    // ============ Recovery Workflow for Lost/Compromised Wallets (OPTIONAL) ============
    // Uses ERC-1643 for document management and aligns with ERC-1644 for controller operations.
    // OPTIONAL: This structured, time-locked workflow is an extension. The REQUIRED
    // baseline for recovery is controllerTransfer — the RTA verifies the investor's
    // identity through its existing off-chain KYC records and executes the transfer.
    // The structured workflow adds public evidence anchoring and a dispute window
    // for deployments that want on-chain transparency of recovery operations.

    /**
     * @notice Initiate recovery process for lost wallet (RTA only) (OPTIONAL)
     * @param lostWallet Address that has lost access
     * @param newWallet Proposed replacement address
     * @param documentName Name/type of the supporting document (ERC-1643 compatible)
     * @param uri URI pointing to the evidence document (IPFS/HTTPS)
     * @param documentHash Hash of the document for integrity verification
     * @return recoveryId Unique identifier for the recovery request
     * @dev Creates a time-locked recovery request requiring multi-step verification:
     *      1. Identity verification of the claiming party
     *      2. Proof of ownership (off-chain documentation)
     *      3. Time delay for potential disputes (e.g., 30 days)
     *      4. Final execution after time lock expires
     *
     *      Following ERC-1643 document management standards:
     *      - documentName: Type of evidence (e.g., "RECOVERY_AFFIDAVIT", "DEATH_CERTIFICATE")
     *      - uri: Link to encrypted document storage (never store PII on-chain)
     *      - documentHash: Cryptographic hash for document integrity
     *
     *      Implementations providing this function MUST emit DocumentUpdated
     *      per ERC-1643 when evidence is submitted
     */
    function initiateRecovery(
        address lostWallet,
        address newWallet,
        bytes32 documentName,
        string calldata uri,
        bytes32 documentHash
    ) external returns (uint256 recoveryId);

    /**
     * @notice Cancel a pending recovery request (RTA only) (OPTIONAL)
     * @param recoveryId The recovery request to cancel
     * @dev Can be called if:
     *      - Original wallet owner proves they still have access
     *      - Evidence is found to be fraudulent
     *      - Court order requires cancellation
     */
    function cancelRecovery(uint256 recoveryId) external;

    /**
     * @notice Execute recovery after time lock expires (RTA only) (OPTIONAL)
     * @param recoveryId The recovery request to execute
     * @dev Transfers all tokens from lost wallet to new wallet
     *      Can only be executed after time lock period (e.g., 30 days)
     *      Implementations providing this function MUST emit ControllerTransfer
     *      per ERC-1644
     */
    function executeRecovery(uint256 recoveryId) external;

    /**
     * @notice Controller transfer for court orders (RTA only) - ERC-1644 compatible
     * @param from Source address
     * @param to Destination address
     * @param amount Number of tokens
     * @param data Encoded data containing document references
     * @param operatorData Encoded document information per ERC-1643:
     *        - documentName: Type (e.g., "COURT_ORDER", "REGULATORY_ACTION")
     *        - uri: Link to encrypted document storage
     *        - documentHash: Cryptographic hash for integrity
     * @dev Immediate transfer without time lock for:
     *      - Court-ordered transfers (divorce, judgments)
     *      - Regulatory enforcement actions
     *      - Estate distributions with proper documentation
     *
     *      Following ERC-1644 controller operation standards:
     *      - MUST emit ControllerTransfer event
     *      - Uses standard function name for tooling compatibility
     *
     *      Following ERC-1643 document management:
     *      - MUST emit DocumentUpdated event when court order is attached
     *      - Never store PII on-chain, only document URIs and hashes
     */
    function controllerTransfer(
        address from,
        address to,
        uint256 amount,
        bytes calldata data,
        bytes calldata operatorData
    ) external;

    // ============ Account Freezing ============

    /**
     * @notice Freeze or unfreeze an account (RTA only)
     * @param account Address to freeze/unfreeze
     * @param frozen True to freeze, false to unfreeze
     * @dev Frozen accounts cannot send or receive tokens
     *      Used for compliance holds, regulatory actions, or suspicious activity
     *      Only RTA can freeze/unfreeze accounts
     *      MUST emit AccountFrozen event
     */
    function setAccountFrozen(address account, bool frozen) external;

    /**
     * @notice Check if an account is frozen
     * @param account Address to check
     * @return bool True if the account is frozen
     * @dev Publicly accessible for transparency
     *      Wallets and exchanges can check before attempting transfers
     */
    function isAccountFrozen(address account) external view returns (bool);

    // ============ Recovery System (OPTIONAL) ============

    /**
     * @notice Get recovery request details (OPTIONAL)
     * @param recoveryId The recovery request ID
     * @return lostWallet The wallet being recovered
     * @return newWallet The replacement wallet
     * @return documentName The type of evidence document (ERC-1643)
     * @return documentUri The URI of the evidence document
     * @return documentHash The hash of the evidence document
     * @return initiatedAt Timestamp when recovery was initiated
     * @return status Current status (pending/executed/cancelled)
     */
    function getRecoveryDetails(uint256 recoveryId)
        external view returns (
            address lostWallet,
            address newWallet,
            bytes32 documentName,
            string memory documentUri,
            bytes32 documentHash,
            uint256 initiatedAt,
            uint8 status
        );

    /**
     * @notice Check if a wallet has a pending recovery
     * @param wallet Address to check
     * @return bool True if wallet has pending recovery
     * @return uint256 Recovery ID if exists, 0 otherwise
     */
    function hasPendingRecovery(address wallet)
        external view returns (bool, uint256);

    // Standard Events from ERC-1644 (Controller Operations)
    event ControllerTransfer(
        address indexed controller,
        address indexed from,
        address indexed to,
        uint256 value,
        bytes data,
        bytes operatorData
    );

    event ControllerRedemption(
        address indexed controller,
        address indexed tokenHolder,
        uint256 value,
        bytes data,
        bytes operatorData
    );

    // ERC-1643 Standard Events (Document Management — OPTIONAL, required if
    // the document management extension is implemented)
    event DocumentUpdated(
        bytes32 indexed _name,
        string _uri,
        bytes32 _documentHash
    );
    event DocumentRemoved(
        bytes32 indexed _name,
        string _uri,
        bytes32 _documentHash
    );

    // Recovery-specific Events (OPTIONAL, required if the recovery workflow
    // extension is implemented)
    event RecoveryInitiated(
        uint256 indexed recoveryId,
        address indexed lostWallet,
        address indexed newWallet,
        uint256 timelock
    );
    event RecoveryCancelled(uint256 indexed recoveryId, address cancelledBy);
    // RecoveryExecuted is replaced by ControllerTransfer event per ERC-1644
}

Interface Detection

The IERC1450 interface ID is calculated by XOR’ing the function selectors of all functions unique to the IERC1450 interface (excluding inherited ERC-20 functions):

// IERC1450 unique functions (not in ERC-20):
bytes4 constant private CHANGEISSUER = bytes4(keccak256("changeIssuer(address)"));
bytes4 constant private SETTRANSFERAGENT = bytes4(keccak256("setTransferAgent(address)"));
bytes4 constant private ISTRANSFERAGENT = bytes4(keccak256("isTransferAgent(address)"));
bytes4 constant private ISSECURITYTOKEN = bytes4(keccak256("isSecurityToken()"));
bytes4 constant private MINT = bytes4(keccak256("mint(address,uint256,uint16,uint256)"));
bytes4 constant private BURNFROM = bytes4(keccak256("burnFrom(address,uint256)"));
bytes4 constant private BURNFROMREGULATION = bytes4(keccak256("burnFromRegulation(address,uint256,uint16)"));
bytes4 constant private GETHOLDERREGULATIONS = bytes4(keccak256("getHolderRegulations(address)"));
bytes4 constant private GETREGULATIONSUPPLY = bytes4(keccak256("getRegulationSupply(uint16)"));
// ... additional IERC1450-specific functions

// The computed interface ID:
bytes4 constant public IERC1450_INTERFACE_ID = CHANGEISSUER ^ SETTRANSFERAGENT ^ ISTRANSFERAGENT ^ ISSECURITYTOKEN ^ MINT ^ BURNFROM ^ BURNFROMREGULATION ^ GETHOLDERREGULATIONS ^ GETREGULATIONSUPPLY /* ^ ... */;
// Actual value from reference implementation:
bytes4 constant public IERC1450_INTERFACE_ID = 0xaf175dee;

Important Notes on Interface Detection:

Implementations MUST return true from supportsInterface(0x01ffc9a7) for ERC-165 itself
Implementations MUST return true from supportsInterface(0xaf175dee) for IERC1450
Implementations SHOULD return true from supportsInterface(type(IERC20Metadata).interfaceId) for token metadata (name(), symbol(), decimals())
Implementations MUST NOT return true from supportsInterface(0x36372b07) for ERC-20

Why NOT Support ERC-20 Interface ID: While ERC-1450 is ABI-compatible with ERC-20 (same function signatures for view functions), returning true for the ERC-20 interface ID (0x36372b07) would be misleading:

Wallets would assume they can call transfer() and approve() normally
These functions always revert in ERC-1450, breaking user expectations
Better to force explicit detection of IERC1450 to ensure proper UI/UX
Returning true for IERC20Metadata is acceptable since name(), symbol(), and decimals() work normally

RTA Proxy Pattern (REQUIRED Security Enhancement)

To prevent security vulnerabilities where a compromised issuer could change the RTA and steal tokens, ERC-1450 implementations MUST use an RTA Proxy pattern. The reference implementation uses a generic multi-signature wallet that provides maximum flexibility while maintaining security:

/**
 * @title RTAProxy
 * @notice Multi-signature proxy contract for RTA operations
 * @dev Deployed once and set as the permanent transferAgent in ERC-1450 tokens
 *
 * The RTAProxy pattern provides:
 * - Protection against single key compromise via M-of-N multi-signature
 * - Generic operation execution (can call any function on any target)
 * - Signer management through multi-sig consensus
 * - Complete audit trail of all RTA actions
 *
 * SECURITY REQUIREMENTS:
 * - MUST use multiple signers (recommended: 2-of-3 or 3-of-5)
 * - Signers SHOULD use hardware wallets or institutional custody
 * - All operations MUST emit events for audit trail
 */
interface IRTAProxy {
    // ============ Events ============

    event SignerAdded(address indexed signer);
    event SignerRemoved(address indexed signer);
    event RequiredSignaturesUpdated(uint256 oldRequired, uint256 newRequired);
    event OperationSubmitted(uint256 indexed operationId, address indexed submitter);
    event OperationConfirmed(uint256 indexed operationId, address indexed signer);
    event OperationExecuted(uint256 indexed operationId);
    event OperationRevoked(uint256 indexed operationId, address indexed signer);

    // ============ Errors ============

    error NotASigner();
    error AlreadyASigner();
    error AlreadyConfirmed();
    error NotConfirmed();
    error InsufficientConfirmations();
    error OperationAlreadyExecuted();
    error InvalidSignerCount();

    // ============ Multi-Sig Operations ============

    /**
     * @notice Submit a new operation for multi-sig approval
     * @param target The contract to call (e.g., ERC-1450 token address)
     * @param data The encoded function call (e.g., abi.encodeWithSignature("mint(...)"))
     * @param value ETH value to send (usually 0)
     * @return operationId The ID of the submitted operation
     * @dev Submitter automatically confirms the operation
     *      Operation auto-executes if submitter's confirmation meets threshold
     */
    function submitOperation(
        address target,
        bytes memory data,
        uint256 value
    ) external returns (uint256 operationId);

    /**
     * @notice Confirm a pending operation
     * @param operationId The operation to confirm
     * @dev Auto-executes when confirmation threshold is met
     */
    function confirmOperation(uint256 operationId) external;

    /**
     * @notice Revoke a previously given confirmation
     * @param operationId The operation to revoke confirmation from
     */
    function revokeConfirmation(uint256 operationId) external;

    /**
     * @notice Manually execute an operation that has enough confirmations
     * @param operationId The operation to execute
     */
    function executeOperation(uint256 operationId) external;

    // ============ Signer Management (via multi-sig) ============

    /**
     * @notice Add a new signer (requires multi-sig approval)
     * @param signer Address of the new signer
     * @dev MUST be called through submitOperation (msg.sender == address(this))
     */
    function addSigner(address signer) external;

    /**
     * @notice Remove a signer (requires multi-sig approval)
     * @param signer Address of the signer to remove
     * @dev MUST be called through submitOperation
     *      MUST NOT reduce signers below requiredSignatures
     */
    function removeSigner(address signer) external;

    /**
     * @notice Update required signature threshold (requires multi-sig approval)
     * @param newRequiredSignatures New threshold
     * @dev MUST be called through submitOperation
     *      MUST be > 0 and <= signers.length
     */
    function updateRequiredSignatures(uint256 newRequiredSignatures) external;

    // ============ View Functions ============

    /**
     * @notice Get the list of current signers
     * @return Array of signer addresses
     */
    function getSigners() external view returns (address[] memory);

    /**
     * @notice Check if an address has confirmed an operation
     * @param operationId The operation ID
     * @param signer The signer address
     * @return bool True if the signer has confirmed
     */
    function hasConfirmed(uint256 operationId, address signer) external view returns (bool);

    /**
     * @notice Get operation details
     * @param operationId The operation ID
     * @return target The target contract
     * @return data The encoded function call
     * @return value The ETH value
     * @return confirmations Number of confirmations
     * @return executed Whether the operation has been executed
     * @return timestamp When the operation was submitted
     */
    function getOperation(uint256 operationId) external view returns (
        address target,
        bytes memory data,
        uint256 value,
        uint256 confirmations,
        bool executed,
        uint256 timestamp
    );

    /**
     * @notice Returns the contract implementation version
     * @return string Semantic version string (e.g., "1.13.0")
     */
    function version() external pure returns (string memory);
}

Security Benefits:

Single Key Protection: M-of-N multi-sig prevents any single compromised key from executing operations
Issuer Protection: Once RTAProxy is set as transferAgent, the issuer cannot unilaterally change it
Flexible Operations: Generic submitOperation can call any function on any target contract
Signer Management: Add/remove signers and adjust thresholds through multi-sig consensus
Audit Trail: All operations are logged on-chain via events
Revocation: Signers can revoke confirmations before execution if needed

Implementation Flow (REQUIRED):

Deploy RTAProxy with initial signers and threshold (e.g., 3 signers, 2-of-3)
Deploy ERC-1450 token with transferAgent = RTAProxy address
Token's setTransferAgent is locked after RTAProxy is set
RTA operations flow: Signer → submitOperation → confirmOperation → auto-execute
Signer changes require multi-sig approval through submitOperation
All operations emit events for regulatory audit trail

Example: Minting Tokens via Multi-Sig

// Signer 1 submits mint operation
bytes memory mintData = abi.encodeWithSignature(
    "mint(address,uint256,uint16,uint256)",
    investor,
    1000,
    0x0006,  // REG_US_CF
    block.timestamp
);
uint256 opId = rtaProxy.submitOperation(tokenAddress, mintData, 0);

// Signer 2 confirms (auto-executes if 2-of-3)
rtaProxy.confirmOperation(opId);

RTA Provider Change Process:

When an issuer legitimately needs to change RTA providers:
Issuer contracts with new RTA provider
Current RTA validates the change request (legal docs, verification)
Current RTA transfers records to new RTA
Current RTA adds new RTA signers via multi-sig: submitOperation(addSigner(newSigner))
Current RTA removes old signers via multi-sig: submitOperation(removeSigner(oldSigner))
New RTA now controls all token operations
Process is logged on-chain for regulatory compliance

This cooperative process ensures:

No unauthorized RTA changes (protects against key compromise)
Legitimate business changes are possible (with proper verification)
Similar to domain registrar transfers - requires current provider cooperation
Creates audit trail for regulators

Broker Registration Pattern (RECOMMENDED)

While the RTAProxy pattern is REQUIRED for RTA security, a similar BrokerProxy pattern is RECOMMENDED but not required for registered brokers. This provides operational security and key management flexibility for professional broker-dealers.

Benefits of BrokerProxy:

Secure key rotation without re-registration with the RTA
Multi-signature controls for trader operations
Business continuity during personnel changes
Institutional custody integration (Fireblocks, Coinbase Custody, etc.)
Protection against individual key compromise

Implementation Options:

Option 1: Direct Registration (Simple)

RTA → registers → Broker EOA/Multisig

Suitable for: Individual brokers, small operations, testing
Risk: Key compromise affects all broker operations
Simplicity: No additional contract deployment needed

Option 2: Proxy Pattern (Recommended for Production)

RTA → registers → BrokerProxy → controls → Operator Multisig

Suitable for: Professional broker-dealers, high-volume operations
Benefits: Key rotation, multi-trader support, institutional security
Complexity: Requires additional proxy contract deployment

Example BrokerProxy Interface:

/**
 * @title IBrokerProxy
 * @notice Optional proxy pattern for registered brokers
 * @dev While not required like RTAProxy, this pattern is RECOMMENDED for:
 *      - Professional broker-dealers with multiple traders
 *      - High-volume brokers needing key rotation
 *      - Brokers using institutional custody solutions
 */
interface IBrokerProxy {
    // Events
    event OperatorRotated(address indexed previousOperator, address indexed newOperator);
    event RequestSubmitted(uint256 indexed requestId, address from, address to, uint256 amount);

    /**
     * @notice Submit transfer request on behalf of client
     * @dev Only callable by authorized operators of this broker
     */
    function submitTransferRequest(
        address token,
        address from,
        address to,
        uint256 amount,
        address feeToken,
        uint256 feeAmount
    ) external payable returns (uint256 requestId);

    /**
     * @notice Rotate broker operator (multi-sig required)
     * @param newOperator New operator address (should be multi-sig)
     */
    function rotateOperator(address newOperator) external;

    /**
     * @notice Check if address is authorized operator
     */
    function isOperator(address account) external view returns (bool);
}

Why Not REQUIRE BrokerProxy?

Unlike the RTA which has ultimate control over all tokens, brokers have limited authority:

Lower Risk: Brokers can only request transfers, not execute them
Business Variety: Some brokers are individuals, not institutions
Market Flexibility: Let brokers choose security appropriate to their needs
Gradual Adoption: Brokers can upgrade to proxy pattern as they grow

The RTA treats both patterns equally - registration is by address whether direct or proxy. The RTA maintains the right to revoke any broker registration at any time, ensuring ultimate control regardless of the broker’s implementation choice.

Fee System Implementation

The fee system allows RTAs to charge for transfer processing using a single configured fee token (typically a stablecoin like USDC):

Querying the Fee Token and Amount

// Get the configured fee token
address feeToken = token.getFeeToken();
// Returns: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 (USDC on mainnet)

// Get the fee amount for a transfer
uint256 feeAmount = token.getTransferFee(from, to, amount);
// Returns: 10000000 (10 USDC with 6 decimals) for flat fee
// OR calculated percentage for percentage-based fees

Frontend Implementation Pattern

// Get the fee token and amount
const feeToken = await token.getFeeToken();
const feeAmount = await token.getTransferFee(from, to, amount);

// Get token info for display
const tokenInfo = await getTokenInfo(feeToken);
const formattedFee = formatUnits(feeAmount, tokenInfo.decimals);

// Display to user: "Transfer fee: 10.00 USDC"
console.log(`Transfer fee: ${formattedFee} ${tokenInfo.symbol}`);

// Ensure user has approved fee token spending
await feeTokenContract.approve(token.address, feeAmount);

// Submit transfer request with fee
const requestId = await token.requestTransferWithFee(from, to, amount, feeAmount);

RTA Fee Configuration

RTAs configure the fee system through two functions:

// Set the fee token (typically USDC or another stablecoin)
token.setFeeToken(USDC_ADDRESS);

// Set fee parameters
// Type 0: Flat fee (feeValue is the exact amount in fee token units)
token.setFeeParameters(0, 10000000); // 10 USDC flat fee

// Type 1: Percentage fee (feeValue is basis points, 100 = 1%)
token.setFeeParameters(1, 50); // 0.5% fee

Implementation Requirements for Regulated Securities

This standard requires implementers to maintain off-chain services and databases that record and track investor information including names, physical addresses, Ethereum addresses, and security ownership amounts. Before associating any Ethereum address with an investor’s identity, implementers MUST verify ownership of that address through cryptographic proof (such as message signing), micro-deposits, or other secure verification methods to prevent fraudulent claims.

The designated transfer agent must be able to produce current lists of all investors, including their identities and security ownership levels at any given moment. The system must support re-issuance of securities to investors for various operational and regulatory reasons.

Private investor information must never be publicly exposed on a public blockchain.

KYC/AML Requirements

Per SEC regulations and the Bank Secrecy Act, the RTA MUST ensure:

Identity Verification: Every address holding tokens MUST be associated with a verified natural or legal person who has passed KYC/AML checks
Address Ownership Proof: Before any transfer, the RTA MUST verify that the recipient address is controlled by a verified person (via signature, micro-deposit, or other secure method)
Ongoing Monitoring: The RTA MUST maintain current KYC/AML status and may freeze accounts that fail periodic reviews
No Anonymous Holdings: Unlike permissionless tokens, ERC-1450 tokens CANNOT be held by anonymous or unverified addresses

The RTA enforces these requirements through:

transferFrom: RTA only executes after verifying both parties
requestTransferWithFee: RTA rejects requests to unverified addresses with appropriate reason codes (10-14)
mint: RTA only mints to verified addresses
Recovery mechanisms: Require identity verification before execution

Transfer rejections for KYC/AML failures use specific reason codes:

REASON_RECIPIENT_NOT_VERIFIED (10): Recipient hasn’t completed KYC/AML
REASON_ADDRESS_NOT_LINKED (11): Address not linked to verified identity
REASON_SENDER_VERIFICATION_EXPIRED (12): Sender’s KYC expired
REASON_JURISDICTION_BLOCKED (13): Recipient in restricted jurisdiction
REASON_ACCREDITATION_REQUIRED (14): Recipient not accredited (for Reg D offerings)

Managing Investor Information

Special care and attention must be taken to ensure that the personally identifiable information of Investors is never exposed or revealed to the public.

Issuers who lost access to their address or private keys

With the RTA Proxy pattern implemented in ERC-1450, the impact of an Issuer losing access to their private key is significantly mitigated. Once the RTA is established (especially via RTAProxy), the RTA maintains exclusive control over critical operations including changeIssuer, mint, burn, and transferFrom. Even if the Issuer loses their private key or becomes compromised, the RTA can:

Continue all token operations without issuer involvement
Transfer ownership to a new issuer address through changeIssuer
Protect token holders from any issuer-side security failures
Maintain full regulatory compliance and operations

This design ensures that securities tokens remain operational and secure regardless of issuer key management issues. The RTA acts as the security backstop, preventing any single point of failure from disrupting the securities’ operations or endangering investor assets.

If the Issuer loses access, the Issuer’s securities must be rebuilt using off-chain services. The Issuer must create (and secure) a new address. The RTA can read the existing Issuer securities, and the RTA can mint Investor securities accordingly under a new ERC-1450 smart contract.

Registered Transfer Agents who lost access to their address or private keys

Professional RTAs MUST implement enterprise-grade key management solutions to prevent key loss scenarios. This includes:

Multi-signature wallets requiring multiple parties to approve transactions
Hardware Security Modules (HSMs) for key storage
Multi-Party Computation (MPC) solutions like Fireblocks or similar institutional custody
Geographically distributed key shards
Regular key rotation and backup procedures

With proper security infrastructure, RTA key loss should be virtually impossible. However, if catastrophic failure occurs:

With RTAProxy pattern: The proxy contract can facilitate controlled RTA rotation with proper authorization
Without RTAProxy: The Issuer can execute setTransferAgent to assign a new RTA address (if the issuer still has access)
Last resort: Securities must be reissued on a new contract with proper verification of all holdings

The use of professional custody solutions by RTAs is not optional but essential for maintaining the security and reliability required for managing securities.

Handling Investors (security owners) who lost access to their addresses or private keys

Common Business Model - RTA Omnibus Custody: Many RTAs maintain securities in omnibus accounts with off-chain record keeping of individual investor holdings. This business model (not a protocol requirement) offers several advantages:

Most investors never need to manage private keys
Internal transfers occur off-chain in databases
Securities only transfer to investor wallets upon explicit, verified request
Investor key loss doesn’t affect their holdings in the omnibus account

Note: This is a business implementation choice, not enforced by the protocol itself.

Self-Custody Scenario: For investors who choose to hold securities in their own wallets, loss of credentials may occur due to: lost private keys, hacking, fraud, or life events (death, incapacitation). In these cases:

If an Investor (or their legal representative) loses wallet access, they must go through a verified process with the RTA including:

Identity verification matching original KYC records
Notarized affidavit of lost access
Waiting period for potential disputes (as specified in recovery mechanism)
Supply and verify ownership of new wallet address

Upon successful verification, the RTA can use the recovery mechanism to transfer securities from the lost wallet to the new verified wallet, maintaining full audit trail for regulatory compliance.

Note: The omnibus custody model described above is a common business practice that provides professional security while maintaining investor flexibility to withdraw to self-custody when desired. This is an implementation choice, not a protocol requirement.

Regulation Tracking Implementation (Non-Normative)

This section provides guidance for implementing regulation tracking in ERC-1450 tokens. Since securities must be issued under specific regulatory frameworks, implementations need to track which regulation applies to each token holder’s shares for proper compliance enforcement.

Regulation Type Encoding

Implementations SHOULD use a uint16 value to encode regulation types, allowing for global regulatory frameworks. A suggested encoding pattern uses the high byte for country/region and the low byte for specific regulations:

// Example encoding (not part of the standard, implementations may vary):
// Format: 0xCCRR where CC = country code, RR = regulation code

// US Regulations (0x00XX)
uint16 constant REG_US_S1 = 0x0001;           // S-1 Registration (IPO)
uint16 constant REG_US_D_504 = 0x0002;        // Regulation D Rule 504 ($10M)
uint16 constant REG_US_A_TIER_1 = 0x0004;     // Regulation A Tier I ($20M)
uint16 constant REG_US_A_TIER_2 = 0x0005;     // Regulation A Tier II ($75M)
uint16 constant REG_US_CF = 0x0006;           // Regulation Crowdfunding ($5M)
uint16 constant REG_US_D_506B = 0x0007;       // Regulation D 506(b) (no general solicitation)
uint16 constant REG_US_D_506C = 0x0008;       // Regulation D 506(c) (accredited only)
uint16 constant REG_US_S = 0x0009;            // Regulation S (offshore offerings)

// EU Regulations (0x01XX)
uint16 constant REG_EU_PROSPECTUS = 0x0101;   // EU Prospectus Regulation

// Canadian Regulations (0x02XX)
uint16 constant REG_CA_OM = 0x0201;           // Offering Memorandum

Storage Pattern

Implementations MUST store regulation data on-chain to enable the RTA to enforce compliance. A recommended storage pattern:

struct TokenBatch {
    uint256 amount;
    uint16 regulationType;
    uint256 issuanceDate;  // Original share issuance, not tokenization
}

mapping(address => TokenBatch[]) private holderBatches;

Compliance Checking

When processing transfer requests, the RTA queries the regulation data to apply appropriate restrictions:

Time-based restrictions: Calculate currentTime - issuanceDate to determine if holding periods have expired
Investor restrictions: Check if recipient meets requirements (e.g., accreditation for Reg D)
Geographic restrictions: Verify jurisdiction compliance for regulations like Reg S

Example: Reg CF Maturation

Regulation Crowdfunding shares have a 12-month resale restriction that expires over time:

// At mint time (tokenizing shares from March 2023 offering)
mint(investor, 1000, 0x0006, 1677628800); // REG_US_CF, March 1, 2023

// Transfer request in November 2024
// RTA calculates: Nov 2024 - March 2023 = 20 months (> 12 months)
// Result: Shares have matured, transfer allowed to any eligible investor

// Transfer request if it had been May 2023
// RTA calculates: May 2023 - March 2023 = 2 months (< 12 months)
// Result: Transfer blocked with REASON_LOCK_PERIOD

RTA Transfer Strategy Flexibility

The RTA has complete control over which token batches to transfer or burn. The blockchain stores raw batch data, while the RTA implements the optimal strategy for each situation:

Transfer Strategy Options:

// Holder has:
// - 100 tokens: Reg CF, issued March 2023
// - 200 tokens: Reg D, issued June 2023
// - 50 tokens: Reg A, issued September 2023

// Transfer request for 150 tokens - RTA chooses strategy:
// Option A (FIFO): transferFromRegulated(..., 100, REG_CF, March2023)
//                  transferFromRegulated(..., 50, REG_D, June2023)
// Option B (LIFO): transferFromRegulated(..., 50, REG_A, Sept2023)
//                  transferFromRegulated(..., 100, REG_D, June2023)
// Option C (Tax Optimized): Transfer specific lots for best tax outcome
// Option D (Regulatory): Transfer only matured/unrestricted batches

Burn Strategy Options:

// Using burnFrom(address, amount) - RTA determines strategy
// Using burnFromRegulated(address, amount, regulation, date) - Precise control
// Using burnFromRegulation(address, amount, regulation) - Regulation-specific

// RTA can optimize based on:
// - Tax implications (short vs long-term gains)
// - Regulatory maturity (expired lockups first)
// - Holder preferences (specific lot selection)
// - Corporate actions (specific share class redemption)

This flexibility ensures:

Tax optimization for holders
Regulatory compliance per jurisdiction
Support for various accounting methods
Adaptability to changing requirements

Corporate Actions (Non-Normative)

This section describes recommended patterns for implementing common corporate actions in ERC-1450 tokens. These patterns demonstrate operational completeness while maintaining the core security and compliance model.

Stock Splits and Reverse Splits

For stock splits (e.g., 2-for-1) or reverse splits (e.g., 1-for-10), the RTA executes proportional adjustments:

// 2-for-1 split implementation pattern
function executeSplit(uint256 splitRatio) external onlyRTA {
    address[] memory holders = getAllHolders(); // Off-chain tracked
    for (uint i = 0; i < holders.length; i++) {
        uint256 currentBalance = balanceOf(holders[i]);
        uint256 additionalShares = currentBalance * (splitRatio - 1);

        // Mint additional shares
        _mint(holders[i], additionalShares);
        // Emit canonical events for indexers
        emit Transfer(address(0), holders[i], additionalShares);
    }
}

Key Implementation Points:

RTA executes atomically across all holders
Uses canonical Transfer(0x0, holder, amount) events for mints
For reverse splits, use _burn with Transfer(holder, 0x0, amount) events
Maintain audit trail with split ratio and execution timestamp

Dividends and Distributions

Dividend payments typically use stablecoin distributions based on a record date snapshot:

Option 1: Off-Chain Distribution List

// RTA takes snapshot at record date
mapping(address => uint256) recordDateBalances;

// Off-chain: Calculate pro-rata distributions
// Execute stablecoin transfers via separate contract or traditional rails

Option 2: On-Chain Claim Contract

contract DividendClaim {
    IERC20 public paymentToken; // e.g., USDC
    mapping(address => uint256) public claimableAmounts;
    uint256 public recordDate;

    function claim() external {
        require(rtaContract.isKYCVerified(msg.sender), "KYC required");
        uint256 amount = claimableAmounts[msg.sender];
        claimableAmounts[msg.sender] = 0;
        paymentToken.transfer(msg.sender, amount);
    }
}

Implementation Notes:

Record date snapshot determines eligible holders
Payment in stablecoins (USDC, USDT) or native tokens (ETH, MATIC)
Tax withholding handled off-chain per jurisdiction
RTA maintains distribution records for tax reporting

Mandatory Redemptions and Calls

For mandatory redemptions (e.g., bond calls, forced buybacks), use Controller Token Operation Standard (1644) semantics:

function executeMandatoryRedemption(
    address holder,
    uint256 amount,
    uint256 pricePerShare,
    string calldata reason
) external onlyRTA {
    // Force transfer to redemption pool
    _transferFrom(holder, redemptionPool, amount);

    // Record redemption terms
    emit Redemption(holder, amount, pricePerShare, reason);

    // Payment handled via separate mechanism
    // (stablecoin transfer, wire, check)
}

Compliance Requirements:

Follow Document Management Standard (1643) for notices and terms
Provide advance notice per security agreements (typically 30-60 days)
Maintain redemption price and payment terms on-chain or via Document Management Standard
Support partial redemptions for pro-rata calls

Tender Offers

Voluntary tender offers allow investors to optionally sell shares:

contract TenderOffer {
    uint256 public offerPrice;
    uint256 public offerExpiry;
    address public offeror;

    function acceptOffer(uint256 amount) external {
        require(block.timestamp < offerExpiry, "Offer expired");
        require(rtaContract.isKYCVerified(msg.sender), "KYC required");

        // Transfer shares to offeror
        token.requestTransferWithFee(msg.sender, offeror, amount, fee);

        // Payment handled separately
        emit OfferAccepted(msg.sender, amount, offerPrice);
    }
}

Mergers and Acquisitions

For mergers requiring token swaps:

contract MergerExchange {
    IERC1450 public oldToken;
    IERC1450 public newToken;
    uint256 public exchangeRatio; // e.g., 100 = 1:1, 150 = 1.5:1

    function exchangeTokens(uint256 amount) external {
        require(rtaContract.isKYCVerified(msg.sender), "KYC required");

        // Burn old tokens
        oldToken.requestTransferWithFee(msg.sender, address(0), amount, 0);

        // Mint new tokens at exchange ratio
        uint256 newAmount = (amount * exchangeRatio) / 100;
        newToken.mint(msg.sender, newAmount);
    }
}

Implementation Considerations

Event Standardization: Use canonical Transfer events for all balance changes to ensure indexer compatibility
Record Dates: Snapshot mechanisms must account for pending transfers and corporate action timelines
Payment Rails: Dividend and redemption payments typically use stablecoins or traditional banking
Regulatory Notices: Use Document Management Standard (1643) for required disclosures
Tax Compliance: Off-chain systems handle withholding and reporting requirements
Audit Trail: All corporate actions must maintain complete records for regulatory review

These patterns demonstrate that ERC-1450 can handle the complete lifecycle of security token operations while maintaining regulatory compliance and investor protections. The RTA’s exclusive control ensures all corporate actions are executed properly with appropriate verification and documentation.

Record Dates and Voting Mechanics (Non-Normative)

Securities require record dates for corporate actions, proxy voting, and shareholder meetings. This section provides guidance on implementing these features without complicating the core token standard.

Record Date Snapshots

Record dates determine which shareholders are eligible for dividends, voting, or other corporate actions. Rather than building snapshots into the token itself, we recommend:

Option 1: Off-Chain Snapshots (Recommended)

// RTA maintains historical balances in database
// Query: SELECT balance FROM holdings WHERE address = ? AND timestamp <= ?
// This provides complete flexibility without on-chain gas costs

Option 2: External Snapshot Contract

// Use existing snapshot solutions like OpenZeppelin's ERC20Snapshot
// or deploy a separate SnapshotManager contract
interface ISnapshotManager {
    function takeSnapshot() external returns (uint256 snapshotId);
    function balanceOfAt(address account, uint256 snapshotId) external view returns (uint256);
}

Option 3: Simple Block-Based Recording

// For simple needs, just record block numbers
mapping(uint256 => uint256) public recordDates; // actionId => blockNumber

// Off-chain services can reconstruct balances at any block
// using historical blockchain data

Voting and Proxy Management

Shareholder voting for corporate governance (board elections, mergers, etc.) is typically handled off-chain with on-chain attestation:

Proxy Rules Documentation

// Store proxy voting rules via ERC-1643 document management
rtaContract.setDocument(
    "PROXY_RULES_2024",
    "ipfs://QmProxyVotingRulesHash",
    block.timestamp
);

Voting Process Pattern

contract VotingRegistry {
    struct ProxyVote {
        uint256 recordDate;
        uint256 votingDeadline;
        string proposalUri; // IPFS link to proposal details
        mapping(address => bool) hasVoted;
        mapping(uint256 => uint256) votes; // optionId => voteCount
    }

    // RTA records votes submitted through traditional proxy channels
    function recordVote(
        uint256 voteId,
        address shareholder,
        uint256 optionId,
        uint256 shares
    ) external onlyRTA {
        require(rtaContract.balanceOfAt(shareholder, recordDate) >= shares);
        require(!hasVoted[shareholder], "Already voted");

        votes[optionId] += shares;
        hasVoted[shareholder] = true;

        emit VoteRecorded(voteId, shareholder, optionId, shares);
    }
}

Quorum and Meeting Mechanics

For shareholder meetings requiring quorum:

contract MeetingQuorum {
    uint256 public quorumPercentage = 5000; // 50% in basis points

    function calculateQuorum(uint256 recordDate) external view returns (uint256) {
        uint256 totalSupply = token.totalSupply();
        return (totalSupply * quorumPercentage) / 10000;
    }

    function isQuorumMet(uint256 voteId) external view returns (bool) {
        uint256 totalVoted = getTotalVotes(voteId);
        uint256 required = calculateQuorum(votes[voteId].recordDate);
        return totalVoted >= required;
    }
}

Implementation Recommendations

Keep the Token Simple: Don’t add snapshot logic to the core ERC-1450 token. Use external contracts or off-chain systems.
Document Everything: Use Document Management Standard (1643) to store:
- PROXY_RULES - Voting procedures and requirements
- MEETING_NOTICE - Shareholder meeting announcements
- RECORD_DATE - Official record date declarations
- VOTING_RESULTS - Final vote tallies and outcomes
Hybrid Approach: Most voting happens off-chain through traditional proxy systems, with results attested on-chain by the RTA.
Regulatory Compliance: Follow SEC rules for proxy solicitation, including:
- Proper notice periods (typically 10-60 days)
- Required disclosures in proxy statements
- Vote tabulation by independent inspectors of election
Audit Trail: Maintain complete records of:
- Record date declarations
- Shareholder eligibility
- Votes submitted
- Final results and actions taken

Example Integration

// Complete voting lifecycle example
contract ShareholderGovernance {
    IERC1450 public token;
    ISnapshotManager public snapshots;

    function initiateVote(
        string memory proposalUri,
        uint256 votingPeriodDays
    ) external onlyRTA returns (uint256 voteId) {
        // 1. Take snapshot for record date
        uint256 snapshotId = snapshots.takeSnapshot();

        // 2. Store proposal details via ERC-1643
        token.setDocument(
            string(abi.encodePacked("PROPOSAL_", voteId)),
            proposalUri,
            block.timestamp
        );

        // 3. Set voting deadline
        uint256 deadline = block.timestamp + (votingPeriodDays * 1 days);

        // 4. Emit event for indexers and shareholders
        emit VoteInitiated(voteId, snapshotId, deadline, proposalUri);

        return voteId;
    }
}

This approach answers the “how do I do meetings?” question while keeping the core ERC-1450 token simple and focused on transfer control. RTAs can implement voting and governance in whatever way best suits their jurisdiction and security type, using the token as the source of truth for ownership while handling the mechanics externally.

Tax and Withholding Obligations (Non-Normative)

Tax compliance for security tokens is handled entirely off-chain by the RTA. This section documents common patterns for managing tax obligations without adding on-chain complexity.

Tax Documentation Collection

RTAs must collect appropriate tax documentation before enabling trading:

U.S. Persons:

W-9 Forms: Collected during KYC for U.S. tax residents
Taxpayer Identification Number (TIN): Stored securely off-chain
Backup Withholding: Applied when W-9 not provided (24% as of 2024)

Non-U.S. Persons:

W-8 Forms: Various types (W-8BEN, W-8BEN-E, W-8IMY, etc.)
Foreign TIN: When available under tax treaties
FATCA/CRS Compliance: Automatic exchange of information

Documentation references stored via Document Management Standard (1643):

// Store encrypted reference to tax documentation
rtaContract.setDocument(
    "TAX_DOCS_2024",
    "ipfs://QmTaxDocumentationHash", // Encrypted off-chain storage
    block.timestamp
);

Withholding at Source

For dividends and distributions, withholding occurs off-chain:

// Example: Dividend payment with withholding (off-chain calculation)
struct DividendPayment {
    address recipient;
    uint256 grossAmount;
    uint256 withholdingRate; // e.g., 3000 = 30%
    uint256 netAmount;       // grossAmount - withholding
}

// RTA calculates withholding based on:
// - Investor tax status (US vs. non-US)
// - Security type (equity vs. debt)
// - Tax treaty benefits
// - Dividend type (ordinary vs. qualified)

Tax Reporting

Annual tax reporting handled entirely off-chain:

1099 Series (U.S. Recipients):

1099-DIV: Dividend distributions
1099-B: Proceeds from broker transactions
1099-INT: Interest payments
1099-MISC: Other income

1042-S (Non-U.S. Recipients):

Foreign person’s U.S. source income
Withholding tax applied
Treaty benefits claimed

Reporting references maintained via document management:

// Annual tax reporting references
rtaContract.setDocument(
    "1099_FORMS_2024",
    "encrypted://tax-reports/2024/1099",
    block.timestamp
);

rtaContract.setDocument(
    "1042S_FORMS_2024",
    "encrypted://tax-reports/2024/1042s",
    block.timestamp
);

Implementation Pattern

// Off-chain tax compliance system interfaces with on-chain token
interface ITaxCompliance {
    // All functions are off-chain, shown here for documentation

    function collectW9(address investor) external;
    function collectW8(address investor, W8Type formType) external;
    function calculateWithholding(address investor, uint256 amount) external view returns (uint256);
    function generate1099(address investor, uint256 year) external;
    function generate1042S(address investor, uint256 year) external;

    // On-chain reference only
    function updateTaxDocumentHash(string memory docType, string memory uri) external;
}

Key Principles

No On-Chain Tax Logic: All tax calculations and withholding happen off-chain
Document References Only: Use Document Management Standard (1643) to store encrypted references to tax documents
Privacy Protection: Never store TINs, SSNs, or tax rates on-chain
Jurisdictional Flexibility: RTAs handle varying tax requirements per jurisdiction
Audit Trail: Maintain complete off-chain records for tax authority audits

Operational Workflow

Onboarding: Collect W-9/W-8 during KYC process
Distributions: Calculate withholding off-chain before payment
Trading: Track cost basis off-chain for 1099-B reporting
Year-End: Generate tax forms and provide to investors
Compliance: File with IRS/tax authorities as required

This approach ensures full tax compliance while keeping the token standard simple and avoiding the complexity of on-chain tax calculations. Tax obligations remain where they belong - in the operational layer managed by the regulated RTA.

ATS Adapter Pattern (Non-Normative)

While ERC-1450 explicitly excludes DEX trading due to compliance requirements, regulated Alternative Trading Systems (ATSs) and other SEC-registered venues can integrate with ERC-1450 tokens to provide compliant secondary market liquidity.

Monitoring Transfer Events for Liquidity Discovery

Regulated trading venues can monitor existing ERC-1450 events to facilitate compliant trading:

// Existing events that ATSs can monitor
event TransferRequested(
    address indexed from,
    address indexed to,
    uint256 value,
    uint256 fee
);

event TransferApproved(
    address indexed from,
    address indexed to,
    uint256 value
);

event TransferRejected(
    address indexed from,
    address indexed to,
    uint256 value,
    uint16 reason
);

ATS Integration Patterns

Pattern 1: Order Book Visibility

// ATS monitors TransferRequested events to understand market interest
// Can display pending transfer requests as "indications of interest"
// Note: Actual execution still requires RTA approval

Pattern 2: Pre-Matched Trade Submission

// ATS matches buyers and sellers off-chain
// Submits transfer via registered broker
function submitMatchedTrade(
    address buyer,
    address seller,
    uint256 shares
) external {
    require(registeredBrokers[msg.sender], "Must be registered broker");

    // Route through standard transfer request
    token.requestTransferWithFee(seller, buyer, shares, brokerFee);
}

Pattern 3: Failed Transfer Analysis

// ATS monitors TransferRejected events with reason codes
// Uses this data to:
// - Pre-filter non-compliant trades
// - Understand liquidity constraints
// - Improve matching algorithms

if (reasonCode == REASON_RECIPIENT_NOT_VERIFIED) {
    // Don't match with this buyer until KYC complete
} else if (reasonCode == REASON_INSUFFICIENT_BALANCE) {
    // Seller doesn't have shares available
}

Compliant Venue Integration

Regulated venues can facilitate liquidity while maintaining full compliance:

Pre-Trade Compliance
- Verify all parties are KYC/AML approved
- Check transfer restrictions before matching
- Ensure accreditation requirements are met
Trade Execution
- Submit transfers through registered broker accounts
- Include appropriate fees in transfer requests
- Maintain audit trail for regulatory review
Post-Trade Settlement
- Monitor TransferApproved events for confirmation
- Handle failed transfers based on reason codes
- Report trades to regulatory systems (CAT, TRACE, etc.)

Example ATS Adapter Implementation

contract ATSAdapter {
    IERC1450 public token;
    address public rtaAddress;

    // Track pending orders
    struct Order {
        address trader;
        bool isBuy;
        uint256 shares;
        uint256 price;
        bool isActive;
    }

    mapping(uint256 => Order) public orders;

    // Submit matched trades to RTA
    function executeTrade(
        uint256 buyOrderId,
        uint256 sellOrderId,
        uint256 shares
    ) external onlyATS {
        Order memory buyOrder = orders[buyOrderId];
        Order memory sellOrder = orders[sellOrderId];

        require(buyOrder.isBuy && !sellOrder.isBuy, "Invalid order types");
        require(buyOrder.isActive && sellOrder.isActive, "Orders not active");

        // Pre-verify compliance
        require(token.isKYCVerified(buyOrder.trader), "Buyer not KYC'd");
        require(token.isKYCVerified(sellOrder.trader), "Seller not KYC'd");

        // Submit transfer through registered broker
        token.requestTransferWithFee(
            sellOrder.trader,
            buyOrder.trader,
            shares,
            calculateFee(shares)
        );

        // Mark orders as pending execution
        orders[buyOrderId].isActive = false;
        orders[sellOrderId].isActive = false;
    }

    // Monitor rejection reasons to update order book
    function handleRejection(
        address from,
        address to,
        uint16 reasonCode
    ) external {
        // Update order book based on rejection reason
        if (reasonCode == 10) { // REASON_RECIPIENT_NOT_VERIFIED
            // Remove buy orders from this recipient
            cancelOrdersForTrader(to);
        }
    }
}

Benefits of ATS Integration

Compliant Liquidity: Provides secondary market without compromising KYC/AML
Price Discovery: Enables transparent pricing through regulated venues
Regulatory Reporting: Maintains full audit trail for SEC/FINRA requirements
Investor Protection: All trades go through regulated entities with oversight
Efficiency: Reduces settlement risk through pre-verification

Important Considerations

Not DEX Trading: All transfers still require RTA approval and KYC verification
Regulatory Compliance: ATSs must be SEC-registered and follow all applicable rules
No Direct P2P: Investors cannot trade directly; must go through regulated intermediaries
Reason Code Utilization: ATSs should use rejection reason codes to optimize matching
Fee Transparency: All broker and RTA fees must be clearly disclosed

This pattern demonstrates how ERC-1450 can support liquid secondary markets through regulated venues while maintaining the strict compliance requirements necessary for security tokens. The existing event structure provides sufficient information for ATSs to facilitate compliant trading without requiring any changes to the core standard.

Rationale

Why On-Chain If the RTA Gates Everything?

A critical question: If holders cannot initiate transfers and the RTA controls all operations, why use blockchain instead of a traditional centralized database? The answer lies in the unique benefits blockchain provides even within a regulated, controlled environment:

1. Immutable Global Audit Trail

Unlike traditional databases where entries can be modified or deleted, blockchain provides:

Permanent Record: Every mint, burn, and transfer is permanently recorded
Regulatory Transparency: SEC, FINRA, and state regulators can independently verify all transactions
Court-Admissible Evidence: Immutable records serve as indisputable evidence in legal proceedings
Real-Time Auditing: Eliminates the need for quarterly reconciliations and manual audits

2. Deterministic Settlement and Reconciliation

Traditional securities settlement involves multiple intermediaries and T+2 settlement cycles. ERC-1450 enables:

Instant Settlement: Transfers are atomic and final when executed
No Failed Trades: Eliminates settlement risk and the need for NSCC guarantees
Automated Reconciliation: Cap table is always accurate, no manual reconciliation needed
Reduced Counterparty Risk: No need for clearing houses or settlement intermediaries

3. Cost Efficiency Through L2 Deployment

Deployment on Layer 2 solutions provides dramatic cost savings:

Traditional System: $5-50 per transfer through existing infrastructure
L2 Deployment: $0.01-0.10 per transfer on Base, Arbitrum, or Polygon
Batch Operations: Process hundreds of transfers in a single transaction
No Infrastructure Costs: No need for expensive mainframes and data centers

4. Programmatic Composability

While direct transfers are disabled, valuable integrations remain:

Portfolio Management: Wallets and portfolio trackers can display holdings
Tax Reporting: Automated tax lot tracking and 1099 generation
Regulatory Reporting: Automated CAT and Blue Sheet reporting
Corporate Actions: Programmable dividends, splits, and voting
Compliant Secondary Markets: Integration with regulated ATSs and exchanges

5. Viable On-Chain Integrations

Despite transfer restrictions, these blockchain capabilities remain valuable:

Read Operations (Always Available):

balanceOf(): Check holdings
totalSupply(): View outstanding shares
decimals(), name(), symbol(): Token metadata (OPTIONAL per EIP-20, SHOULD be provided)
Event logs: Complete transaction history

RTA-Initiated Operations:

Automated dividend distributions
Programmatic share buybacks
Instant corporate actions (splits, mergers)
Cross-border settlements without correspondent banking

Compliance Integrations:

KYC/AML oracle integration
Accreditation verification services
Regulatory reporting automation
Smart contract escrows for M&A

6. Future Interoperability

Building on blockchain today positions for future innovations:

Central Bank Digital Currencies (CBDCs): Native integration for settlements
Cross-Border Securities: Eliminate need for ADRs and dual listings
24/7 Markets: Enable round-the-clock trading when regulations permit
DeFi Integration: Future compliant lending and borrowing against securities

7. Investor Benefits

Even without direct transfers, investors gain:

Transparency: View holdings and transactions in real-time
Proof of Ownership: Cryptographic proof without relying on RTA databases
Inheritance: Simplified estate transfer through smart contracts
Global Access: Hold US securities from anywhere without local custodians

The Centralized Database Comparison

A traditional centralized database cannot provide:

Cryptographic Proof: No mathematical guarantee of ownership
Global Accessibility: Requires API access and trust
Auditability: Can be modified without trace
Interoperability: Closed system with no composability
Cost Efficiency: Requires expensive infrastructure
Innovation Platform: No programmable extensions

Conclusion: ERC-1450 uses blockchain as a regulated public infrastructure rather than a permissionless payment rail. The RTA control model satisfies SEC requirements while capturing blockchain’s benefits: immutability, transparency, cost efficiency, and programmability. This is not about decentralization—it’s about building better market infrastructure.

SEC Regulatory Framework for Transfer Agent Operations

In the United States securities market, the exclusive control model where only the RTA can execute transfers, mints, and burns is based on established regulatory practice:

Transfer Agent Exclusive Authority: Under SEC Rule 17Ad-1 through 17Ad-22, transfer agents are designated as the sole entities responsible for:

Recording changes in ownership (equivalent to transferFrom)
Issuing securities (equivalent to mint)
Cancelling securities (equivalent to burnFrom)
Maintaining the official register of security holders

Regulatory Citations:

17 CFR § 240.17Ad-1: Defines transfer agent responsibilities for prompt and accurate clearance and settlement
17 CFR § 240.17Ad-10: Requires transfer agents to establish adequate internal accounting controls
17 CFR § 240.17Ad-11: Mandates accurate recordkeeping and reporting systems
Section 17A of the Securities Exchange Act of 1934: Establishes the regulatory framework for transfer agents

This standard implements these regulatory requirements by assigning exclusive control of transfer operations to the RTA. While this reflects US market practice rather than a universal requirement, similar designated transfer controller models exist in many jurisdictions worldwide. Implementers in other jurisdictions should consult local regulations for specific requirements.

ERC-1450 builds upon lessons learned from previous security token standards:

ERC-884 (Delaware General Corporations Law (DGCL) compatible share token) addresses corporate share requirements under Delaware law, focusing on maintaining compliant shareholder registries. While ERC-884 provides important groundwork for regulated securities on blockchain, it explicitly states that broader securities regulation requirements are out of scope.

Simple Restricted Token Standards provide basic transfer restrictions but do not address critical operational requirements such as recovery mechanisms, court-ordered transfers, or the designated transfer controller model.

The Controller of Record Model

In the United States, SEC regulations under Rule 17Ad mandate that Registered Transfer Agents maintain exclusive authority over share registry and transfer operations - a “controller of record” model that ensures regulatory compliance and investor protection. While other jurisdictions have similar designated controller requirements with different terminology, the SEC’s RTA framework is particularly stringent and well-established, making it an ideal foundation for this standard that can be adapted to other regulatory environments.

This standard implements this controller model on-chain, providing:

Single point of regulatory accountability
Clear audit trails for compliance
Recovery mechanisms for lost assets
Court-ordered transfer capabilities

ERC-3643 (T. rex) takes a different approach with on-chain identity management and modular compliance rules. While comprehensive, it adds significant complexity through multiple contracts and on-chain identity storage, which raises privacy concerns and gas costs. ERC-3643 is primarily adopted in European markets where regulatory frameworks differ from US SEC requirements.

Comparison Matrix: Security Token Standards

Feature	ERC-1450	ERC-3643 (T. rex)	Security Token Suite	Standard ERC-20
Control Model	RTA-exclusive monopsony	Multiple compliance agents	Flexible controllers	Permissionless
Identity Management	Off-chain (privacy-preserving)	On-chain identity registry	Mixed (implementation-dependent)	None
US SEC Compliance	✅ Native RTA model	❌ Requires adaptation	❌ Requires customization	❌ Non-compliant
Privacy	✅ No PII on-chain	❌ Identity data on-chain	⚠️ Implementation varies	✅ No identity required
Gas Efficiency	✅ Single contract	❌ Multiple contracts	❌ Modular architecture	✅ Minimal
Operational Complexity	✅ Simple RTA operations	❌ Complex rule engine	❌ Partition management	✅ Simple transfers
Recovery Mechanism	✅ Via controller transfer; optional time-locked workflow	⚠️ Implementation-dependent	⚠️ Via controller operations	❌ None
Court Orders	✅ Native support	⚠️ Via forced transfers	✅ Controller operations	❌ None
Transfer Restrictions	✅ RTA-gated only	✅ Rule-based	✅ Partition-based	❌ None
Direct Transfers	❌ Disabled (by design)	⚠️ If rules allow	⚠️ If authorized	✅ Always allowed
Broker Integration	✅ Native broker model	❌ Not specified	⚠️ Implementation varies	❌ None
Fee Collection	✅ Built-in mechanism	❌ Not specified	❌ Not specified	❌ None
Existing RTA Infrastructure	✅ Direct integration	❌ Requires middleware	❌ Requires adaptation	❌ Incompatible
Regulatory Reporting	✅ Clear audit trail	✅ On-chain compliance	⚠️ Varies by module	❌ None
Market Adoption	New (2025)	European markets	Limited	Widespread
Implementation Complexity	Low	High	High	Low
Upgrade Path	Via RTA Proxy	Contract migrations	Module updates	Immutable

Key Differentiator: ERC-1450’s RTA monopsony model is not a limitation but its core security feature. While other standards offer flexibility, ERC-1450 prioritizes regulatory compliance and operational simplicity through exclusive RTA control—essential for SEC-regulated securities where the transfer agent model is legally mandated.

Relationship to Security Token Suites

Various security token suites provide comprehensive frameworks through multiple complementary standards covering:

Core security token functionality with transfer restrictions
Document management for off-chain documents
Controller operations for forced transfers

While ERC-1450 appears to overlap with these standards (court-ordered transfers align with controller operations, document references align with document management), we deliberately chose not to extend existing suites for the following reasons:

Philosophical Difference: Other security token suites enables flexible, modular compliance where different operators can have different rules. ERC-1450 enforces a single, rigid model where only the RTA has control - essential for SEC compliance and adaptable to similar regulatory models globally. This isn’t a limitation—it’s the core security feature.
Regulatory Alignment: Other security token suites was designed for global markets with varying regulations. ERC-1450 is explicitly designed for US SEC-regulated securities with RTA requirements, while providing a framework that other jurisdictions can adopt for their designated transfer controller models. We prioritize regulatory clarity over flexibility.
Simplicity Over Modularity: Other security token suites uses multiple interconnected contracts and complex partition logic. ERC-1450 uses a single contract with clear, restricted operations. This reduces attack surface and audit complexity.
RTA Exclusivity: Other security token suites’s controller model allows for multiple controllers or changing controllers. ERC-1450’s RTA model explicitly prevents this—the RTA cannot be changed without cooperative action, protecting against issuer key compromise.
Gas Efficiency: By avoiding modular architecture and partition management, ERC-1450 operations are significantly more gas-efficient, important for retail investors on L2s.

Why Not Extend Existing Security Token Standards? Extending existing suites would require supporting their controller models, partition systems, and modular architectures—all of which conflict with the designated transfer controller model used in many regulated securities markets. The approaches are fundamentally incompatible.

Alignment with Established Security Token Patterns

ERC-1450 leverages established security token patterns for maximum interoperability:

Controller Operations Integration:

Implements standard controllerTransfer function for forced transfers
Emits standard ControllerTransfer events that existing tools can index
Uses operatorData parameter to specify transfer type while maintaining standard interface

Document Management Integration:

Defines an optional document management interface aligned with established security token patterns: setDocument, getDocument, removeDocument, getAllDocuments
When implemented, all evidence is stored as document URIs with cryptographic hashes
Never stores PII directly on-chain, only references
Emits standard DocumentUpdated and DocumentRemoved events for audit trails

Semantic Clarity Through Data Fields: The operatorData parameter in controllerTransfer encodes:

Document type (e.g., “COURT_ORDER”, “REGULATORY_ACTION”, “ESTATE_DISTRIBUTION”)
Document URI for off-chain storage
Cryptographic hash for integrity verification

This approach maintains standard function signatures while preserving the semantic precision required for regulatory compliance.

ERC-1450 specifically addresses US market needs and SEC requirements by:

Leveraging the existing RTA infrastructure mandated by SEC Rule 17Ad
Maintaining investor privacy with off-chain identity management
Providing simple, gas-efficient single contract architecture
Enabling omnibus custody models used by US broker-dealers
Supporting fee-based secondary markets with broker registration

While designed to meet stringent SEC requirements, the standard’s controller model can be adapted to other jurisdictions’ regulatory frameworks that employ similar designated transfer controller models, making it globally applicable while ensuring US regulatory compliance.

Fractional Shares Support

Unlike earlier proposals that forced decimals() to return 0, ERC-1450 allows configurable decimal places set at deployment. This flexibility recognizes that:

Modern Markets Support Fractions: Many securities now trade in fractional amounts:
- Mutual funds and ETFs often have fractional shares
- REITs frequently allow fractional ownership
- Modern broker-dealers offer fractional share trading for retail investors
- Dividend reinvestment plans (DRIPs) create fractional shares
Immutable at Deployment: The decimal places are set once at contract creation and cannot be changed, ensuring consistency throughout the security’s lifecycle.
RTA Control Maintained: Whether whole or fractional, all transfers remain under exclusive RTA control, maintaining regulatory compliance.

This design allows issuers to choose the appropriate divisibility for their specific security type while maintaining the strict RTA control model.

Wallet and DEX Integration via ERC-165

ERC-1450 implements ERC-165 introspection to prevent broken user experiences in wallets, DEXs, and other tools that expect standard ERC-20 behavior.

Detection Flow for Integrators:

// 1. Check if it's a security token (quickest check)
if (token.isSecurityToken()) {
    // This is ERC-1450, disable transfer/approve UI
    return handleSecurityToken();
}

// 2. Alternative: Check via ERC-165
bytes4 IERC1450_ID = 0x[computed_interface_id];
if (token.supportsInterface(IERC1450_ID)) {
    // This is ERC-1450, handle accordingly
    return handleSecurityToken();
}

// 3. For maximum compatibility, also check:
bytes4 IERC20_ID = 0x36372b07;
bool isERC20 = token.supportsInterface(IERC20_ID);
bool isSecure = token.isSecurityToken();
if (isERC20 && isSecure) {
    // Restricted ERC-20 interface detected
    showRestrictedTokenUI();
}

Expected Wallet/DEX Behavior:

Display: Show token balances normally (read-only operations work)
Transfers: Hide or disable transfer/send buttons
Swaps: Exclude from DEX trading interfaces
Approvals: Hide or disable approval interfaces
Information: Display “Security Token - Transfers Restricted” or similar
Secondary Market: Optionally provide link to compliant secondary market

This introspection mechanism ensures that:

Wallets don’t show broken transfer interfaces
DEXs don’t attempt to list restricted tokens
Portfolio trackers can display holdings correctly
Users understand the token’s restricted nature

Optional: ERC-1820 Registry

For broader discovery, implementations MAY also register with the ERC-1820 Pseudo-introspection Registry. This allows any address (including externally owned accounts acting as proxies) to publish interface support:

// Optional ERC-1820 registration
bytes32 constant private IERC1450_HASH = keccak256("IERC1450Token");
registry.setInterfaceImplementer(address(this), IERC1450_HASH, address(this));

However, ERC-165 support is sufficient for most use cases and is simpler to implement.

Backwards Compatibility

ERC-1450 implements the ERC-20 interface but with critical behavioral differences. Per the ERC-20 specification, functions MAY return false or revert() on failure. The specification notes: “Callers MUST handle false from returns (bool). Callers MUST NOT assume that false is never returned!”

This standard is ABI-compatible with ERC-20 for reads; state-changing ERC-20 flows are disallowed by design. Contracts MUST implement ERC-165 and expose the IERC1450 interface ID so clients can detect restricted semantics before offering send/approve UI. Note that ERC-20 itself does not define ERC-165 detection; using ERC-165 for ERC-20 interface detection is acceptable but not universally supported. The isSecurityToken() helper function provides an additional discovery mechanism, though ERC-165 and ERC-1820 should be considered the primary discovery methods.

ERC-1450 makes the following deliberate choices:

Read-Only Functions (Fully Compatible):

function totalSupply() external view returns (uint256) - Works normally
function balanceOf(address account) external view returns (uint256) - Works normally
function allowance(address owner, address spender) external view returns (uint256) - MUST always return 0

Restricted Functions (Modified Behavior):

function transfer(address to, uint256 amount) external returns (bool) and function approve(address spender, uint256 amount) external returns (bool):
- MUST always revert with ERC1450TransferDisabled error (never return false)
- This is permitted by ERC-20 which allows revert as a failure mode
- Holder-initiated transfers are not legal for regulated securities
function transferFrom(address from, address to, uint256 amount) external returns (bool):
- MUST always revert with ERC1450TransferDisabled error (never return false)
- This standard ERC-20 function is disabled to prevent confusion
- Use transferFromRegulated() for actual transfers with regulation tracking
Critical for Integrators:
- Implementers MUST expose ERC-165 interface IDs (supportsInterface and isSecurityToken)
- This allows clients to detect non-standard ERC-20 behavior before attempting transfers
- Without this detection, wallets and DEXs would mis-assume standard ERC-20 semantics
- The interface detection prevents users from attempting operations that will always fail
Approval event:
- Will never be emitted as approve() always reverts
- Implementations MAY omit this event entirely

Test Cases

Test cases are provided in the reference implementation repository (see Reference Implementation section).

Reference Implementation

A production-ready reference implementation is available at github.com/StartEngine/erc1450-reference.

This implementation has completed a comprehensive security audit by Halborn Security (December 2025) with all findings addressed. See the repository for full audit report and remediation details.

The reference implementation includes:

Full ERC-1450 compliant token contract
RTA Proxy pattern for enhanced security
Comprehensive test suite covering all functionality
Deployment scripts and integration examples
Gas optimization benchmarks
Contract versioning with automatic sync from package.json

Key features demonstrated in the reference implementation:

Transfer request workflow with fee collection
Recovery mechanism with timelock security
Court-ordered transfers and recovery procedures
Integration with existing ERC-20 infrastructure
Version tracking for upgrade detection

Contract Versioning

The reference implementation includes automatic version synchronization between the npm package version and the contract version() function. This enables:

Upgrade Detection: Compare deployed contract version against local artifacts to detect available upgrades
Audit Trail: Know exactly which version was deployed at any given time
Bytecode Verification: Match deployed bytecode hash against expected hash for security verification

// Query version from deployed contract
string memory deployedVersion = token.version();  // Returns "1.17.0"

// Compare with local artifacts to detect upgrades
if (keccak256(bytes(deployedVersion)) != keccak256(bytes(localVersion))) {
    // Upgrade available
}

The version is automatically synced via a pre-commit hook, ensuring the contract version always matches the package version without manual updates.

Security Considerations

Key Management and Custody

Investor Private Key Loss: When investors lose access to their private keys, the RTA’s exclusive control over transfers enables recovery procedures. Unlike permissionless tokens where lost keys mean permanently lost assets, ERC-1450’s RTA can execute court-ordered recovery transfers from lost addresses to new investor-controlled addresses after proper legal verification.

Transfer Agent Key Security: The RTA MUST implement institutional-grade key management including:

Hardware Security Modules (HSMs) or secure custody solutions (e.g., Fireblocks)
Multi-signature requirements for critical operations
Key rotation procedures through the RTAProxy pattern
Geographically distributed key shards to prevent single points of failure

Issuer Key Compromise: The RTAProxy pattern protects against compromised issuer keys by preventing unauthorized RTA changes. Once the RTAProxy is set as the transfer agent, even a compromised issuer cannot redirect token control to an attacker.

RTA Control Model Rationale

Why the Transfer Controller Has Unilateral Control: The design decision to give the designated transfer controller exclusive control over changeIssuer (preventing even the issuer from changing the issuer address themselves) is intentional and based on operational requirements:

Regulatory Independence in US Markets: In the United States, SEC Rule 17Ad-10 requires transfer agents to establish and maintain adequate internal accounting controls. SEC Rule 17Ad-11 mandates accurate recordkeeping. Transfer agents have fiduciary duties to shareholders that must remain independent from issuer influence. While other jurisdictions may have different requirements, this standard implements the US model which can be adapted for other regulatory frameworks.
Security Through Regulation: In US markets, RTAs are heavily regulated entities with:
- SEC registration under Section 17A of the Securities Exchange Act
- Compliance with Rules 17Ad-1 through 17Ad-22
- Regular FINRA examinations under Rule 17Ad-13
- Statutory liability for failures
- Professional insurance requirements
- Established business continuity plans
Issuer Key Vulnerability: Issuers (often startups) typically lack institutional-grade key management. If an issuer’s keys are compromised and they could change the RTA, an attacker could:
- Replace the legitimate RTA with their own address
- Steal all tokens from investors
- Destroy the entire cap table
Legitimate RTA Changes Are Supported: The model does support changing RTAs through cooperative action:
- Current RTA and issuer negotiate transition
- Legal agreements are executed off-chain
- Current RTA initiates the technical handoff
- New RTA accepts responsibility
- This mirrors traditional RTA transitions in conventional securities

Alternative Models Considered:

Dual-control: Would violate SEC Rule 17Ad requirements for RTA independence
Time-locks: Could prevent emergency actions required by court orders
Multi-sig with issuer: Reintroduces issuer key compromise risk

This design prioritizes regulatory compliance and investor protection over decentralization. For fully decentralized governance tokens, other standards like ERC-20 remain more appropriate.

Smart Contract Security

Reentrancy Protection: All state changes MUST occur before external calls. The restricted nature of ERC-1450 (direct value movement disabled, all transfers require RTA execution) naturally limits reentrancy vectors, but implementations should still follow check-effects-interactions patterns.

Integer Overflow/Underflow: Solidity 0.8.x provides automatic overflow protection. Implementations using earlier versions MUST use SafeMath or equivalent libraries for all arithmetic operations.

Authorization Bypasses: Critical functions are protected by modifiers (onlyTransferAgent). Implementations MUST ensure:

Modifiers check msg.sender against stored RTA address
No functions exist that bypass RTA authorization
The transfer() and approve() functions must ALWAYS revert with appropriate ERC-6093 errors

Regulatory Compliance Risks

Unauthorized Transfers: The disabled transfer() function prevents investors from bypassing KYC/AML requirements. All transfers must go through the RTA, ensuring regulatory compliance for every transaction.

Sanctions Screening: The RTA MUST maintain updated sanctions lists and check all parties before executing transfers. The exclusive RTA control ensures no transfers can bypass these checks.

Jurisdiction Restrictions: Securities often have geographic restrictions. The RTA enforces these through off-chain verification before executing any transfer.

Off-Chain Infrastructure Security

Database Compromise: As mentioned in the specification, RTAs maintain off-chain databases of investor information. These systems MUST implement:

Encryption at rest and in transit
Regular security audits
Access controls and audit logging
Backup and recovery procedures
Data residency compliance

Oracle Risks: If the implementation relies on oracles for pricing or other data:

Multiple oracle sources should be used to prevent manipulation
Circuit breakers should halt operations on suspicious data
Time delays for critical operations based on oracle data

Denial-of-Service Risks

RTA Availability: The RTA being the sole transfer authority creates a potential bottleneck. Mitigations include:

High-availability infrastructure with redundancy
Service Level Agreements (SLAs) for uptime
Batch processing capabilities to handle high volumes
Emergency procedures for RTA unavailability

Gas Griefing: Batch operations should implement gas limits per operation to prevent one failed transfer from reverting an entire batch.

DeFi Integration Risks

Incompatibility with DEXs: ERC-1450 tokens cannot be traded on standard DEXs due to disabled transfer() and approve() functions. This is intentional for regulatory compliance.

Wrapper Contract Risks: Any wrapper contracts that attempt to make ERC-1450 tokens tradeable MUST be carefully audited as they could bypass regulatory controls. The RTA should monitor for and potentially restrict transfers to unauthorized wrapper contracts.

Flash Loan Attacks: The disabled transfer() function prevents flash loan attacks. However, any future extensions should carefully consider flash loan implications.

Upgrade and Migration Security

Upgrade Authority: If the implementation uses upgradeable proxy patterns, upgrade authority MUST be carefully controlled, potentially requiring both RTA and issuer approval.

Migration Procedures: Token migrations to new contracts should include:

Snapshot mechanisms to preserve balances
Time-locked migration periods
Rollback capabilities in case of issues
Clear communication to all stakeholders

Emergency Response

Circuit Breakers: Implementations should include emergency pause mechanisms that can be triggered by the RTA in case of:

Smart contract vulnerabilities discovered
Regulatory enforcement actions
Custody provider compromises

Incident Response Plan: RTAs must maintain documented procedures for:

Key compromise scenarios
Smart contract vulnerabilities
Regulatory interventions
System outages

These security considerations are informed by operational experience from SEC-registered transfer agents managing billions in compliant securities offerings. The restricted nature of ERC-1450, while limiting functionality compared to permissionless tokens, provides strong security guarantees essential for regulatory compliance and investor protection.

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`	Number	Amount of global gas refunded

Optional Fields

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

Example:

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

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

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

Example:

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

Summary and Error Handling

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

Required Fields

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

Optional Fields

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

Example:

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

Rationale

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

Backwards Compatibility

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

Clients

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

Test Cases

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

Security Considerations

Tracing is expensive.

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

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

Copyright

ERC-721 Nonce Extension

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

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

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

Abstract

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

Motivation

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

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

Specification

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

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

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

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

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

Rationale

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

Backwards Compatibility

This standard is compatible with ERC-721.

Test Cases

Test cases are included in test.js.

Run:

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

Reference Implementation

See ERC5008.sol.

Security Considerations

No security issues found.

Copyright

Soulbound Badge

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

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

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

Abstract

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

Specification

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

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

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

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

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

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

Rationale

Immutability

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

Content Addressable URIs Required

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

No Specification for `badgeUri` Data Format

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

Backwards Compatibility

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

Security Considerations

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

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

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

Copyright

Cross-Chain Execution

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

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

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

Abstract

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

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

Motivation

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

Specification

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

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

MessageDispatcher
MessageExecutor

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

MessageDispatcher

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

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

MessageDispatcher Methods

dispatchMessage

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

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

MessageDispatchers MUST revert if toChainId is not supported.

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

MessageDispatchers MUST use a unique messageId for each message.

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

MessageDispatchers MAY require payment.

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

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

MessageDispatcher Events

MessageDispatched

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

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

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

MessageExecutor

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

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

Execution

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

MessageExecutors MUST NOT successfully execute a message more than once.

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

Calldata

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

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

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

MessageExecutor Events

MessageIdExecuted

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

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

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

MessageExecutor Errors

MessageAlreadyExecuted

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

interface MessageExecutor {
  error MessageIdAlreadyExecuted(
    bytes32 messageId
  );
}

MessageFailure

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

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

Rationale

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

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

Backwards Compatibility

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

Security Considerations

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

Copyright

ERC-1155 Allowance Extension

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

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

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

Abstract

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

Motivation

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

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

Specification

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

Contracts using this ERC MUST implement the IERC5216 interface.

Interface implementation

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

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

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

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

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

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

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

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

In addition, the safeBatchTransferFrom MUST:

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

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

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

Rationale

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

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

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

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

Backwards Compatibility

This standard is compatible with ERC-1155.

Reference Implementation

The reference implementation can be found here.

Security Considerations

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

Copyright

Endorsement - Permit for Any Functions

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

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

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

Abstract

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

Motivation

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

Specification

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

Interfaces

The interfaces and structures referenced here are as follows

pragma solidity ^0.8.9;

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

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

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

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

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

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

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


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

See IERC5453.sol.

Behavior specification

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

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

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

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

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

The functionParamStructHash MUST be computed as follows

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

whereas

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

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

Rationale

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

Backwards Compatibility

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

Reference Implementation

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

pragma solidity ^0.8.9;

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

import "./IERC5453.sol";

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

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

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

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

See AERC5453.sol

Reference Implementation of `EndorsableERC721`

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

pragma solidity ^0.8.9;

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

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

See EndorsableERC721.sol

Reference Implementation of `ThresholdMultiSigForwarder`

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

pragma solidity ^0.8.9;

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

}

See ThresholdMultiSigForwarder.sol

Security Considerations

Replay Attacks

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

Phishing

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

Copyright

Multi-privilege Management NFT Extension

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

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

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

Abstract

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

Motivation

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

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

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

Specification

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

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

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

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

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

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

The PrivilegeAssigned event MUST be emitted when setPrivilege is called.

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

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

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

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

The PrivilegeCloned event MUST be emitted when clonePrivilege is called.

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

Rationale

Shareable Privileges

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

Expire Date Type

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

Beneficiary of Referrer

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

Proposal: NFT Transfer

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

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

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

    _burn(tokenId);

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

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

Backwards Compatibility

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

Test Cases

Test cases are implemented with the reference implementation.

Test Code

test.js

Run in terminal:

truffle test ./test/test.js

testCloneable.js

Run in terminal:

truffle test ./test/testCloneable.js

Reference Implementation

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

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

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

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

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

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

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

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

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

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

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

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

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

Security Considerations

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

Copyright

Contracts Dependencies Registry

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

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

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

Abstract

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

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

Motivation

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

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

The advantages of using the provided system might be:

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

Specification

Overview

The system consists of two smart contracts:

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

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

ContractsRegistry

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

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

The ContractsRegistry MUST implement the following interface:

pragma solidity ^0.8.0;

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

Dependant

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

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

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

The Dependant contract MUST implement the following interface:

pragma solidity ^0.8.0;

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

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

Rationale

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

ContractsRegistry Rationale

Contracts Identifier

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

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

Reverts

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

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

Dependant Rationale

Dependencies

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

Injector

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

Reference Implementation

Note that the reference implementation depends on OpenZeppelin contracts 4.9.2.

ContractsRegistry Implementation

pragma solidity ^0.8.0;

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

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

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

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

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

    function injectDependencies(string memory name) external;

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

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

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

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

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

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

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

    function removeContract(string memory name) external;
}

contract ProxyUpgrader {
    using Address for address;

    address private immutable _OWNER;

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

    constructor() {
        _OWNER = msg.sender;
    }

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

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

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

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

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

contract ContractsRegistry is IContractsRegistry, OwnableUpgradeable {
    ProxyUpgrader private _proxyUpgrader;

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

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

        __Ownable_init();
    }

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

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

        return contractAddress_;
    }

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

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

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

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

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

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

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

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

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

        _proxyUpgrader.upgrade(contractToUpgrade_, newImplementation_, data_);

        emit ProxyContractUpgraded(name_, newImplementation_);
    }

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

        _contracts[name_] = contractAddress_;

        emit ContractAdded(name_, contractAddress_);
    }

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

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

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

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

        emit ProxyContractAdded(name_, proxyAddr_, contractAddress_);
    }

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

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

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

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

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

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

        emit ContractRemoved(name_);
    }

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

Dependant Implementation

pragma solidity ^0.8.0;

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

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

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

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

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

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

        assembly {
            injector_ := sload(slot_)
        }
    }

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

        assembly {
            sstore(slot_, injector_)
        }
    }

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

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

Security Considerations

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

ContractsRegistry Security

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

Dependant Security

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

Copyright

Single-contract Multi-delegatecall

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

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

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

Abstract

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

Motivation

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

Specification

Contracts implementing this EIP must implement the following interface:

pragma solidity ^0.8.0;

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

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

Rationale

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

Backwards Compatibility

This is compatible with most existing multicall functions.

Test Cases

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

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

Reference Implementation

pragma solidity ^0.8.0;

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

Security Considerations

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

Copyright

Empty accounts deprecation

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

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

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

Abstract

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

Motivation

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

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

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

Specification

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

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

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

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

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

Rationale

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

Alternative approaches include:

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

These approaches were rejected as being unnecessarily complicated.

Backwards Compatibility

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

Security Considerations

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

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

Copyright

Revert creation in case of non-empty storage

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

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

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

Abstract

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

Specification

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

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

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

Rationale

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

Backwards Compatibility

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

Test Cases

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

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

Security Considerations

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

Copyright

Network Upgrade Inclusion Stages

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

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

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

Abstract

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 (PFI) section of the Upgrade Meta EIP. The proposer of an EIP SHOULD serve as the primary point of contact for that EIP for the duration of the upgrade cycle or SHOULD designate another person to serve in that role. Reasonable pull requests SHOULD be merged in a timely fashion by the Upgrade Meta EIP author.

At this stage, implementation teams SHOULD review the EIP. For Core EIPs, this should be in the context of including it in the 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 (CFI) stage. Once a decision is made by client teams to move an EIP to Considered for Inclusion, the Upgrade Meta EIP SHOULD be updated to reflect this.

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

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

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

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

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

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

Declined for Inclusion

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

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

Scheduled for Inclusion

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

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

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

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

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

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

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

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

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

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

Included

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

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

Rationale

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

The specification tries to minimize steps 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

Store, Table-Based Introspectable Storage

Fri, 08 Nov 2024 00:00:00 +0000

EIP #7813 - Store, Table-Based Introspectable Storage is in Last Call status. It is authored by alvarius (@alvrs), dk1a (@dk1a), frolic (@frolic), ludens (@ludns), vdrg (@vdrg), yonada and was originally created 2024-11-08. 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-7813-store-table-based-introspectable-storage/21628

Abstract

This standard introduces a flexible on-chain storage pattern that organizes data into structured tables that consist of records with fixed key and value schemas, similar to a traditional database. This storage pattern consists of a unified contract interface for data access, along with a compact binary encoding format for both static and dynamic data types. State changes are tracked through standardized events that enable automatic, schema-aware state replication by off-chain indexers. New tables can be dynamically registered at runtime through a special table that stores schema metadata for all tables, allowing the system to evolve without breaking existing contracts or integrations.

Motivation

The absence of consistent standards for on-chain data management in smart contracts can lead to rigid implementations, tightly coupled contract logic with off-chain services, and challenges in updating or extending a contract’s data layout without breaking existing integrations.

Using the storage mechanism defined in this ERC provides the following benefits:

Automatic Indexing: By emitting consistent, standardized events during state changes, off-chain services can automatically track on-chain state and provide schema-aware indexer APIs.
Elimination of Custom Getter Functions: Any contract or off-chain service can read stored data through a consistent interface, decoupling smart contract implementation from specific data access patterns and reducing development overhead.
Simpler Upgradability: This pattern leverages unstructured storage, making it easier to upgrade contract logic without the risks associated with using a fixed storage layout.
Flexible Data Extensions: New tables can be added at runtime without without breaking existing integrations with other data consumers.
Reduced gas costs: Using efficient data packing reduces gas costs for both storage and event emissions.

Specification

Definitions

Store

A smart contract that implements the interface proposed by this ERC and organizes data in Tables. It emits events for each data operation so that off-chain components can replicate the state of all tables.

Table

A storage structure that holds Records sharing the same Schema.

On-chain Table: Stores its state on-chain and emits events for off-chain- indexers.
Off-chain Table: Does not store state on-chain but emits events for off-chain indexers.

Record

A piece of data stored in a Table, addressed by one or more keys.

`ResourceId`

A 32-byte value that uniquely identifies each Table within the Store.

type ResourceId is bytes32;

Encoding:

Bytes (from left to right)	Description
0-1	Table type identifier
2-31	Unique identifier

Table Type Identifiers:

0x7462 ("tb") for on-chain tables
0x6f74 ("ot") for off-chain tables

`Schema`

Used to represent the layout of Records within a table.

type Schema is bytes32;

Each Table defines two schemas:

Key Schema: the types of the keys used to uniquely identify a Record within a table. It consists only of fixed-length data types.
Value Schema: the types of the value fields of a Record within a table, which can include both fixed-length and variable-length data types.

Byte(s) from left to right	Value	Constraint
0-1	Total byte length of static fields
2	Number of static length fields	≤ (28 - number of dynamic length fields)
3	Number of dynamic length fields	For the key schema, 0
For the value schema, ≤5
4-31	Each byte encodes a `SchemaType`	Dynamic-length types MUST come after all the static-length types.

`SchemaType`

Single byte that represents the type of a specific static or dynamic field.

enum SchemaType { ... }

Type Encoding

Value Range	Type
`0x00` to `0x1F`	`uint8` to `uint256` (increments of 8 bits)
`0x20` to `0x3F`	`int8` to `int256` (increments of 8 bits)
`0x40` to `0x5F`	`bytes1` to `bytes32`
`0x60`	`bool`
`0x61`	`address`
`0x62` to `0x81`	`uint8[]` to `uint256[]`
`0x82` to `0xA1`	`int8[]` to `int256[]`
`0xA2` to `0xC1`	`bytes1[]` to `bytes32[]`
`0xC2`	`bool[]`
`0xC3`	`address[]`
`0xC4`	`bytes`
`0xC5`	`string`

`FieldLayout`

Encodes the concrete value Schema information, specifically the total byte length of the static fields, the number of dynamic fields and the length of each static field on its own.

This encoding serves as an optimization for on-chain operations. By having the exact lengths readily available, the Store doesn’t need to repeatedly compute or translate the schema definitions into actual field lengths during execution.

type FieldLayout is bytes32;

Byte(s) from left to right	Value	Constraint
0-1	Total length of static fields
2	Number of static length fields	≤ (28 - number of dynamic length fields)
3	Number of dynamic length fields	For the key schema, 0
For the value schema, ≤5
4-31	Each byte encodes the byte length of the corresponding static field

`EncodedLengths`

Encodes the byte length of all the dynamic fields of a specific Record. It is returned by the Store methods when reading a Record, as it is needed for decoding dynamic fields.

type EncodedLengths is bytes32;

Bytes (from least to most significant)	Type	Description
0x00-0x06	uint56	Total byte length of dynamic data
0x07-0xB	uint40	Length of the first dynamic field
0x0C-0x10	uint40	Length of the second dynamic field
0x11-0x15	uint40	Length of the third dynamic field
0x16-0x1A	uint40	Length of the fourth dynamic field
0x1B-0x1F	uint40	Length of the fifth dynamic field

Packed Data Encoding

Record data returned by Store methods and included in Store events uses the following encoding rules.

Field Limits

Maximum Total Fields: A record can contain up to 28 fields in total (both static and dynamic fields combined).
- This limit is due to the Schema type structure, which uses 28 bytes (bytes 4 to 31) to define field types, with one byte per field (SchemaType).
Dynamic Fields Limit: A record can have up to 5 dynamic fields.
- This is due to the fact that a single 32 bytes word (EncodedLengths) to encode the byte lengths of each dynamic field, instead of encoding each length separately as Solidity’s abi.encode would.
Static Fields Limit: The maximum number of static fields is 28 minus the number of dynamic fields.
- For example, if there are 5 dynamic fields, the maximum number of static fields is 23 (28 - 5).

Encoding Rules

Static-length fields are encoded without any padding, and concatenated in the order they are defined in the schema, which is equivalent to using Solidity’s abi.encodePacked.
For dynamic-length fields (arrays, bytes, and strings):
- If the field is an array, its elements are tightly packed without padding.
- All dynamic fields are concatenated together without padding and without including their lengths.
- The lengths of all dynamic fields are encoded into a single EncodedLengths.

Example

Suppose a table has the following value schema:

(uint256 id, address owner, string description, uint8[] scores)

Encoding (Pseudocode):

bytes memory staticData = abi.encodePacked(id, owner);

// This is a custom function as Solidity does not provide a way to tightly pack array elements
bytes memory packedScores = packElementsWithoutPadding(scores);

// abi.encodePacked concatenates both description and packedScores without including their lengths
bytes memory dynamicData = abi.encodePacked(description, packedScores);

// Total length is encoded in the 56 least significant bits
EncodedLengths encodedLengths = dynamicData.length;

// Each length is encoded using 5 bytes
encodedLengths |= (description.length << (56));
encodedLengths |= (encodedData.length << (56 + 8 * 5));

// The full encoded record data is represented by the following tuple:
// (staticData, encodedLengths, dynamicData)

Store Interface

All Stores MUST implement the following interface.

interface IStore {
  /**
   * Get full encoded record (all fields, static and dynamic data) for the given tableId and key tuple.
   */
  function getRecord(
    ResourceId tableId,
    bytes32[] calldata keyTuple
  ) external view returns (bytes memory staticData, EncodedLengths encodedLengths, bytes memory dynamicData);

  /**
   * Get a single encoded field from the given tableId and key tuple.
   */
  function getField(
    ResourceId tableId,
    bytes32[] calldata keyTuple,
    uint8 fieldIndex
  ) external view returns (bytes memory data);

  /**
   * Get the byte length of a single field from the given tableId and key tuple
   */
  function getFieldLength(
    ResourceId tableId,
    bytes32[] memory keyTuple,
    uint8 fieldIndex
  ) external view returns (uint256);
}

The return values of both getRecord and getField use the encoding rules previously defined in the Packed Data Encoding section. More specifically, getRecord returns the fully encoded record tuple, and the data returned by getField is encoded using the encoding rules as if the field was being encoded on its own.

Store Operations and Events

This standard defines three core operations for manipulating records in a table: setting, updating, and deleting. For each operation, specific events must be emitted. The implementation details of these operations are left to the discretion of each Store implementation.

The fundamental requirement is that for on-chain tables the Record data retrieved through the Store interface methods at any given block MUST be consistent with the Record data that would be obtained by applying the operations implied by the Store events up to that block. This ensures data integrity and allows for accurate off-chain state reconstruction.

`Store_SetRecord`

Setting a Record means overwriting all of its fields. This operation can be performed whether the record has been set before or not (the standard does not enforce existence checks).

The Store_SetRecord event MUST be emitted whenever the full data of a record has been overwritten.

event Store_SetRecord(
  ResourceId indexed tableId,
  bytes32[] keyTuple,
  bytes staticData,
  EncodedLengths encodedLengths,
  bytes dynamicData
);

Parameters:

Name	Type	Description
tableId	ResourceId	The ID of the table where the record is set
keyTuple	bytes32[]	An array representing the composite key for the record
staticData	bytes	The static data of the record using packed encoding
encodedLengths	EncodedLengths	The encoded lengths of the dynamic data of the record
dynamicData	bytes	The dynamic data of the record, using custom packed encoding

`Store_SpliceStaticData`

Splicing the static data of a Record consists in overwriting bytes of the packed encoded static fields. The total length of static data does not change as it is determined by the table’s value schema.

The Store_SpliceStaticData event MUST be emitted whenever the static data of the Record has been spliced.

event Store_SpliceStaticData(
  ResourceId indexed tableId,
  bytes32[] keyTuple,
  uint48 start,
  bytes data
);

Parameters:

Name	Type	Description
tableId	ResourceId	The ID of the table where the data is spliced
keyTuple	bytes32[]	An array representing the key for the record
start	uint48	The start position in bytes for the splice operation
data	bytes	Packed ABI encoding of a tuple with the value’s static fields

`Store_SpliceDynamicData`

Splicing the dynamic data of a Record involves modifying the packed encoded representation of its dynamic fields by removing, replacing, and/or inserting new bytes in place.

The Store_SpliceDynamicData event MUST be emitted whenever the dynamic data of the Record has been spliced.

event Store_SpliceDynamicData(
  ResourceId indexed tableId,
  bytes32[] keyTuple,
  uint8 dynamicFieldIndex,
  uint48 start,
  uint40 deleteCount,
  EncodedLengths encodedLengths,
  bytes data
);

Parameters:

Name	Type	Description
tableId	ResourceId	The ID of the table where the data is spliced
keyTuple	bytes32[]	An array representing the composite key for the record
dynamicFieldIndex	uint8	The index of the dynamic field to splice data, relative to the start of the dynamic fields (Dynamic field index = field index - number of static fields)
start	uint48	The start position in bytes for the splice operation
deleteCount	uint40	The number of bytes to delete in the splice operation
encodedLengths	EncodedLengths	The resulting encoded lengths of the dynamic data of the record
data	bytes	The data to insert into the dynamic data of the record at the start byte

`Store_DeleteRecord`

The Store_DeleteRecord event MUST be emitted whenever the Record has been deleted from the Table.

event Store_DeleteRecord(ResourceId indexed tableId, bytes32[] keyTuple);

Parameters:

Name	Type	Description
tableId	ResourceId	The ID of the table where the record is deleted
keyTuple	bytes32[]	An array representing the composite key for the record

See the reference implementation section for an example on how to index store events.

The `Tables` table

To keep track of the information of each table and support registering new tables at runtime, the Store implementation MUST include a special on-chain Tables table, which behaves the same way as other on-chain tables except for the special constraints mentioned below.

The Tables table MUST use the following Schemas:

Key Schema:
- tableId (ResourceId): ResourceId of the table this record describes.
Value Schema:
- fieldLayout (FieldLayout): encodes the byte length of each static data type in the table.
- keySchema (Schema): represents the data types of the (composite) key of the table.
- valueSchema (Schema): represents the data types of the value fields of the table.
- abiEncodedKeyNames (bytes): ABI encoded string array of key names.
- abiEncodedFieldNames (bytes): ABI encoded string array of field names.

Records stored in the Tables table are considered immutable:

The Store MUST emit a single Store_SetRecord event for each table being registered.
The Store SHOULD NOT emit any other Store events for a Table registered in the Tables table.

The Tables table MUST store a record that describes itself before any other table is registered, emitting the corresponding Store_SetRecord event. The record must use the following tableId:

// First two bytes indicates that this is an on-chain table
// The next 30 bytes are the unique identifier for the Tables table
// bytes32("tb") | bytes32("store") >> (2 * 8) | bytes32("Tables") >> (2 * 8 + 14 * 8)
ResourceId tableId = ResourceId.wrap(0x746273746f72650000000000000000005461626c657300000000000000000000);

By using a predefined ResourceId and Schema for the Tables table, off-chain indexers can interpret store events for all registered tables. This enables the development of advanced off-chain services that operate on structured data rather than raw encoded data like in the previous indexer implementation example.

Rationale

Splice Events

While the Store_SetRecord event suffices for tracking the data of each record off-chain, including Splice events (Store_SpliceStaticData and Store_SpliceDynamicData) allows for more efficient partial updates. When only a portion of a record changes, emitting a full SetRecord event would be inefficient because the entire record data would need to be read from storage and emitted. Splice events enable the store to emit only the minimal necessary data for the update, reducing gas consumption. This is particularly important for records with large dynamic fields, as the cost of updating them doesn’t grow with the field’s size.

Disallowing Arrays of Dynamic Types

Arrays of dynamic types (e.g., string[], bytes[]) are intentionally not included as supported SchemaTypes. This restriction enforces a flat data schema, which simplifies the store implementation and enhances efficiency. If users need to store such data structures, they can model them using a separate table with a schema like { index: uint256, data: bytes }, where each array element is represented as an individual record.

FieldLayout Optimization

Including the FieldLayout in the Tables schema provides an on-chain optimization by precomputing and storing the exact byte lengths of static fields. This eliminates the need to repeatedly compute field lengths and offsets during runtime, which can be gas-intensive. By having this information readily available, the store can perform storage operations more efficiently, while components reading from the store can retrieve it from the Tables table to decode the corresponding records.

Special `Tables` table

Including a special Tables table provides significant benefits for off-chain indexers. While emitting events for table registration isn’t strictly necessary for basic indexers that operate on raw encoded data, doing so makes indexers aware of the schemas used by each table. This awareness enables the development of more advanced, schema-aware indexer APIs (e.g., SQL-like query capabilities), enhancing the utility and flexibility of off-chain data interactions.

By reusing existing Store abstractions for table registration, we also simplify the implementation and eliminate the need for additional, specific table registration events. Indexers can leverage the standard Store events to access schema information, ensuring consistency and reducing complexity.

Reference Implementation

Store Event Indexing

The following example shows how a simple in-memory indexer can use the Store events to replicate the Store state off-chain. It is important to note that this indexer operates over raw encoded data which is not that useful on its own, but can be improved as we will explain in the next section.

We use TypeScript for this example but it can easily be replicated with other languages.

type Hex = `0x${string}`;

type Record = {
  staticData: Hex;
  encodedLengths: Hex;
  dynamicData: Hex;
};

const store = new Map<string, Record>();

// Create a key string from a table ID and key tuple to use in our store Map above
function storeKey(tableId: Hex, keyTuple: Hex[]): string {
  return `${tableId}:${keyTuple.join(",")}`;
}

// Like `Array.splice`, but for strings of bytes
function bytesSplice(
  data: Hex,
  start: number,
  deleteCount = 0,
  newData: Hex = "0x"
): Hex {
  const dataNibbles = data.replace(/^0x/, "").split("");
  const newDataNibbles = newData.replace(/^0x/, "").split("");
  return `0x${dataNibbles
    .splice(start, deleteCount * 2)
    .concat(newDataNibbles)
    .join("")}`;
}

function bytesLength(data: Hex): number {
  return data.replace(/^0x/, "").length / 2;
}

function processStoreEvent(log: StoreEvent) {
  if (log.eventName === "Store_SetRecord") {
    const key = storeKey(log.args.tableId, log.args.keyTuple);

    // Overwrite all of the Record's fields
    store.set(key, {
      staticData: log.args.staticData,
      encodedLengths: log.args.encodedLengths,
      dynamicData: log.args.dynamicData,
    });
  } else if (log.eventName === "Store_SpliceStaticData") {
    const key = storeKey(log.args.tableId, log.args.keyTuple);
    const record = store.get(key) ?? {
      staticData: "0x",
      encodedLengths: "0x",
      dynamicData: "0x",
    };

    // Splice the static field data of the Record
    store.set(key, {
      staticData: bytesSplice(
        record.staticData,
        log.args.start,
        bytesLength(log.args.data),
        log.args.data
      ),
      encodedLengths: record.encodedLengths,
      dynamicData: record.dynamicData,
    });
  } else if (log.eventName === "Store_SpliceDynamicData") {
    const key = storeKey(log.args.tableId, log.args.keyTuple);
    const record = store.get(key) ?? {
      staticData: "0x",
      encodedLengths: "0x",
      dynamicData: "0x",
    };

    // Splice the dynamic field data of the Record
    store.set(key, {
      staticData: record.staticData,
      encodedLengths: log.args.encodedLengths,
      dynamicData: bytesSplice(
        record.dynamicData,
        log.args.start,
        log.args.deleteCount,
        log.args.data
      ),
    });
  } else if (log.eventName === "Store_DeleteRecord") {
    const key = storeKey(log.args.tableId, log.args.keyTuple);

    // Delete the whole Record
    store.delete(key);
  }
}

Security Considerations

Access Control

This standard only defines functions to read from the Store (getRecord, getField, and getFieldLength). The methods for setting or modifying records in the store are left to each specific implementation. Therefore, implementations must provide appropriate access control mechanisms for writing to the store, tailored to their specific use cases.

On-Chain Data Accessibility

All data stored within a store is accessible not only off-chain but also on-chain by other smart contracts through the provided read functions (getRecord, getField, and getFieldLength). This differs from the typical behavior of smart contracts, where internal storage variables are private by default and cannot be directly read by other contracts unless explicit getter functions are provided. Thus, developers must be mindful that any data stored in the store is openly accessible to other smart contracts.

Copyright

Transferable Tokenized Vault Requests

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

EIP #8161 - Transferable Tokenized Vault Requests is in Last Call status. It is authored by Cain O'Sullivan (@cosullivan), Jeroen Offerijns (@hieronx) and was originally created 2025-02-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/draft-erc-transferable-asynchronous-tokenized-vault-requests/27747

Abstract

This standard extends ERC-7540 by adding optional transferability of pending deposit and redeem Requests. It introduces two separate interfaces that allow a controller to transfer their pending Request balance to a new controller. Implementations may support either or both interfaces independently.

Motivation

ERC-7540 asynchronous Requests can remain in the Pending state for an extended period of time. During this period, controllers have no way to transfer their position to another address. This creates friction for users who need to migrate wallets, restructure positions across accounts, or integrate with protocols that compose on top of pending Request positions.

By enabling transferability of pending Requests, this standard unlocks secondary market liquidity for pending positions and simplifies account management without requiring cancelation and re-submission of Requests.

Transferability is kept optional and split into two separate interfaces so that implementations can choose to support transferable deposit Requests, transferable redeem Requests, both, or neither, depending on their security model and use case.

Specification

Transferable Deposit Requests

Vaults that support transferable deposit Requests MUST implement the IERC7540DepositTransferable interface.

`transferDepositRequest`

Transfers the entire pending deposit Request balance from oldController to newController for the given requestId.

MUST only transfer the Pending balance. Claimable balances MUST NOT be affected.

After a successful transfer, pendingDepositRequest(requestId, oldController) MUST decrease by the transferred amount and pendingDepositRequest(requestId, newController) MUST increase by the same amount (less any fees).

msg.sender MUST be oldController or an operator approved by oldController.

MUST emit the TransferDepositRequest event.

- name: transferDepositRequest
  type: function
  stateMutability: nonpayable

  inputs:
    - name: requestId
      type: uint256
    - name: oldController
      type: address
    - name: newController
      type: address

`TransferDepositRequest`

from has transferred their pending deposit Request to to for the given requestId.

MUST be emitted when a pending deposit Request is transferred using the transferDepositRequest method.

- name: TransferDepositRequest
  type: event

  inputs:
    - name: requestId
      indexed: true
      type: uint256
    - name: from
      indexed: true
      type: address
    - name: to
      indexed: true
      type: address
    - name: sender
      indexed: false
      type: address

Transferable Redeem Requests

Vaults that support transferable redeem Requests MUST implement the IERC7540RedeemTransferable interface.

`transferRedeemRequest`

Transfers the entire pending redeem Request balance from oldController to newController for the given requestId.

MUST only transfer the Pending balance. Claimable balances MUST NOT be affected.

After a successful transfer, pendingRedeemRequest(requestId, oldController) MUST decrease by the transferred amount and pendingRedeemRequest(requestId, newController) MUST increase by the same amount (less any fees).

msg.sender MUST be oldController or an operator approved by oldController.

MUST emit the TransferRedeemRequest event.

- name: transferRedeemRequest
  type: function
  stateMutability: nonpayable

  inputs:
    - name: requestId
      type: uint256
    - name: oldController
      type: address
    - name: newController
      type: address

`TransferRedeemRequest`

from has transferred their pending redeem Request to to for the given requestId.

MUST be emitted when a pending redeem Request is transferred using the transferRedeemRequest method.

- name: TransferRedeemRequest
  type: event

  inputs:
    - name: requestId
      indexed: true
      type: uint256
    - name: from
      indexed: true
      type: address
    - name: to
      indexed: true
      type: address
    - name: sender
      indexed: false
      type: address

ERC-165 Support

Smart contracts implementing this standard MUST implement the ERC-165 supportsInterface function.

Vaults implementing IERC7540DepositTransferable MUST return the constant value true when 0x53b3bb0a is passed through the interfaceID argument.

Vaults implementing IERC7540RedeemTransferable MUST return the constant value true when 0x7846f5bd is passed through the interfaceID argument.

Rationale

Only Transferring Pending Balances

This standard deliberately restricts transfers to the Pending state. Claimable balances already have a deterministic exchange rate and can be claimed by the controller at any time; transferring them would add complexity without significant benefit. Limiting scope to Pending balances keeps the interface simple and avoids edge cases around partial claimability.

Separate Interfaces for Deposit and Redeem Transferability

Following the design philosophy of ERC-7540 where deposit and redemption flows are independently optional, this standard keeps deposit and redeem transferability as separate interfaces. A Vault may have valid reasons to allow transferability of one request type but not the other. For example, a Vault might allow transfer of pending deposit Requests (where assets are locked) but disallow transfer of pending redeem Requests (where shares have already been burned or locked with specific accounting implications).

Transferring the Full Pending Balance

The transferDepositRequest and transferRedeemRequest methods transfer the entire pending balance rather than accepting a partial amount. This simplifies the interface and aligns with the ERC-7540 model where Requests of the same requestId are fungible.

Backwards Compatibility

This standard is fully backward compatible with ERC-7540. Vaults that do not implement this extension continue to function as before. Integrators can detect support for transferability via ERC-165 supportsInterface.

Security Considerations

Operator Trust

As with ERC-7540, operators approved by a controller can transfer pending Requests on their behalf. Users must be aware that granting operator permissions extends to the ability to transfer pending Requests to arbitrary addresses, effectively moving locked assets or shares out of the controller’s control.

Pricing of Pending Requests

Unlike Vault shares, which have convertToShares and convertToAssets as onchain price references, pending Requests have no built-in pricing mechanism. The exchange rate is unknown until fulfillment. Builders of secondary markets around transferable Requests should account for this lack of a canonical price source when designing pricing and settlement mechanisms.

Copyright

AI Agent Authenticated Wallet

Sat, 14 Mar 2026 00:00:00 +0000

EIP #8196 - AI Agent Authenticated Wallet is in Last Call status. It is authored by Leigh Cronian (@cybercentry) , Chris Johnson and was originally created 2026-03-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/erc-8196-ai-agent-authenticated-wallet/27987

Abstract

This ERC defines a standard interface for AI agent-authenticated wallets. These wallets execute transactions only when accompanied by verifiable cryptographic proof that the action complies with a specific policy defined by the asset owner.

It serves as Layer 3 (Execute) in a modular trust stack designed for secure autonomous AI agents:

Layer 1 (Register): ERC-8004 - on-chain identity and registration
Layer 2 (Verify): ERC-8126 - verification/risk scoring
Layer 3 (Execute): This standard - policy-bound execution with immutable audit trail

The design enables secure credential delegation without exposing private keys, prevents host manipulation of agent behavior, provides tamper-evident logging of all session activity, and ensures users retain final say over their agents and actions, as emphasized in the EF Mandate (“a user has the final say over their identities, assets, actions, and agents”).

Motivation

Autonomous AI agents introduce critical security challenges when performing on-chain actions:

Hosting Trust Trap - Hosts can steal private keys if agents hold funds directly
Blind Delegation - Credential delegation to agents lacks enforceable limits or auditable compliance
Host Manipulation - Malicious hosts can suppress outputs, delay requests, replay probabilistic queries, or influence agent behavior through repeated sampling
Malicious Historical Activity - Agents with prior sanctions, mixer usage, bot-like patterns, rapid forwarding, or clustering with tainted addresses pose ongoing risk
Replay & Timing Vulnerabilities - Valid proofs from the past can be reused, or timing manipulated to the host’s advantage

This ERC provides the execution layer in a composable trust stack to mitigate these risks:

Layer	Purpose	Standard	Core Question
1	Register	ERC-8004	“Does this agent exist on-chain?”
2	Verify	ERC-8126	“Is this agent trustworthy and free of malicious signals?”
3	Execute	This ERC	“Is this action authorized right now?”

Key features include:

Cryptographically enforced policy compliance
Immutable, hash-chained audit trail for verifiable delegation
Entropy commit-reveal to counter host influence on probabilistic agents
Active containment mechanisms (recommended) for real-time violation response
Legacy credential delegation via TLS attestations
User sovereignty over agent actions via enforceable, auditable policy compliance, emphasising final user control over agents and actions

The verification layer allows flexibility while strongly encouraging checks (e.g. via ERC-8126 Wallet Verification) against historical malicious behavior before granting control.

Specification

Trust Stack Integration

This ERC defines an on-chain smart contract interface (IAIAgentAuthenticatedWallet). Implementations are expected to be smart contracts (such as ERC-4337 account abstraction wallets or dedicated policy enforcement modules) that implement this interface.

Verification Check (ERC-8126): Implementations MUST perform a verification check using ERC-8126 before executing any agent action. The policy’s minVerificationScore field MUST be enforced. Actions MUST be rejected if the agent’s current ERC-8126 score exceeds the minVerificationScore value set in the policy. The agent’s ERC-8126 score MUST be looked up by the policy’s agentId via getLatestRiskScore.

Off-chain components (such as agent hosting services, wallet UIs, and relayers) SHOULD also perform the same verification checks before submitting transactions or UserOperations.

Agent Policy Structure

Policies MUST include the following fields:

Field	Type	Required	Description
`policyId`	`bytes32`	Yes	Unique policy identifier
`agentAddress`	`address`	Yes	Authorized AI agent address
`agentId`	`uint256`	Yes	ERC-8004 agent id; key for the ERC-8126 `getLatestRiskScore` lookup
`ownerAddress`	`address`	Yes	Asset owner / delegator
`allowedActions`	`string[]`	Yes	List of permitted actions (e.g. `["transfer", "swap"]`)
`allowedContracts`	`address[]`	Yes	Whitelist of target contracts
`blockedContracts`	`address[]`	Yes	Blacklist of contracts
`maxValuePerTx`	`uint256`	Yes	Maximum value per transaction (in wei)
`maxValuePerDay`	`uint256`	No	Optional daily spending limit (in wei)
`validAfter`	`uint256`	Yes	Timestamp when the policy becomes active
`validUntil`	`uint256`	Yes	Timestamp when the policy expires
`minVerificationScore`	`uint8`	Yes	Minimum ERC-8126 verification score required (20 = Low Risk tier; scores 0–20 allowed; lower score = lower risk)

ERC-712 Types

bytes32 constant AGENT_ACTION_TYPEHASH = keccak256(
    "AgentAction(address agent,string action,address target,uint256 value,bytes data,uint256 nonce,uint256 validUntil,bytes32 policyHash,bytes32 entropyCommitment)"
);

bytes32 constant DELEGATION_TYPEHASH = keccak256(
    "Delegation(address delegator,address delegatee,bytes32 policyHash,uint256 validUntil,uint256 nonce)"
);

Core Interface

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

interface IAIAgentAuthenticatedWallet {
    event PolicyRegistered(
        bytes32 indexed policyHash,
        address indexed owner,
        address indexed agent,
        uint256 validUntil
    );

    event ActionExecuted(
        bytes32 indexed policyHash,
        address indexed agent,
        address target,
        uint256 value,
        bytes32 auditEntryId
    );

    event PolicyRevoked(
        bytes32 indexed policyHash,
        string reason
    );

    event AuditEntryLogged(
        bytes32 indexed entryId,
        uint256 sequence,
        bytes32 sessionId,
        string actionType
    );

    function registerPolicy(
        address agent,
        uint256 agentId,
        string[] calldata allowedActions,
        address[] calldata allowedContracts,
        address[] calldata blockedContracts,
        uint256 maxValuePerTx,
        uint256 maxValuePerDay,
        uint256 validAfter,
        uint256 validUntil,
        uint8 minVerificationScore
    ) external returns (bytes32 policyHash);

    function executeAction(
        bytes32 policyHash,
        address target,
        uint256 value,
        bytes calldata data,
        uint256 nonce,
        bytes32 entropyCommitment,
        bytes calldata signature
    ) external returns (bool success, bytes32 auditEntryId);

    function revokePolicy(bytes32 policyHash, string calldata reason) external;

    function getPolicy(bytes32 policyHash) external view returns (
        address agent,
        address owner,
        uint256 maxValuePerTx,
        uint256 validUntil,
        bool isActive
    );
}

Audit Trail (Hash-Chained)

Each audit entry MUST include previousHash for integrity. Implementations MAY store entries off-chain (e.g. IPFS) with periodic Merkle roots anchored on-chain (for example, to ERC-8004’s Validation Registry).

Error Codes

error PolicyExpired(bytes32 policyHash, uint256 validUntil);
error ValueExceedsLimit(uint256 value, uint256 maxValue);
error InvalidSignature(address recovered, address expected);
error EntropyVerificationFailed(bytes32 commitment, bytes32 revealed);
error PolicyViolation(bytes32 policyHash, string reason);

Rationale

Separation of concerns: identity (ERC-8004) and verification (ERC-8126) decoupled from execution, with verification enforced via policy
policyHash in ERC-712 signatures binds actions immutably
Hash-chain audit provides tamper detection without full on-chain cost
Verification gating allows flexibility while encouraging trust standards like ERC-8126

This specification explores novel combinations of policy-bound signing, hash-chained auditing, and entropy commitments to enable verifiable agent autonomy under potentially hostile hosts, with open questions regarding gas-efficient audit roots, threshold-based containment mechanisms, and the enforcement of Censorship Resistant, Open Source, Private, and Secure (CROPS) properties in high-value agent scenarios.

Backwards Compatibility

Compatible with ERC-4337 wallets and existing standards. No breaking changes.

Security Considerations

Expiration checks and nonce uniqueness should be enforced to prevent replay attacks.
The hash-chained audit trail makes tampering detectable through broken hash links.
Host manipulation remains a probabilistic risk. For high-value agents, using multiple independent hosts is recommended to reduce this threat.
A recent verification via ERC-8126 with a low risk score is required before delegation. Special attention must be given to clean Wallet Verification (WV) results showing no signs of sanctions, mixer usage, bot-like patterns, rapid forwarding, or threat intelligence hits.
Wallets must reject or revoke delegations if the ERC-8126 Wallet Verification flags malicious activity (such as sanctioned funding, clustering with known bad actors, or strong automation indicators), even if the overall risk score appears acceptable.
User sovereignty must remain the highest priority. Designs should ensure users retain final control over their agents and actions, and avoid any mechanism that introduces blind trust or unaccountable intermediation.
The system should be designed with CROPS principles in mind: strong censorship resistance, verifiable security, and privacy preservation (minimizing on-chain data exposure through ERC-8126 gating).
Active containment mechanisms should be implemented where possible. These allow users to respond quickly to policy violations and help preserve sovereignty.