Signer</th>	Digest</th>	`r</code></th>`	`s</code></th></tr></thead>`
`0x4a6f6B9fF1fc974096f9063a45Fd12bD5B928AD1</code></td>`	`0xb0922c37cafd247fe3ada4eb1d1e3735b7d2837437c1178e9af120d535214270</code></td>`	`0xdb7f75635124c807ec1f8b03e34cd76b633dc3a189e3c85fc5aee7e7d71df38c</code></td>`	`0x5f1e6c6edf21cacfc2acba2815b253b9048b894eec5aaf70343389bb596c48bc</code></td></tr>`
`0x4a6f6B9fF1fc974096f9063a45Fd12bD5B928AD1</code></td>`	`0xd92ff06caae7253883627416a425414d79e9003b91d6208add30e73735ef13c3</code></td>`	`0xaa40efd534ac7f96b85babd7df9228fa131e8523115ca1ebc025698c37f3867d</code></td>`	`0xa4b8d3c650fe62e46a563aed681bfdd44d50452fa7712bd139f2bfba3aed59c9</code></td></tr>`
`0x6B93E3bB9C0780C0f9042346Ffc379530a5882c1</code></td>`	`0xfa75eba87f076cf22489da7c53a651bb3869473f78d09d4814afb7ab2d54ed45</code></td>`	`0xaf4a877600ab6d14ebac626830cf1063d624487932b3cc73a7cd98ae7fbf337f</code></td>`	0xbc41d29acfcd3a1e7b5cb2dde1b85fe8882739312639b5f16d476a87584c040f</code></td></tr> </tbody></table> Reference Implementation</h2> pragma</span> solidity</span> ^0.8.30</span>;</span></span> </span> library</span> BoundSignatures</span> {</span></span> function</span> recover</span>(</span>bytes32</span> digest</span>,</span> bytes32</span> r</span>,</span> bytes32</span> s</span>)</span> internal</span> pure</span> returns</span> (</span>address</span> signer</span>)</span> {</span></span> signer </span>=</span> ecrecover</span>(</span>digest</span>,</span> 27</span>,</span> r</span>,</span> s</span>)</span>;</span></span> require</span>(</span>signer </span>!=</span> address</span>(</span>0</span>)</span>)</span>;</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> Bound signatures are recoverable and not malleable.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Diamonds, Simplified 2025-12-21T00:00:00+00:00 Abstract</h2> A diamond is a proxy contract that delegatecall</code>s to multiple implementation contracts called facets.</p> </p> Diamond contracts were originally standardized by ERC-2535</a>. This standard refines that specification by simplifying terminology, reducing the implementation complexity of introspection functions, and standardizing specific events.</p> This standard preserves the full capabilities of diamond contracts while reducing complexity. It also specifies an optional upgrade path for existing ERC-2535 diamonds.</p> Motivation</h2> Motivation for Diamond Contracts</h3> Through a single contract address, a diamond provides functionality from multiple implementation contracts (facets). Each facet is independent, yet facets can share internal functions and storage. This architecture allows large smart-contract systems to be composed from separate facets and presented as a single contract, simplifying deployment, testing, and integration with other contracts, off-chain software, and user interfaces.</p> By decomposing large smart contracts into facets, diamonds can reduce complexity and make systems easier to reason about. Distinct areas of functionality can be isolated, organized, tested, and managed independently.</p> Diamonds combine the single-address convenience of a monolithic contract with the modular flexibility of distinct, integrated contracts.</p> This architecture is well suited to immutable</strong> smart-contract systems, where all functionality is composed from multiple facets at deployment time and permanently fixed thereafter.</p> For upgradeable systems, diamonds enable incremental development: new functionality can be added, and existing functionality modified, without redeploying unaffected facets.</p> Additional motivation and background for diamond-based smart-contract systems can be found in ERC-1538</a> and ERC-2535</a>.</p> Motivation for this Standard</h3> Unlike monolithic contracts, a diamond's external functions are commonly determined by runtime routing (selector → facet mapping) rather than being wholly represented in the diamond's source code or bytecode. To accurately determine or display the full set of functionality a diamond has, tooling must rely on standardized introspection functions and events.</p> Block explorers, indexers, development tools, and user interfaces need a standard way to inspect which functions and facets a diamond possesses. Additionally, tooling can be built to reconstruct and display the full development or upgrade history of diamond contracts using event logs.</p> ERC-2535 standardized introspection functions and events. ERC-8109</a> re-standardizes these to make diamond contracts easier to implement and easier to understand.</p> ERC-8109 improves upon ERC-2535 Diamonds in the following ways:</p> Simplified terminology.</li> Fewer and simpler to implement introspection functions.</li> Replaces a single monolithic event, with per-function events. This makes it easier to implement a variety of functions that add, replace and remove functions in a diamond. It also makes it easier for tools to search for and process events.</li> </ol> Specification</h2> Terms</h3> A diamond</strong> is a smart contract that routes external function calls to one or more implementation contracts, referred to as facets. A diamond is stateful: all persistent data is stored in the diamond’s contract storage. A diamond implements the requirements in the Implementation Requirements</a> section.</li> A facet</strong> is a smart contract that defines one or more external functions. A facet is deployed independently, and one or more of its functions are added to one or more diamonds. A facet’s functions are executed in the diamond’s context via delegatecall</code>, so reads/writes affect the diamond’s storage. The term facet is derived from the diamond industry, referring to a flat surface of a diamond.</li> An introspection function</strong> is a function that returns information about the facets and functions used by a diamond.</li> For the purposes of this specification, a mapping</strong> refers to a conceptual association between two items and does not refer to a specific implementation.</li> </ol> Diamond Diagram</h3> This diagram shows the structure of a diamond.</p> It shows that a diamond has a mapping from function to facet and that facets can access the storage inside a diamond.</p> </p> Fallback</h3> When an external function is called on a diamond, its fallback function is executed. The fallback function determines which facet to call based on the first four bytes of the calldata (known as the function selector) and executes the function from the facet using delegatecall</code>.</p> A diamond’s fallback function and delegatecall</code> enable a diamond to execute a facet’s function as if it was implemented by the diamond itself. The msg.sender</code> and msg.value</code> values do not change and only the diamond’s storage is read and written to.</p> Here is an example of how a diamond’s fallback function might be implemented:</p> error</span> FunctionNotFound</span>(</span>bytes4</span> _selector</span>)</span>;</span></span> </span> //</span> Executes function call on facet using `delegatecall`.</span></span> //</span> Returns function call return data or revert data.</span></span> fallback</span>(</span>)</span> external</span> payable</span> {</span></span> //</span> Get facet address from function selector</span></span> address</span> facet </span>=</span> selectorToFacet</span>[</span>msg</span>.</span>sig</span>]</span>;</span></span> if</span> (</span>facet </span>==</span> address</span>(</span>0</span>)</span>)</span> {</span></span> revert</span> FunctionNotFound</span>(</span>msg</span>.</span>sig</span>)</span>;</span></span> }</span></span> //</span> Execute external function on facet using `delegatecall` and return any value.</span></span> assembly</span> {</span></span> //</span> Copy function selector and any arguments from calldata to memory.</span></span> calldatacopy</span>(</span>0</span>,</span> 0</span>,</span> calldatasize</span>(</span>)</span>)</span></span> //</span> Execute function call using the facet.</span></span> let</span> result </span>:=</span> delegatecall</span>(</span>gas</span>(</span>)</span>,</span> facet</span>,</span> 0</span>,</span> calldatasize</span>(</span>)</span>,</span> 0</span>,</span> 0</span>)</span></span> //</span> Copy all return data from the previous call into memory.</span></span> returndatacopy</span>(</span>0</span>,</span> 0</span>,</span> returndatasize</span>(</span>)</span>)</span></span> //</span> Return any return value or error back to the caller.</span></span> switch result</span></span> case </span>0</span> {</span>revert</span>(</span>0</span>,</span> returndatasize</span>(</span>)</span>)</span>}</span></span> default </span>{</span>return</span> (</span>0</span>,</span> returndatasize</span>(</span>)</span>)</span>}</span></span> }</span></span> }</span></span></code></pre>Function Not Found</h4> If the fallback function cannot find a facet for a function selector, and there is no default function or other mechanism to handle the call, the fallback MUST revert with the error FunctionNotFound(bytes4 _selector)</code>.</p> Events</h3> Adding/Replacing/Removing Functions</h4> These events are REQUIRED.</p> For each function selector that is added, replaced, or removed, the corresponding event MUST be emitted.</p> /*</span></span> </span>@notice</span> Emitted when a function is added to a diamond.</span></span> </span></span> </span>@param</span> _selector</span> The function selector being added.</span></span> * </span>@param</span> _facet</span> The facet address that will handle calls to `_selector`.</span></span> /</span></span> event</span> DiamondFunctionAdded</span>(</span>bytes4</span> indexed</span> _selector</span>, </span>address</span> indexed</span> _facet</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> Emitted when changing the facet that will handle calls to a function.</span></span> * </span></span> * </span>@param</span> _selector</span> The function selector being affected.</span></span> * </span>@param</span> _oldFacet</span> The facet address previously responsible for `_selector`.</span></span> * </span>@param</span> _newFacet</span> The facet address that will now handle calls to `_selector`.</span></span> /</span></span> event</span> DiamondFunctionReplaced</span>(</span></span> bytes4</span> indexed</span> _selector</span>,</span></span> address</span> indexed</span> _oldFacet</span>,</span></span> address</span> indexed</span> _newFacet</span></span> )</span>;</span></span> </span> /</span></span> </span>@notice</span> Emitted when a function is removed from a diamond.</span></span> </span></span> </span>@param</span> _selector</span> The function selector being removed.</span></span> * </span>@param</span> _oldFacet</span> The facet address that previously handled `_selector`.</span></span> /</span></span> event</span> DiamondFunctionRemoved</span>(</span></span> bytes4</span> indexed</span> _selector</span>, </span></span> address</span> indexed</span> _oldFacet</span></span> )</span>;</span></span></code></pre>Recording Non-Fallback delegatecall</code>s</h4> This event is OPTIONAL.</p> This event can be used to record delegatecall</code>s made by a diamond.</p> This event MUST NOT be emitted for delegatecall</code>s made by a diamond’s fallback function when routing calls to facets. It is only intended for delegatecall</code>s made by functions in facets or a diamond’s constructor.</p> This event enables tracking of changes to a diamond’s contract storage caused by delegatecall</code> execution.</p> /</span></span> </span>@notice</span> Emitted when a diamond's constructor function or function from a</span></span> * facet makes a `delegatecall`. </span></span> * </span></span> * </span>@param</span> _delegate</span> The contract that was the target of the `delegatecall`.</span></span> * </span>@param</span> _delegateCalldata</span> The function call, including function selector and </span></span> * any arguments.</span></span> /</span></span> event</span> DiamondDelegateCall</span>(</span>address</span> indexed</span> _delegate</span>, </span>bytes</span> _delegateCalldata</span>)</span>;</span></span></code></pre>Diamond Metadata</h4> This event is OPTIONAL.</p> This event can be used to record versioning or other information about diamonds.</p> It can be used to record information about diamond upgrades.</p> /</span></span> </span>@notice</span> Emitted to record information about a diamond.</span></span> * </span>@dev</span> This event records any arbitrary metadata. </span></span> * The format of `_tag` and `_data` are not specified by the </span></span> * standard.</span></span> </span></span> </span>@param</span> _tag</span> Arbitrary metadata, such as a release version.</span></span> * </span>@param</span> _data</span> Arbitrary metadata.</span></span> /</span></span> event</span> DiamondMetadata</span>(</span>bytes32</span> indexed</span> _tag</span>, </span>bytes</span> _data</span>)</span>;</span></span></code></pre>Inspecting Diamonds</h3> Diamond introspection functions return information about what functions and facets are used in a diamond.</p> These functions MUST be implemented and are required by the standard:</p> /</span> @notice</span> Gets the facet that handles the given selector.</span></span> </span></span> * </span>@dev</span> If facet is not found return address(0).</span></span> * </span>@param</span> _functionSelector</span> The function selector.</span></span> * </span>@return</span> The</span> facet address associated with the function selector.</span></span> /</span></span> function</span> facetAddress</span>(</span>bytes4</span> _functionSelector</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span> </span> struct</span> FunctionFacetPair</span> {</span></span> bytes4</span> selector</span>;</span></span> address</span> facet</span>;</span></span> }</span></span> </span> /</span></span> </span>@notice</span> Returns an array of all function selectors and their </span></span> * corresponding facet addresses.</span></span> </span></span> </span>@dev</span> Iterates through the diamond's stored selectors and pairs</span></span> * each with its facet.</span></span> * </span>@return</span> pairs</span> An array of `FunctionFacetPair` structs, each containing</span></span> * a selector and its facet address.</span></span> /</span></span> function</span> functionFacetPairs</span>(</span>)</span> external</span> view</span> returns</span>(</span>FunctionFacetPair</span>[</span>]</span> memory</span> pairs</span>)</span>;</span></span></code></pre> The essence of a diamond is its function -> facet</code> mapping. functionFacetPairs()</code> returns that mapping as an array of (selector, facet)</code> pairs.</p> These functions were chosen because they provide all necessary facet and function data about a diamond. They are very simple to implement and are computationally efficient.</p> Block explorers, GUIs, tests, and other tools may rely on their presence.</p> A reference implementation exists for these introspection functions here: DiamondInspectFacet.sol</a></p> Other introspection functions may be added to a diamond. The above two functions are the only ones required by this standard.</p> Implementation Requirements</h3> A diamond MUST implement the following:</p> Diamond Structure</strong> A diamond MUST implement a fallback()</code> function.</li> </ul> </li> Function Association</strong> A diamond MUST associate function selectors with facet addresses.</li> </ul> </li> Function Execution</strong> When an external function is called on a diamond: The diamond’s fallback function is executed.</li> The fallback function MUST find the facet associated with the function selector.</li> The fallback function MUST execute the function on the facet using delegatecall</code>.</li> If no facet is associated with the function selector, the diamond MAY execute a default function or apply another handling mechanism.</li> If no facet, default function, or other handling mechanism exists, execution MUST revert with the error FunctionNotFound(bytes4 _selector)</code>.</li> </ul> </li> </ul> </li> Events</strong> The following events MUST be emitted: DiamondFunctionAdded</code> — when a function is added to a diamond.</li> DiamondFunctionReplaced</code> — when a function is replaced in a diamond.</li> DiamondFunctionRemoved</code> — when a function is removed from a diamond.</li> </ul> </li> </ul> </li> Introspection</strong> A diamond MUST implement the following introspection functions: facetAddress(bytes4 _functionSelector)</code></li> functionFacetPairs()</code></li> </ul> </li> </ul> </li> </ol> receive()</code> function</h3> A diamond MAY have a receive()</code> function.</p> Immutable Functions</h3> Definition:</p> An immutable function is an external or public function defined directly in a diamond contract, not in a facet. This definition does not apply to a diamond's constructor or the special fallback()</code> and receive()</code> functions.</p> </blockquote> A diamond can have zero or more immutable functions.</p> A diamond with immutable functions has the following additional requirements that MUST be followed:</p> The DiamondFunctionAdded</code> event MUST be emitted for each immutable function.</li> Immutable functions MUST be returned by the introspection functions facetAddress(bytes4 _functionSelector)</code> and functionFacetPairs()</code>, where the facet address is the diamond’s own address.</li> Any upgrade function MUST revert on an attempt to replace or remove an immutable function.</li> </ol> Rationale</h2> This standard provides standard events and introspection functions so that GUIs, block explorers, command line programs, and other tools and software can detect and interoperate with diamond contracts.</p> Software can retrieve function selectors and facet addresses from a diamond in order to use and show what functions a diamond has. Function selectors and facet addresses, combined with contract ABIs and verified source code, provide sufficient information for tooling and user interfaces.</p> ERC-8109 Diamonds vs ERC-2535 Diamonds</h3> This standard is a simplification and refinement of ERC-2535 Diamonds.</p> A diamond compliant with ERC-8109 is NOT required to implement ERC-2535.</p> Here are changes in ERC-8109 Diamonds:</p> Simplified terminology.</li> Simplified introspection functions.</li> Standardized events that are simpler to use and consume.</li> Optional upgrade path for existing ERC-2535 diamonds.</li> </ul> Diamond Upgrades</h3> This standard does not specify an upgrade function.</p> This means several things:</p> 1. Diamonds Can Be Immutable</h4> A Diamond does not have to have an upgrade function.</p> A diamond can be fully constructed within its constructor function without adding any upgrade function, making it immutable upon deployment.</p> </li> A large immutable diamond can be built using well organized facets.</p> </li> A diamond can initially be upgradeable, and later made immutable by removing its upgrade function.</p> </li> </ul> 2. Other Standards Can Build on ERC-8109</h4> Other standards can build on ERC-8109 by specifying an upgrade function(s), while remaining compliant with this standard.</p> 3. You Can Create Your Own Upgrade Functions</h4> You can design and create your own upgrade functions and remain compliant with this standard. All that is required is that you emit the appropriate add/replace/remove required events specified in the events section</a>, and that the introspection functions defined in the Inspecting Diamonds section</a> continue to accurately return function and facet information.</p> Gas Considerations</h3> Routing calls via delegatecall</code> introduces a small amount of gas overhead. In practice, this cost is mitigated by several architectural and tooling advantages enabled by diamonds:</p> Optional, gas-optimized functionality</strong> By structuring functionality across multiple facets, diamonds make it straightforward to include specialized, gas-optimized features without increasing the complexity of core logic. For example, an ERC-721</a> diamond may implement batch transfer functions in a dedicated facet, improving both gas efficiency and usability while keeping the base ERC-721 implementation simple and well-scoped.</p> </li> Reduced external call overhead</strong> Some contract architectures require multiple external calls within a single transaction. By consolidating related functionality behind a single diamond address, these interactions can execute internally with shared storage and shared authorization, reducing gas costs from external calls and repeated access-control checks.</p> </li> Selective optimization per facet</strong> Because facets are compiled and deployed independently, they may be built with different compiler optimizer settings. This allows gas-critical facets to use aggressive optimization configurations to reduce execution costs, without increasing bytecode size or compilation complexity for unrelated functionality.</p> </li> </ol> functionFacetPairs()</code> Gas Usage</h3> The functionFacetPairs()</code> function is meant to be called off-chain. At this time major RPC providers have a maximum gas limit of about 550 million gas. Gas benchmark tests show that the functionFacetPairs()</code> function can return 60,000 (selector, facet)</code> pairs using less gas than that.</p> ERC-8109 implementations are free to add iteration or pagination-based introspection functions, but they are not required by this standard.</p> Storage Layout</h3> Diamonds and facets need to use a storage layout organizational pattern because Solidity’s default storage layout doesn’t support proxy contracts or diamonds. The storage layout technique or pattern to use is not specified in this ERC. However, examples of storage layout patterns that work with diamonds are ERC-8042 Diamond Storage</a> and ERC-7201 Namespaced Storage Layout</a>.</p> Facets Sharing Storage & Functionality</h3> Facets are separately deployed, independent units, but can share state and functionality in the following ways:</p> Facets can share state variables by using the same structs at the same storage positions.</li> Facets can share internal functions by importing them or inheriting contracts.</li> </ul> On-chain Facets can be Reused and Composed</h3> A deployed facet can be used by many diamonds.</p> It is possible to create and deploy a set of facets that are reused by different diamonds.</p> The ability to use the same deployed facets for many diamonds has the potential to reduce development time, increase reliability and security, and reduce deployment costs.</p> It is possible to implement facets in a way that makes them usable/composable/compatible with other facets.</p> Function Signature Limitation</h3> A function signature is the name of a function and its parameter types. Example function signature: myfunction(uint256)</code>. A limitation is that two external functions with the same function signature can’t be added to the same diamond at the same time because a diamond, or any contract, cannot have two external functions with the same function signature.</p> Immutable Functions Considerations</h3> Immutable functions offer minor gas savings by avoiding fallback logic and a delegatecall</code>. However, they introduce a second implementation alongside facets, resulting in two ways to provide similar functionality. This increases implementation complexity and cognitive overhead.</p> A diamond is simpler to implement and understand without immutable functions.</p> In upgradeable diamonds, immutable functions reduce flexibility, as they cannot be replaced or removed. This limits the ability to evolve, fix, or improve functionality over time.</p> Immutable functions that read from or write to storage are not isolated from upgrades. Other functions, including upgrade logic, may modify the same storage relied upon by immutable functions.</p> Backwards Compatibility</h2> Existing, deployed ERC-2535 Diamonds implementations MAY upgrade to this standard by performing an upgrade that does the following:</p> Removes the existing upgrade function and adds a new upgrade function that uses the new events.</li> Adds the new functionFacetPairs()</code> introspection function.</li> Emits a DiamondFunctionAdded</code> event for every function currently in the diamond, including the new upgrade function and the new functionFacetPairs()</code> function.</li> </ol> Any other upgrade details are implementation specific.</p> After this upgrade, the diamond is considered compliant with this standard and SHOULD be indexed and treated as a diamond of this standard going forward.</p> This upgrade acts as a 'state snapshot'. Indexers only interested in the current state of the diamond can start indexing from this transaction onwards, without needing to parse the legacy DiamondCut</code> history.</p> To reconstruct the complete upgrade history requires retrieving all the past DiamondCut</code> events as well as all new events defined in this standard.</p> ERC-2535 Diamonds with Immutable Functions</h3> An ERC-2535 diamond that upgrades to this standard and has immutable functions MUST comply with the Immutable Functions</a> section of the Specification.</p> If the ERC-2535 diamond upgrade function is immutable, then it can't be removed. If possible, disable the upgrade function by making its authentication always fail.</p> Reference Implementation</h2> The reference implementation for the facetAddress(bytes4 _functionSelector)</code> and functionFacetPairs()</code> introspection functions is here: DiamondInspectFacet.sol</a></li> An example implementation of an ERC-8109 diamond is here: DiamondExample.sol</a></li> </ul> Security Considerations</h2> Ownership and Authentication</h3> The design and implementation of diamond ownership/authentication is not part of this standard.</p> It is possible to create many different authentication or ownership schemes with diamonds. Authentication schemes can be very simple or complex, fine grained or coarse. This proposal does not limit it in any way. For example ownership/authentication could be as simple as a single account address having the authority to add/replace/remove functions. Or a decentralized autonomous organization could have the authority to add/replace/remove certain functions.</p> The development of standards and implementations of ownership, control and authentication of diamonds is encouraged.</p> Transparency</h3> A diamond emits an event every time a function is added, replaced or removed. Source code can be verified. This enables people and software to monitor changes to a diamond.</p> Security and domain experts can review a diamond's upgrade history.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Domain Architecture for Diamonds 2025-12-20T00:00:00+00:00 Abstract</h2> This standard introduces a domain-based architectural pattern</strong> for contracts implementing the Diamond execution model defined by ERC-2535 (Diamond Standard)</a> or ERC-8109 (Diamond, Simplified)</a>, together with the storage identifier mechanism defined by ERC-8042 (Diamond Storage Identifier)</a>.</p> It defines a domain-centric storage management architecture, providing consistent storage identifiers and a structured directory model that decouples storage ownership from facet logic.</p> This pattern helps reduce storage collisions and human error while enabling better tooling for multi-facet systems.</p> Motivation</h2> ERC-2535 provides a flexible foundation for modular smart contracts through facets, but it intentionally leaves storage organization and architectural conventions open to implementation. While this flexibility encourages creativity, it can sometimes lead to inconsistency. Each developer or team may structure storage differently, making it harder to design robust and easy-to-use tooling for storage management.</p> Without a shared structural framework, storage identifiers may be inconsistently verified or reused across facets, which can result in unexpected collisions or subtle upgrade issues between facets sharing the same state.</p> ERC-8042 introduced human-readable storage identifiers to improve clarity, but it does not define how those identifiers should be structured or grouped in larger projects.</p> This EIP proposes a domain-centric architectural pattern that establishes a consistent framework for managing storage independently of facet implementation.</p> By introducing clear domain boundaries and deterministic naming rules for storage identifiers, the pattern maintains the openness of the Diamond Standard while providing a shared foundation for collaboration, tooling support, and long-term upgrade safety across complex systems.</p> Specification</h2> 1. Domain Definition</h3> A domain</strong> represents the conceptual ownership of a storage space.</p> </li> Each domain</strong> corresponds to exactly one storage struct and one identifier.</p> </li> A domain</strong> has a one-to-many relationship with the group of function selectors that access it.</p> </li> A domain</strong> is independent of facets, multiple facets MAY read or modify the same domain.</p> </li> Domains</strong> SHOULD be defined according to business or system responsibility, not by facet name.</p> </li> </ul> 2. Storage Identifier Naming Convention</h3> A storage identifier is the human-readable string whose keccak256 hash defines a Diamond Storage position.</p> bytes32</span> constant</span> STORAGE_POSITION </span>=</span> keccak256</span>(</span>"meaningful.string"</span>)</span>;</span></span></code></pre> It represents the domain that owns and manages a specific storage layout. To ensure uniqueness and clarity, at a minimum, a storage identifier SHOULD include the following components:</p> {project}.{domain-name}.{version}</span></span></code></pre> To improve readability, namespace separation, and tooling support, additional contextual components MAY be included, resulting in the following extended format:</p> {org}.{project}.{domain-type}.{domain-name}.{version}</span></span></code></pre>Identifier Components</h3> org</code> Optional organization or author prefix (e.g., eth</code>, vag</code>, safe</code>)</p> </li> project</code> Project or protocol name</p> </li> domain-type</code> Optional classification of the domain. If present, it SHOULD be one of:</p> diamond</code> — core Diamond protocol domains, such as upgrade, introspection, and ownership.</p> </li> system</code> — shared system-level domains providing cross-cutting functionality. (e.g., reentrancy, pause, access control)</p> </li> business</code> — application-specific domains. (tokens, guards, modules)</p> </li> </ul> </li> domain-name</code> Lowercase keyword identifying the storage domain</p> </li> version</code> Optional storage layout version identifier</p> The initial storage layout is conceptually treated as v1</code>.</p> </li> If omitted, the identifier refers to this initial (v1</code>) storage layout for backward compatibility.</p> </li> v2</code>, v3</code>, … MUST be used for layout-breaking changes.</p> </li> The version MUST be incremented only when the storage layout is no longer append-only.</p> </li> </ul> </li> </ul> Each domain:</strong></p> MUST have one</strong> storage struct and one</strong> identifier.</p> </li> SHOULD be implemented in a dedicated directory named after the domain.</p> </li> If new fields are added to a storage struct, they MUST be added only at the end, and the struct MUST remain append-only.</p> </li> </ul> Sub-domain Components</h3> A sub-domain represents a storage-isolated vertical extension of an existing domain.</p> A sub-domain is used when new functionality belongs conceptually to an existing domain, but its required state can be cleanly isolated without modifying or appending to the original domain’s storage layout.</p> If present, the sub-domain's identifier format becomes:</p> {project}.{domain-name}.{version}.{sub-domain}</span></span></code></pre> or, when using the extended format:</p> {org}.{project}.{domain-type}.{domain-name}.{version}.{sub-domain}</span></span></code></pre> The version component indicates the domain version in which the sub-domain was introduced. It serves as a historical and organizational reference, not as an independent versioning lifecycle for the sub-domain.</p> Definition and Rules</strong></p> A sub-domain:</p> MUST define its own ERC-8042 storage identifier.</p> </li> MUST define its own storage layout</p> </li> MUST NOT modify or append to the parent domain’s storage.</p> </li> MUST remain conceptually subordinate to the parent domain.</p> </li> MUST share the same version context as the parent domain.</p> </li> SHOULD be placed alongside the parent domain’s storage definitions.</p> </li> </ul> Sub-domains exist as a safety-oriented design choice to isolate newly introduced state, while preserving the original domain layout unchanged.</p> Choosing between evolving the existing domain storage or introducing a sub-domain depends on the project’s complexity, the team’s discipline, and long-term maintenance goals.</p> 3. Storage Declaration Requirements</h3> To support reliable tooling and explicit storage ownership, each domain defined by this proposal MUST declare its storage location using the ERC-8042 NatSpec annotation.</p> Specifically, the domain-owned storage struct MUST be annotated with:</p> ///</span>@custom:storage</span>-location erc8042:<NAMESPACE_ID></span></span></code></pre> This proposal does not redefine the storage location formula, but requires the use of this annotation to ensure that domain storage is discoverable, unambiguous, and machine-readable.</p> Example Identifiers</h3> The extended identifier format is recommended for global uniqueness. It is especially useful when integrating shared libraries, predefined facets, or other standards, where namespace collisions are more likely.</p> For application-specific systems, teams may choose a minimal identifier format to reduce naming complexity, as long as the identifier remains stable and unique within the project.</p> Equipment Identifier</strong></p> Represents a business domain responsible for equipment state. This domain has undergone a layout-breaking change, therefore uses an explicit v2 identifier.</p> ///</span> @custom:storage</span>-location erc8042:org.project.business.equipment.v2</span></span> ///</span> @dev</span> Minimal form: project.equipment.v2</span></span> bytes32</span> constant</span> EQUIPMENT_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.business.equipment.v2"</span>)</span>;</span></span></code></pre> Character Identifier</strong></p> Represents a business domain responsible for character state and progression. This example also demonstrates how a domain can be extended using a storage-isolated sub-domain.</p> ///</span> @custom:storage</span>-location erc8042:org.project.business.character.v1</span></span> ///</span> @dev</span> Minimal form: project.character.v1</span></span> ///</span> @dev</span> Main character domain.</span></span> bytes32</span> constant</span> CHARACTER_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.business.character.v1"</span>)</span>;</span></span> </span> ///</span> @custom:storage</span>-location erc8042:org.project.business.character.v1.mounted</span></span> ///</span> @dev</span> Minimal form: project.character.v1.mounted</span></span> ///</span> @dev</span> Sub-domain for global character mounted state.</span></span> bytes32</span> constant</span> CHARACTER_MOUNTED_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.business.character.v1.mounted"</span>)</span>;</span></span></code></pre> Game Setting Identifier</strong></p> Defines a system-level domain for game-wide configuration shared across multiple facets.</p> ///</span> @custom:storage</span>-location erc8042:org.project.system.gamesettings</span></span> ///</span> @dev</span> Minimal form: project.gamesettings</span></span> bytes32</span> constant</span> GAME_SETTING_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.system.gamesettings"</span>)</span>;</span></span></code></pre>4. Directory Convention</h3> In line with Domain-Driven Design principles, the directory layout SHOULD reflect domain ownership.</p> Each domain defines a logical namespace for storage ownership</strong>. Directories are named after this namespace and serve as its physical representation in the codebase.</p> </li> Facets act as logic containers and do not own storage</strong>. They MAY reside alongside domain directories or reference domain-owned logic.</p> </li> Both directory names and storage identifiers SHOULD include domain information</strong>. This consistency allows tooling and precompilers to automatically associate selectors, domains, and storage layouts.</p> </li> Each domain SHOULD be represented by a dedicated directory</strong>. Within this directory, domain-owned logic such as storage layout definitions, internal helper logic, and any facets primarily associated with the domain MAY be organized under subdirectories as needed.</p> </li> This structure reduces the risk of storage collisions by design</strong>. The alignment of domain namespaces, directory layout, and storage identifiers allows file system constraints and static analysis tools to surface conflicts early and reason about upgrades proactively.</p> </li> </ul> Example Directory</h3> This directory structure is illustrative and does not mandate a specific naming convention.</em> Subdirectory names such as storage/</code> are illustrative and may contain both storage layout definitions and internal domain logic.</em></p> contracts/</span></span> ├── diamond/</span></span> │ └── Diamond.sol</span></span> │</span></span> ├── character/</span></span> │ ├── storage/</span></span> │ │ └── CharacterStorage.sol</span></span> │ └── facets/</span></span> │ └── CharacterFacet.sol</span></span> │</span></span> ├── equipment/</span></span> │ ├── storage/</span></span> │ │ └── EquipmentStorage.sol</span></span> │ └── facets/</span></span> │ └── EquipmentFacet.sol</span></span> │</span></span> └── gamesettings/</span></span> ├── storage/</span></span> │ └── GameSettingsStorage.sol</span></span> └── facets/</span></span> └── GameSettingsFacet.sol</span></span></code></pre>5. Upgrade Scenarios</h3> This architecture defines upgrade behavior based on the effect new selectors introduce to domains and storage</strong>, rather than on facets themselves.</p> Upgrades fall into one of the following cases.</p> Case 1: No new storage required</strong></p> If new selectors do not require any additional storage:</p> The selectors MAY be added to existing facets or new facets</li> The facet SHOULD be placed under an appropriate existing domain</li> No storage changes are required</li> </ul> This is the simplest and safest upgrade path, as it introduces no new state and does not affect existing storage layouts.</p> Case 2: New domain required (horizontal upgrade)</strong></p> If new functionality introduces state that does not logically belong to any existing domain:</p> A new domain MUST be defined</li> A new ERC-8042 storage identifier MUST be introduced</li> A new storage layout MUST be defined for that domain</li> The facet implementing this functionality SHOULD be placed under the new domain</li> </ul> This represents a horizontal expansion of the system, allowing new features to be introduced without impacting existing domains or storage layouts.</p> Case 3: New variables within an existing domain (vertical upgrade)</strong></p> If new selectors require additional state that logically belongs to an existing domain, and the existing storage layout is not broken, this becomes a design trade-off.</p> Two common approaches MAY be used:</p> Option A — Evolve the existing domain</strong></p> Append new variables to the end of the existing storage layout</li> Add new selectors to interact with the evolved domain</li> </ul> This keeps the domain unified and works well for tightly coupled or complex business logic. It requires strict discipline when managing storage layout.</p> Option B — Introduce a sub-domain</strong></p> Define a sub-domain under the existing domain</li> Introduce a new storage identifier and layout for the new variables</li> Leave the original domain storage unchanged</li> </ul> This approach reduces risk and cognitive load by isolating newly introduced state, while keeping the original domain layout stable.</p> The choice between these approaches depends on project complexity, team discipline, and long-term maintenance goals.</p> Case 4: Layout-breaking change</strong></p> If new selectors require a change that breaks the existing storage layout of a domain (for example, changing the inner structure of nested structs or struct arrays</em>)</p> A new, versioned storage identifier MUST be introduced</li> A new storage layout MUST be defined under that identifier</li> Any required data migration MUST be handled explicitly by the project</li> </ul> This architecture does not attempt to automate or abstract storage migration. The goal is to keep schema changes intentional, visible, and auditable.</p> If the layout-breaking change is partial</strong>, and the newly required state can be cleanly isolated and defined independently, developers MAY also consider introducing a sub-domain</strong> instead of versioning the entire domain.</p> Rationale</h2> From the beginning, the Diamond Standard (ERC-2535) was designed around the relationship between function selectors</strong> and storage positions</strong>, not around facets themselves. Facets are replaceable units of logic — the diamondCut</code> operation only replaces, removes or adds code — but the storage layout persists</strong> and defines the actual state continuity of the contract.</p> ERC-8109 itself only defines introspection mechanisms for querying the Diamond and deliberately leaves the upgrade mechanism to implementations or to other standards. This flexibility is achieved because both introspection facets and upgrade facets interact with the same underlying domain (8109.diamond</code>).</p> This demonstrates that storage belongs to the domain</strong>, not the facet, facets merely provide interfaces for logic to read or mutate that domain.</p> Over time, many implementations have treated facets as the primary boundary of responsibility, grouping logic and storage together without recognizing that storage domains</strong> are the true architectural anchors. This misunderstanding leads to inconsistent storage management, overlapping identifiers and fragile upgrade paths where one facet unintentionally corrupts another’s state.</p> The domain-centric approach</strong> restores the original intent of the Diamond: Selectors (facets) operate through</em> domains, not as</em> domains. Each domain defines its own persistent storage struct and identifier, while facets merely act as interfaces that execute logic against it.</p> This shift decouples storage from logic when separation is desired, while still allowing tightly coupled designs when intentional. It enables:</p> Independent evolution of business logic without rewriting storage.</li> Clear separation between reusable system components and app-specific domains.</li> A deterministic mapping between identifiers and state.</li> </ul> By formalizing this pattern, Diamond Architecture becomes safer, more transparent and easier to extend — re-aligning practice with its original design philosophy.</p> Special Case: Domain–Facet Overlap</h3> There is a special case within the separation principle where a domain (or sub-domain) and its facet are intentionally designed to represent the same logical entity.</p> In this scenario, the facet implements all functions belonging to its domain. This reduces flexibility, but improves encapsulation and self-containment, making the facet behave like a reusable application module rather than a low-level primitive.</p> A concrete example of this approach can be found in the Compose project</code>. In Compose, a facet and its associated sub-domain are explicitly mapped into a single entity, enabling the creation of predefined, plug-and-play standard facets.</p> This approach is suitable for systems that prioritize modular composition and standardized functionality, allowing developers to safely integrate common features with predictable behavior. However, when implementing custom or project-specific logic, domains and facets SHOULD still be treated as separate entities.</p> Maintaining this separation preserves clarity of ownership, supports future upgrades, and supports the long-term evolution of application-level Diamond architectures.</p> Sub-domains and Layout-Sensitive State</h3> Sub-domains can also serve as a practical way to isolate layout-sensitive state.</p> Projects that need to move quickly may choose to place complex or layout-unstable data (such as mappings or dynamic arrays) in a primary domain, while isolating smaller or more compact state in sub-domains.</p> As development progresses, additional state can either be appended to an existing domain or introduced via a sub-domain, depending on data shape and evolution needs.</p> This allows projects to start with a simple structure while preserving flexibility to refine storage organization as the system scales.</p> Isolated Domain</h3> An isolated domain describes a conceptual separation between a domain and function- or facet-level logic.</p> In this model, a domain defines its own storage access helpers. Facets and their functions interact with domain-owned state through these helpers, rather than accessing storage layouts directly.</p> This approach makes data access logic explicit at the domain level, while allowing facets to focus on business logic and coordination.</p> A domain may be fully isolated, partially isolated, or not isolated, depending on project needs.</p> This concept is particularly useful when functions or facets need to coordinate state across multiple domains or sub-domains, as it helps keep cross-domain interactions consistent and easier to reason about.</p> Backwards Compatibility</h2> This proposal is fully backward-compatible with ERC-2535 (Diamond Standard), ERC-8042 (Diamond Storage Identifier) and ERC-8109 (Diamond, Simplified). It introduces no breaking changes, no new opcodes, and no modifications to existing protocol mechanics.</p> It does not alter the execution model defined by ERC-2535 or ERC-8109. The relationships between facets, selectors, and shared storage remain unchanged and fully compatible across all three standards.</p> Instead, this proposal defines an architectural convention that complements existing Diamond standards by:</p> Reinforcing modularity and upgrade safety established by ERC-2535 and ERC-8109</li> Extending the human-readable storage identifier design introduced by ERC-8042</li> Providing a domain-based approach to storage ownership and organization</li> </ul> This architecture may be applied to contracts implementing either ERC-2535 or ERC-8109, as both share the same fundamental facet and selector architecture.</p> Developers are encouraged to continue following all applicable standards to maintain interoperability while benefiting from clearer state ownership, reduced storage collision risk, and lower architectural complexity.</p> Adoption for Deployed Systems</h3> For already deployed systems, adoption can be done incrementally.</p> The Domain Architecture does not require projects to modify, rename, or refactor existing libraries or other standards in order to adopt it. If a library or standard already follows ERC-2535, ERC-8042, or uses its own established storage identifiers, that code SHOULD remain unchanged.</p> Adoption MAY begin at the application layer, without touching shared libraries or standardized components. Existing storage identifiers MAY be treated conceptually as pre-v1 domains.</p> In practice, projects typically start by:</p> Defining clear domain boundaries</li> Organizing directories around domain responsibility</li> Grouping facets and their related storage by domain</li> Explicitly declaring storage ownership using the ERC-8042 @custom:storage-location</code> annotation</li> </ul> Adopting the Domain Architecture does not require migrating existing state. It primarily affects how new storage is introduced and how future upgrades are structured.</p> When a layout-breaking change is required, a new versioned storage identifier can be introduced explicitly, allowing existing storage layouts to remain untouched. Any data migration, if needed, MUST be handled explicitly by the project.</p> The primary consideration during adoption is identifier uniqueness. New storage identifiers MUST NOT collide with existing identifiers from shared libraries or from within the project itself.</p> Reference Implementation</h2> Minimal implementation examples demonstrating the convention:</p> Business Domain (Equipment)</strong></p> ///</span> @custom:storage</span>-location erc8042:org.project.business.equipment.v2</span></span> ///</span> @dev</span> Minimal form: project.equipment.v2</span></span> bytes32</span> constant</span> EQUIPMENT_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.business.equipment.v2"</span>)</span>;</span></span> </span> struct</span> Equipment</span> </span></span> {</span></span> uint8</span> itemType</span>;</span> </span></span> uint16</span> power</span>;</span></span> uint8</span> rarity</span>;</span></span> address</span> effectOwner</span>;</span> </span></span> }</span></span> </span> struct</span> EquipmentStorage</span> </span></span> {</span></span> mapping</span>(</span>uint256</span> =></span> Equipment</span>)</span> items</span>;</span> //</span> itemId => Equipment</span></span> }</span></span> </span> function</span> equipmentStorage</span>(</span>)</span> pure</span> returns</span> (</span>EquipmentStorage</span> storage</span> s</span>)</span> </span></span> {</span></span> bytes32</span> position </span>=</span> EQUIPMENT_STORAGE_POSITION</span>;</span></span> assembly</span> {</span></span> s</span>.</span>slot </span>:=</span> position</span></span> }</span></span> }</span></span></code></pre> Business Domain (Character)</strong></p> ///</span> @custom:storage</span>-location erc8042:org.project.business.character.v1</span></span> ///</span> @dev</span> Minimal form: project.character.v1</span></span> ///</span> @dev</span> Main character domain.</span></span> bytes32</span> constant</span> CHARACTER_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.business.character.v1"</span>)</span>;</span></span> </span> struct</span> Character</span> </span></span> {</span></span> uint32</span> level</span>;</span></span> uint256</span> hp</span>;</span></span> </span> //</span> equipment slot => itemId</span></span> //</span> e.g. slot: head, chest, weapon, boots...</span></span> mapping</span>(</span>uint8</span> =></span> uint256</span>)</span> equippedItemId</span>;</span></span> }</span></span> </span> struct</span> CharacterStorage</span> </span></span> {</span></span> mapping</span>(</span>uint256</span> =></span> Character</span>)</span> characters</span>;</span></span> }</span></span> </span> function</span> characterStorage</span>(</span>)</span> pure</span> returns</span> (</span>CharacterStorage</span> storage</span> s</span>)</span></span> {</span></span> bytes32</span> position </span>=</span> CHARACTER_STORAGE_POSITION</span>;</span></span> assembly</span> {</span></span> s</span>.</span>slot </span>:=</span> position</span></span> }</span></span> }</span></span> </span> ///</span> @custom:storage</span>-location erc8042:org.project.business.character.v1.mounted</span></span> ///</span> @dev</span> Minimal form: project.character.v1.mounted</span></span> ///</span> @dev</span> Sub-domain for global character mounted state.</span></span> bytes32</span> constant</span> CHARACTER_MOUNTED_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.business.character.v1.mounted"</span>)</span>;</span></span> </span> struct</span> CharacterMountedStorage</span> {</span></span> //</span> Global character state, persists across character switches</span></span> bool</span> isMounted</span>;</span></span> }</span></span> </span> function</span> characterMountedStorage</span>(</span>)</span> pure</span> returns</span> (</span>CharacterMountedStorage</span> storage</span> s</span>)</span></span> {</span></span> bytes32</span> position </span>=</span> CHARACTER_MOUNTED_STORAGE_POSITION</span>;</span></span> assembly</span> {</span></span> s</span>.</span>slot </span>:=</span> position</span></span> }</span></span> }</span></span></code></pre> System Domain (Game Settings)</strong></p> ///</span> @custom:storage</span>-location erc8042:org.project.system.gamesettings</span></span> ///</span> @dev</span> Minimal form: project.gamesettings</span></span> bytes32</span> constant</span> GAME_SETTING_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.system.gamesettings"</span>)</span>;</span></span> </span> struct</span> GameSettingStorage</span> {</span></span> uint256</span> balancePatchBlock</span>;</span></span> bytes32</span> rulesetHash</span>;</span></span> uint32</span> gameVersion</span>;</span></span> uint32</span> seasonId</span>;</span></span> bool</span> tradingEnabled</span>;</span></span> bool</span> craftingEnabled</span>;</span></span> bool</span> pvpEnabled</span>;</span></span> }</span></span> </span> function</span> gameSettingsStorage</span>(</span>)</span> pure</span> returns</span> (</span>GameSettingStorage</span> storage</span> s</span>)</span> {</span></span> bytes32</span> position </span>=</span> GAME_SETTING_STORAGE_POSITION</span>;</span></span> assembly</span> {</span></span> s</span>.</span>slot </span>:=</span> position</span></span> }</span></span> }</span></span></code></pre> Each domain defines and owns its storage independently. Facets interact with domain-owned storage definitions, supporting safe upgrades and avoiding unintended storage overlap.</p> Security Considerations</h2> This pattern strengthens the security model of Diamond-based systems by introducing explicit and deterministic storage identifiers.</p> By separating domains and enforcing consistent naming rules, it reduces the risk of:</p> Storage collisions between unrelated facets or upgrades.</li> Human errors caused by inconsistent or reused identifiers.</li> State corruption during upgrades or extensions.</li> </ul> Each domain owns its ERC-8042 storage identifier. When combined with append-only storage layout upgrades, this allows storage evolution without interfering with existing state.</p> This clarity also improves auditability and supports static analysis tooling when analyzing storage safety across upgrades.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> RWA Event-based Compliance Framework 2025-12-16T00:00:00+00:00 Abstract</h2> This standard defines an event-based compliance framework for Real World Asset (RWA) tokens on ERC-20</a>, providing:</p> A standardized entity classification system distinguishing between Compliance Entities (CE) and Decentralized Entities (DE)</li> Event-driven compliance observation enabling auditability through standardized events and actual value flows, without enforcing hard transaction reverts</li> </ol> This standard is intentionally minimal and does not prescribe business-specific RWA workflows, off-chain settlement mechanisms, minting policies, or specific transfer patterns.</p> Motivation</h2> Real World Asset tokenization requires compliance observability that existing ERC-20</a> tokens do not provide:</p> Missing Capabilities</h3> Entity Classification</strong>: No standardized way to distinguish regulated corporate entities from decentralized participants</li> Compliance Observability</strong>: No uniform event semantics for tracking compliance-relevant transfers</li> Flexible Enforcement</strong>: Existing standards use hard reverts, making them incompatible with diverse regulatory frameworks</li> </ol> Why Event-Based?</h3> This standard adopts an event-driven approach rather than enforcement through reverts:</p> Regulatory Flexibility</strong>: Different jurisdictions can interpret the same events differently</li> Adaptability</strong>: Compliance rules can evolve without contract upgrades</li> Lower Costs</strong>: Events are cheaper than state-based enforcement</li> </ul> Specification</h2> 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.</p> Definitions</h3> Compliance Entity (CE)</strong>: An address representing a regulated legal entity (e.g., corporate treasury, custody account)</li> Decentralized Entity (DE)</strong>: An address representing a decentralized participant (e.g., end users, routers, settlement contracts)</li> BizID</strong>: A business correlation identifier (hash) linking related transfers to a single workflow</li> Soft Policy</strong>: Compliance policy expressed through event labeling, not transaction reversion</li> </ul> Entity Registry</h3> Compliant implementations MUST provide an entity classification registry that assigns each address to one of three categories.</p> interface</span> IERC8106EntityRegistry</span> {</span></span> enum</span> EntityType</span> {</span> DECENTRALIZED_ENTITY</span>,</span> COMPLIANCE_ENTITY</span> }</span></span> </span> event</span> EntityTypeUpdated</span>(</span></span> address</span> indexed</span> entity</span>,</span></span> EntityType</span> entityType</span>,</span></span> bytes32</span> indexed</span> reasonHash</span>,</span></span> address</span> indexed</span> operator</span></span> )</span>;</span></span> </span> ///</span> @notice</span> Returns the entity type of an address</span></span> ///</span> @dev</span> MUST return DECENTRALIZED_ENTITY for addresses not explicitly registered as COMPLIANCE_ENTITY</span></span> function</span> entityTypeOf</span>(</span>address</span> entity</span>)</span> external</span> view</span> returns</span> (</span>EntityType</span>)</span>;</span></span> }</span></span></code></pre>Registry Requirements</h4> Implementations MUST satisfy the following requirements:</p> Default Classification</strong>: The entityTypeOf</code> function MUST return DECENTRALIZED_ENTITY</code> for any address not explicitly registered as COMPLIANCE_ENTITY</code></li> Explicit Registration</strong>: Only addresses explicitly registered SHOULD return COMPLIANCE_ENTITY</code></li> Update Events</strong>: Entity type changes MUST emit EntityTypeUpdated</code> events</li> Reason Tracking</strong>: The reasonHash</code> parameter MUST reference off-chain documentation (e.g., KYC records, legal entity registration)</li> Operator Accountability</strong>: The operator</code> parameter MUST identify the address that authorized the update</li> </ol> Implementation Note</h4> The registry MAY be:</p> Embedded within the token contract itself</li> Implemented as a separate contract referenced by the token</li> Shared across multiple tokens within an ecosystem</li> </ul> Compliance Events</h3> Compliant implementations MUST emit standardized events that capture compliance-relevant transfer information, including entity classifications, compliance flags, and business correlation identifiers.</p> interface</span> IERC8106ComplianceEvents</span> is</span> IERC8106EntityRegistry</span> {</span></span> enum</span> ComplianceFlag</span> {</span></span> OK</span>,</span></span> DIRECT_DE_TO_CE</span>,</span> //</span> DE -> CE observed</span></span> DIRECT_CE_TO_DE</span>,</span> //</span> CE -> DE observed</span></span> POLICY_CUSTOM</span> //</span> project-defined policy</span></span> }</span></span> </span> event</span> ComplianceObserved</span>(</span></span> bytes32</span> indexed</span> bizId</span>,</span></span> address</span> indexed</span> token</span>, </span>// </span>the</span> ERC</span>-</span>20</span> token</span> contract</span> address</span></span> address</span> indexed</span> from</span>,</span></span> address</span> to</span>,</span></span> uint256</span> amount</span>,</span></span> EntityType</span> fromType</span>,</span></span> EntityType</span> toType</span>,</span></span> ComplianceFlag</span> flag</span>,</span></span> bytes32</span> policyTag</span> // </span>project</span>-</span>defined</span> categorization</span> tag</span></span> )</span>;</span></span> }</span></span></code></pre>Event Requirements</h4> Implementations MUST satisfy the following requirements:</p> Complete Information</strong>: Each ComplianceObserved</code> event MUST include all specified parameters</li> Accurate Classification</strong>: The fromType</code> and toType</code> MUST reflect the actual entity types at the time of the transfer</li> Consistent BizID</strong>: All legs of a multi-leg transfer MUST use the same bizId</code> value</li> Token Identification</strong>: The token</code> parameter MUST be the address of the ERC-20</a> token contract</li> </ol> Recommended Flagging Policy (Non-normative)</h4> Implementations SHOULD apply the following flagging heuristics:</p> DIRECT_DE_TO_CE</code>: When fromType == DECENTRALIZED_ENTITY</code> and toType == COMPLIANCE_ENTITY</code></li> DIRECT_CE_TO_DE</code>: When fromType == COMPLIANCE_ENTITY</code> and toType == DECENTRALIZED_ENTITY</code></li> OK</code>: When transfer does not cross compliance boundaries (DE↔DE or CE↔CE)</li> POLICY_CUSTOM</code>: For project-specific compliance scenarios</li> </ul> Event-Based Compliance</h4> Implementations SHOULD NOT revert transactions solely based on compliance flags. This event-based approach enables:</p> Off-chain compliance review and decision-making</li> Flexible interpretation across different regulatory jurisdictions</li> Time-delayed enforcement where appropriate (e.g., 24-hour review periods)</li> </ul> Compliance actions (transaction reversals, account freezes, regulatory reporting) SHOULD be handled through separate mechanisms such as:</p> Off-chain monitoring systems</li> On-chain governance modules</li> Dedicated compliance management contracts</li> </ul> Rationale</h2> Event-Driven Model</h3> Events rather than reverts because:</p> Different jurisdictions can interpret events differently</li> Cheaper than state-based enforcement (~2000 gas per event vs state writes)</li> Enables time-delayed enforcement where appropriate</li> </ul> Soft Policy Flags</h3> Compliance flags are informational, not enforced:</p> Projects decide whether to revert based on flags</li> Off-chain systems can alert, review, or freeze post-transaction</li> Supports evolving regulations without contract changes</li> </ul> Auditability Design</h3> Auditors reconstruct transaction flows using:</p> Value Flows</strong>: Every ComplianceObserved</code> event corresponds to a real ERC-20</a> balance change</li> Standardized Events</strong>: Uniform event structure for machine-readable compliance data</li> BizID Correlation</strong>: Link multiple transfers to a single business transaction</li> </ol> For a given bizId</code>, auditors can query all ComplianceObserved</code> events, build directed graphs from from</code>/to</code>/amount</code> fields, check for direct CE/DE transfers using the flag</code> field, and cross-reference reasonHash</code> with off-chain KYC/AML systems.</p> Reference Implementation</h2> Implementation Patterns</h3> Embedded Registry</strong>: Store entity types in the token contract itself</p> contract</span> RWAToken</span> is</span> ERC20</span>, </span>IERC8106ComplianceEvents</span> {</span></span> mapping</span>(</span>address</span> =></span> bool</span>)</span> private</span> _isComplianceEntity</span>;</span></span> </span></span> function</span> entityTypeOf</span>(</span>address</span> entity</span>)</span> public</span> view</span> returns</span> (</span>EntityType</span>)</span> {</span></span> return</span> _isComplianceEntity</span>[</span>entity</span>]</span> </span></span> ?</span> EntityType</span>.</span>COMPLIANCE_ENTITY </span></span> :</span> EntityType</span>.</span>DECENTRALIZED_ENTITY</span>;</span></span> }</span></span> //</span> ...</span></span> }</span></span></code></pre> Separate Registry</strong>: Share registry across multiple tokens</p> contract</span> EntityRegistry</span> is</span> IERC8106EntityRegistry</span> {</span></span> mapping</span>(</span>address</span> =></span> bool</span>)</span> private</span> _isComplianceEntity</span>;</span></span> </span></span> function</span> entityTypeOf</span>(</span>address</span> entity</span>)</span> external</span> view</span> returns</span> (</span>EntityType</span>)</span> {</span></span> return</span> _isComplianceEntity</span>[</span>entity</span>]</span></span> ?</span> EntityType</span>.</span>COMPLIANCE_ENTITY</span></span> :</span> EntityType</span>.</span>DECENTRALIZED_ENTITY</span>;</span></span> }</span></span> </span></span> function</span> registerComplianceEntity</span>(</span>address</span> entity</span>,</span> bytes32</span> reasonHash</span>)</span> external</span> onlyAdmin</span> {</span></span> _isComplianceEntity</span>[</span>entity</span>]</span> =</span> true</span>;</span></span> emit</span> EntityTypeUpdated</span>(</span>entity</span>,</span> EntityType</span>.</span>COMPLIANCE_ENTITY</span>,</span> reasonHash</span>,</span> msg.sender</span>)</span>;</span></span> }</span></span> //</span> ...</span></span> }</span></span></code></pre> Policy Tag Conventions</strong>: Use consistent hashes for interoperability</p> bytes32</span> constant</span> TAG_PAYMENT </span>=</span> keccak256</span>(</span>"PAYMENT"</span>)</span>;</span></span> bytes32</span> constant</span> TAG_TREASURY </span>=</span> keccak256</span>(</span>"TREASURY"</span>)</span>;</span></span> bytes32</span> constant</span> TAG_REFUND </span>=</span> keccak256</span>(</span>"REFUND"</span>)</span>;</span></span></code></pre>Example Use Cases</h3> Compliance Monitoring:</strong> A regulated stablecoin tracks all CE↔DE flows for monthly regulatory reports without blocking transactions.</p> Atomic Multi-Leg Transfers:</strong> While not part of this standard, projects can build on these primitives to implement atomic multi-hop transfers:</p> //</span> User pays → Treasury → Operational account (single transaction)</span></span> function</span> purchaseRWA</span>(</span>bytes32</span> orderId</span>,</span> uint256</span> amount</span>)</span> external</span> {</span></span> //</span> Leg 1: DE → CE</span></span> token</span>.</span>transferFrom</span>(</span>msg.sender</span>,</span> treasury</span>,</span> amount</span>)</span>;</span></span> emit</span> ComplianceObserved</span>(</span>orderId</span>,</span> token</span>,</span> msg.sender</span>,</span> treasury</span>,</span> amount</span>,</span> </span></span> DE</span>,</span> CE</span>,</span> DIRECT_DE_TO_CE</span>,</span> TAG_PAYMENT</span>)</span>;</span></span> </span></span> //</span> Leg 2: CE → CE</span></span> token</span>.</span>transferFrom</span>(</span>treasury</span>,</span> operational</span>,</span> amount</span>)</span>;</span></span> emit</span> ComplianceObserved</span>(</span>orderId</span>,</span> token</span>,</span> treasury</span>,</span> operational</span>,</span> amount</span>,</span></span> CE</span>,</span> CE</span>,</span> OK</span>,</span> TAG_TREASURY</span>)</span>;</span></span> }</span></span></code></pre> This pattern enables single user-facing transactions, unified bizId</code> for audit correlation, and per-leg compliance events.</p> Time-Delayed Enforcement:</strong> Detect suspicious patterns in events, then freeze accounts off-chain or via governance after review.</p> Security Considerations</h2> Event Integrity:</strong> Implementations MUST emit ComplianceObserved</code> events only after actual ERC-20</a> balance changes. Emitting events without value movement compromises auditability.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> ENS Trust Registry for Agent Coordination 2025-12-16T00:00:00+00:00 Abstract</h2> This ERC defines a Trust Registry</strong> that enables agents to establish and query transitive trust relationships using ENS names as identifiers. Trust is expressed at four levels (Unknown, None, Marginal, Full) and propagates through signature chains following the GNU Privacy Guard (GnuPG) web of trust model.</p> The registry serves as the trust and delegation module</strong> anticipated by ERC-8001</a>, enabling coordinators to gate participation based on trust graph proximity. An agent is considered valid from a coordinator's perspective if sufficient trust paths exist between them.</p> This standard specifies trust attestation structures, the path verification algorithm, ENS integration semantics, and ERC-8001</a> coordination hooks.</p> Motivation</h2> ERC-8001</a> defines minimal primitives for multi-party agent coordination but explicitly defers trust to modules:</p> "Privacy, thresholds, bonding, and cross-chain are left to modules."</p> </blockquote> And in Security Considerations:</p> "Equivocation: A participant can sign conflicting intents. Mitigate with module-level slashing or reputation."</p> </blockquote> This ERC provides that trust and delegation module. Before coordinating, agents need answers to:</p> "Should I include this agent in my coordination?"</strong> — Participant selection</li> "Can I trust this agent's judgment about other agents?"</strong> — Transitive trust</li> "How do I update trust based on coordination outcomes?"</strong> — Trust maintenance</li> </ol> Why Web of Trust?</h3> The web of trust model, proven over 25+ years in GnuPG, solves the bootstrap problem: how do you establish trust with unknown agents without a centralised registrar?</p> GnuPG Concept</th> This Standard</th></tr></thead> Public key</td> ENS name</td></tr> Key signing</td> Trust attestation</td></tr> Owner trust levels</td> TrustLevel</code> enum</td></tr> Key validity</td> Agent validity for coordination</td></tr> Certification path</td> Trust chain through agents</td></tr> </tbody></table> Why ENS?</h3> ENS provides a battle-tested, finalized identity layer:</p> Stable identifiers</strong> that survive key rotation</li> Ownership semantics</strong> via owner()</code> and isApprovedForAll()</code></li> Human readable</strong> names (alice.agents.eth</code> not 0x742d...</code>)</li> Subdomain delegation</strong> for protocol-issued agent identities</li> </ul> Using ENS avoids dependency on draft identity standards while remaining compatible with future standards through adapter patterns.</p> Deployment note</strong>: This standard requires access to an ENS registry. On Ethereum mainnet, use the canonical ENS deployment. On other networks, use network-specific ENS deployments or bridges. CCIP-Read is a client-side mechanism and cannot be used for on-chain validation.</p> Identity Continuity</h3> ENS names are the identity. When an ENS name is transferred, the new owner inherits existing trust relationships where that name is the trustee. The new owner can manage trust where they are the trustor.</p> Implementations SHOULD use short expiries (RECOMMENDED: 90 days maximum) for high-stakes scopes to limit exposure from name transfers. Agents SHOULD monitor Transfer</code> events on ENS names they trust and re-evaluate trust accordingly.</p> Specification</h2> 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.</p> Overview</h3> This ERC specifies:</p> Trust levels and their semantics</li> ENS-indexed trust attestation structures with scope as key</li> EIP-712</a> typed data for signing attestations</li> EIP-1271</a> support for contract controllers</li> The ITrustRegistry</code> interface</li> Path verification algorithm</li> ERC-8001</a> integration hooks</li> </ul> Trust Levels</h3> Implementations MUST use the canonical enum:</p> enum</span> TrustLevel</span> {</span></span> Unknown</span>,</span> //</span> 0: No trust relationship established</span></span> None</span>,</span> //</span> 1: Explicitly distrusted</span></span> Marginal</span>,</span> //</span> 2: Partial trust — multiple required for validation</span></span> Full</span> //</span> 3: Complete trust — single attestation sufficient</span></span> }</span></span></code></pre> Semantic definitions:</strong></p> Level</th> Meaning</th> Validation Contribution</th></tr></thead> Unknown</code></td> Default state; no data about agent</td> Cannot contribute to validation</td></tr> None</code></td> Agent known to behave improperly</td> Explicitly excluded; voids trust paths containing this agent</td></tr> Marginal</code></td> Agent generally trustworthy</td> Contributes to validation when minEdgeTrust <= Marginal</code></td></tr> Full</code></td> Agent's judgment equals own verification</td> Always contributes to validation</td></tr> </tbody></table> Level transitions:</strong></p> Any level MAY transition to any other level via a valid attestation with a higher nonce</li> Transitioning from None</code> to Marginal</code> or Full</code> requires a new attestation (revocation is not permanent)</li> </ul> ENS Integration</h3> The Trust Registry uses ENS namehashes as agent identifiers.</p> //</span> ENS namehash computation (per ERC-137)</span></span> bytes32</span> node </span>=</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span></span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>bytes32</span>(</span>0</span>)</span>,</span> keccak256</span>(</span>"eth"</span>)</span>)</span>)</span>,</span></span> keccak256</span>(</span>"alice"</span>)</span></span> )</span>)</span>;</span></span> //</span> node = namehash("alice.eth")</span></span></code></pre>Signature Authority</h3> Trust attestations MUST be signed by an address with signing authority for the ENS name.</p> Signing authority</strong> is limited to:</p> The ENS name owner (ens.owner(node)</code>), OR</li> For contract owners: any signer the contract validates via EIP-1271</a></li> </ul> Transaction submission</strong> (calling setTrust</code>, revokeTrust</code>, etc.) MAY be performed by:</p> Any address holding a valid signature</li> An approved operator (ens.isApprovedForAll(owner, operator)</code>) for revokeTrust</code> only</li> </ul> This separation ensures:</p> Attestations are cryptographically bound to the ENS owner/controller</li> Transaction submission can be delegated (relayers, operators)</li> Approvals cannot be used to forge signatures</li> </ul> ///</span> @dev</span> Verify signature - signing authority is ENS owner only</span></span> function</span> verifySignature</span>(</span></span> bytes32</span> node</span>,</span></span> bytes32</span> digest</span>,</span></span> bytes</span> calldata</span> signature</span></span> )</span> internal</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span> address</span> owner </span>=</span> ens</span>.</span>owner</span>(</span>node</span>)</span>;</span></span> if</span> (</span>owner </span>==</span> address</span>(</span>0</span>)</span>)</span> return</span> false</span>;</span></span> </span> //</span> EOA owner</span></span> if</span> (</span>owner</span>.</span>code</span>.</span>length </span>==</span> 0</span>)</span> {</span></span> return</span> ECDSA</span>.</span>recover</span>(</span>digest</span>,</span> signature</span>)</span> ==</span> owner</span>;</span></span> }</span></span> </span> //</span> Contract owner - delegate to EIP-1271</span></span> try</span> IERC1271</span>(</span>owner</span>)</span>.</span>isValidSignature</span>(</span>digest</span>,</span> signature</span>)</span> returns</span> (</span>bytes4</span> magic</span>)</span> {</span></span> return</span> magic </span>==</span> IERC1271</span>.</span>isValidSignature</span>.</span>selector</span>;</span></span> }</span> catch</span> {</span></span> return</span> false</span>;</span></span> }</span></span> }</span></span> </span> ///</span> @dev</span> Check if caller can submit revokeTrust transaction</span></span> function</span> canSubmitRevocation</span>(</span>bytes32</span> node</span>,</span> address</span> caller</span>)</span> internal</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span> address</span> owner </span>=</span> ens</span>.</span>owner</span>(</span>node</span>)</span>;</span></span> return</span> caller </span>==</span> owner </span>\|\|</span> ens</span>.</span>isApprovedForAll</span>(</span>owner</span>,</span> caller</span>)</span>;</span></span> }</span></span></code></pre>EIP-712 Domain</h3> Implementations MUST use the following EIP-712</a> domain:</p> EIP712Domain</span>(</span>{</span></span> name</span>:</span> "TrustRegistry"</span>,</span></span> version</span>:</span> "1"</span>,</span></span> chainId</span>:</span> block</span>.</span>chainid</span>,</span></span> verifyingContract</span>:</span> address</span>(</span>this</span>)</span></span> }</span>)</span></span></code></pre> Implementations SHOULD expose the domain via EIP-5267</a>.</p> Primary Types</h3> struct</span> TrustAttestation</span> {</span></span> bytes32</span> trustorNode</span>;</span> //</span> ENS namehash of trustor</span></span> bytes32</span> trusteeNode</span>;</span> //</span> ENS namehash of trustee</span></span> TrustLevel level</span>;</span> //</span> Trust level assigned</span></span> bytes32</span> scope</span>;</span> //</span> Scope restriction; bytes32(0) = universal</span></span> uint64</span> expiry</span>;</span> //</span> Unix timestamp; 0 = no expiry</span></span> uint64</span> nonce</span>;</span> //</span> Per-trustor monotonic nonce</span></span> }</span></span> </span> struct</span> ValidationParams</span> {</span></span> uint8</span> maxPathLength</span>;</span> //</span> Maximum trust chain depth (1-10)</span></span> TrustLevel minEdgeTrust</span>;</span> //</span> Minimum trust level required on each edge</span></span> bytes32</span> scope</span>;</span> //</span> Required scope; bytes32(0) = any</span></span> bool</span> enforceExpiry</span>;</span> //</span> Check expiry on all chain elements</span></span> bytes32</span>[</span>]</span> requiredAnchors</span>;</span> //</span> Path MUST traverse at least one anchor; empty = no requirement</span></span> }</span></span> </span> struct</span> TrustPath</span> {</span></span> bytes32</span>[</span>]</span> nodes</span>;</span> //</span> [validator, ...intermediaries..., target]</span></span> }</span></span></code></pre> Path length definition</strong>: Path length is the number of edges (trust relationships) in the path. A direct trust relationship has path length 1. A path [A, B, C]</code> has length 2.</p> Default Validation Parameters</h4> When not specified, implementations SHOULD use:</p> ValidationParams</span>(</span>{</span></span> maxPathLength</span>:</span> 5</span>,</span></span> minEdgeTrust</span>:</span> TrustLevel</span>.</span>Marginal</span>,</span></span> scope</span>:</span> bytes32</span>(</span>0</span>)</span>,</span></span> enforceExpiry</span>:</span> true</span>,</span></span> requiredAnchors</span>:</span> new</span> bytes32</span>[](</span>0</span>)</span></span> }</span>)</span></span></code></pre>Validation Parameters Constraints</h4> Implementations MUST reject ValidationParams</code> where:</p> maxPathLength == 0</code> or maxPathLength > 10</code></li> minEdgeTrust == TrustLevel.Unknown</code> or minEdgeTrust == TrustLevel.None</code></li> requiredAnchors.length > 10</code></li> </ul> Typed Data Hashes</h3> bytes32</span> constant</span> TRUST_ATTESTATION_TYPEHASH </span>=</span> keccak256</span>(</span></span> "TrustAttestation(bytes32 trustorNode,bytes32 trusteeNode,uint8 level,bytes32 scope,uint64 expiry,uint64 nonce)"</span></span> )</span>;</span></span> </span> function</span> hashAttestation</span>(</span>TrustAttestation</span> calldata</span> att</span>)</span> internal</span> pure</span> returns</span> (</span>bytes32</span>)</span> {</span></span> return</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span> TRUST_ATTESTATION_TYPEHASH</span>,</span></span> att</span>.</span>trustorNode</span>,</span></span> att</span>.</span>trusteeNode</span>,</span></span> uint8</span>(</span>att</span>.</span>level</span>)</span>,</span></span> att</span>.</span>scope</span>,</span></span> att</span>.</span>expiry</span>,</span></span> att</span>.</span>nonce</span></span> )</span>)</span>;</span></span> }</span></span></code></pre>Interface</h3> Implementations MUST expose the following interface:</p> interface</span> ITrustRegistry</span> {</span></span> //</span> ═══════════════════════════════════════════════════════════════════</span></span> //</span> Events</span></span> //</span> ═══════════════════════════════════════════════════════════════════</span></span> </span> ///</span> @notice</span> Emitted when trust is set or updated</span></span> event</span> TrustSet</span>(</span></span> bytes32</span> indexed</span> trustorNode</span>,</span></span> bytes32</span> indexed</span> trusteeNode</span>,</span></span> TrustLevel</span> level</span>,</span></span> bytes32</span> indexed</span> scope</span>,</span></span> uint64</span> expiry</span></span> )</span>;</span></span> </span> ///</span> @notice</span> Emitted when trust is explicitly revoked</span></span> event</span> TrustRevoked</span>(</span></span> bytes32</span> indexed</span> trustorNode</span>,</span></span> bytes32</span> indexed</span> trusteeNode</span>,</span></span> bytes32</span> indexed</span> scope</span>,</span></span> bytes32</span> reasonCode</span></span> )</span>;</span></span> </span> ///</span> @notice</span> Emitted when an identity gate is configured</span></span> event</span> IdentityGateSet</span>(</span></span> bytes32</span> indexed</span> coordinationType</span>,</span></span> bytes32</span> indexed</span> gatekeeperNode</span>,</span></span> uint8</span> maxPathLength</span>,</span></span> TrustLevel</span> minEdgeTrust</span></span> )</span>;</span></span> </span> ///</span> @notice</span> Emitted when an identity gate is removed</span></span> event</span> IdentityGateRemoved</span>(</span>bytes32</span> indexed</span> coordinationType</span>)</span>;</span></span> </span> //</span> ═══════════════════════════════════════════════════════════════════</span></span> //</span> Trust Management</span></span> //</span> ═══════════════════════════════════════════════════════════════════</span></span> </span> ///</span> @notice</span> Set trust level for another agent in a specific scope</span></span> ///</span> @dev</span> Signature MUST be from ENS owner (EOA) or validate via EIP-1271 (contract)</span></span> ///</span> @param</span> attestation</span> The trust attestation</span></span> ///</span> @param</span> signature</span> EIP-712 signature from trustor's ENS owner</span></span> function</span> setTrust</span>(</span></span> TrustAttestation</span> calldata</span> attestation</span>,</span></span> bytes</span> calldata</span> signature</span></span> )</span> external</span>;</span></span> </span> ///</span> @notice</span> Batch set multiple trust relationships</span></span> ///</span> @dev</span> All attestations MUST share the same trustorNode</span></span> ///</span> @param</span> attestations</span> Array of trust attestations</span></span> ///</span> @param</span> signatures</span> Corresponding signatures</span></span> function</span> setTrustBatch</span>(</span></span> TrustAttestation</span>[</span>]</span> calldata</span> attestations</span>,</span></span> bytes</span>[</span>]</span> calldata</span> signatures</span></span> )</span> external</span>;</span></span> </span> ///</span> @notice</span> Revoke trust (sets level to None)</span></span> ///</span> @dev</span> Caller MUST be ENS owner or approved operator</span></span> ///</span> @param</span> trustorNode</span> The trustor's ENS namehash</span></span> ///</span> @param</span> trusteeNode</span> The agent to revoke trust from</span></span> ///</span> @param</span> scope</span> The scope to revoke trust in</span></span> ///</span> @param</span> reasonCode</span> Reason code for revocation</span></span> function</span> revokeTrust</span>(</span></span> bytes32</span> trustorNode</span>,</span></span> bytes32</span> trusteeNode</span>,</span></span> bytes32</span> scope</span>,</span></span> bytes32</span> reasonCode</span></span> )</span> external</span>;</span></span> </span> ///</span> @notice</span> Get trust record between two agents in a specific scope</span></span> ///</span> @param</span> trustorNode</span> The trusting agent</span></span> ///</span> @param</span> trusteeNode</span> The trusted agent</span></span> ///</span> @param</span> scope</span> The trust scope (bytes32(0) for universal)</span></span> ///</span> @return</span> level</span> Current trust level</span></span> ///</span> @return</span> expiry</span> Expiration timestamp (0 = never)</span></span> function</span> getTrust</span>(</span></span> bytes32</span> trustorNode</span>,</span></span> bytes32</span> trusteeNode</span>,</span></span> bytes32</span> scope</span></span> )</span> external</span> view</span> returns</span> (</span>TrustLevel</span> level</span>,</span> uint64</span> expiry</span>)</span>;</span></span> </span> ///</span> @notice</span> Get current nonce for a trustor</span></span> ///</span> @param</span> trustorNode</span> The agent's ENS namehash</span></span> ///</span> @return</span> Current</span> nonce value</span></span> function</span> getNonce</span>(</span>bytes32</span> trustorNode</span>)</span> external</span> view</span> returns</span> (</span>uint64</span>)</span>;</span></span> </span> //</span> ═══════════════════════════════════════════════════════════════════</span></span> //</span> Path Verification</span></span> //</span> ═══════════════════════════════════════════════════════════════════</span></span> </span> ///</span> @notice</span> Verify a pre-computed trust path</span></span> ///</span> @param</span> path</span> The trust path to verify</span></span> ///</span> @param</span> params</span> Validation parameters</span></span> ///</span> @return</span> valid</span> Whether the path satisfies validation requirements</span></span> ///</span> @return</span> anchorSatisfied</span> Whether requiredAnchors constraint is met</span></span> function</span> verifyPath</span>(</span></span> TrustPath</span> calldata</span> path</span>,</span></span> ValidationParams</span> calldata</span> params</span></span> )</span> external</span> view</span> returns</span> (</span>bool</span> valid</span>,</span> bool</span> anchorSatisfied</span>)</span>;</span></span> </span> //</span> ═══════════════════════════════════════════════════════════════════</span></span> //</span> ERC-8001 Integration</span></span> //</span> ═══════════════════════════════════════════════════════════════════</span></span> </span> ///</span> @notice</span> Set identity gate for a coordination type</span></span> ///</span> @param</span> coordinationType</span> The ERC-8001 coordination type</span></span> ///</span> @param</span> gatekeeperNode</span> Agent whose trust graph gates entry</span></span> ///</span> @param</span> params</span> Validation parameters for the gate</span></span> function</span> setIdentityGate</span>(</span></span> bytes32</span> coordinationType</span>,</span></span> bytes32</span> gatekeeperNode</span>,</span></span> ValidationParams</span> calldata</span> params</span></span> )</span> external</span>;</span></span> </span> ///</span> @notice</span> Remove identity gate for a coordination type</span></span> ///</span> @param</span> coordinationType</span> The ERC-8001 coordination type</span></span> function</span> removeIdentityGate</span>(</span>bytes32</span> coordinationType</span>)</span> external</span>;</span></span> </span> ///</span> @notice</span> Get identity gate configuration</span></span> ///</span> @param</span> coordinationType</span> The ERC-8001 coordination type</span></span> ///</span> @return</span> gatekeeperNode</span> The gatekeeper agent</span></span> ///</span> @return</span> params</span> Validation parameters</span></span> ///</span> @return</span> enabled</span> Whether the gate is active</span></span> function</span> getIdentityGate</span>(</span></span> bytes32</span> coordinationType</span></span> )</span> external</span> view</span> returns</span> (</span></span> bytes32</span> gatekeeperNode</span>,</span></span> ValidationParams</span> memory</span> params</span>,</span></span> bool</span> enabled</span></span> )</span>;</span></span> </span> ///</span> @notice</span> Validate participant using pre-computed path</span></span> ///</span> @param</span> coordinationType</span> The ERC-8001 coordination type</span></span> ///</span> @param</span> path</span> Pre-computed trust path from gatekeeper to participant</span></span> ///</span> @return</span> isValid</span> Whether participant passes the gate</span></span> function</span> validateParticipantWithPath</span>(</span></span> bytes32</span> coordinationType</span>,</span></span> TrustPath</span> calldata</span> path</span></span> )</span> external</span> view</span> returns</span> (</span>bool</span> isValid</span>)</span>;</span></span> }</span></span></code></pre>OPTIONAL Interface Extensions</h3> The following functions are OPTIONAL. Implementations MAY include them but they are not required for compliance:</p> interface</span> ITrustRegistryExtended</span> is</span> ITrustRegistry</span> {</span></span> ///</span> @notice</span> Get agents trusted by a given agent (paginated)</span></span> ///</span> @dev</span> OPTIONAL - useful for indexing but not required</span></span> function</span> getTrustees</span>(</span></span> bytes32</span> trustorNode</span>,</span></span> TrustLevel</span> minLevel</span>,</span></span> bytes32</span> scope</span>,</span></span> uint256</span> offset</span>,</span></span> uint256</span> limit</span></span> )</span> external</span> view</span> returns</span> (</span>bytes32</span>[</span>]</span> memory</span> trustees</span>,</span> uint256</span> total</span>)</span>;</span></span> </span> ///</span> @notice</span> Get agents that trust a given agent (paginated)</span></span> ///</span> @dev</span> OPTIONAL - useful for indexing but not required</span></span> function</span> getTrustors</span>(</span></span> bytes32</span> trusteeNode</span>,</span></span> TrustLevel</span> minLevel</span>,</span></span> bytes32</span> scope</span>,</span></span> uint256</span> offset</span>,</span></span> uint256</span> limit</span></span> )</span> external</span> view</span> returns</span> (</span>bytes32</span>[</span>]</span> memory</span> trustors</span>,</span> uint256</span> total</span>)</span>;</span></span> </span> ///</span> @notice</span> Validate an agent through on-chain graph traversal</span></span> ///</span> @dev</span> OPTIONAL - expensive, prefer off-chain computation with verifyPath</span></span> ///</span> @param</span> validatorNode</span> The validating agent's perspective</span></span> ///</span> @param</span> targetNode</span> The agent to validate</span></span> ///</span> @param</span> params</span> Validation parameters</span></span> ///</span> @param</span> marginalThreshold</span> Number of marginal attestations required (for accumulation)</span></span> ///</span> @param</span> fullThreshold</span> Number of full attestations required</span></span> function</span> validateAgent</span>(</span></span> bytes32</span> validatorNode</span>,</span></span> bytes32</span> targetNode</span>,</span></span> ValidationParams</span> calldata</span> params</span>,</span></span> uint8</span> marginalThreshold</span>,</span></span> uint8</span> fullThreshold</span></span> )</span> external</span> view</span> returns</span> (</span></span> bool</span> isValid</span>,</span></span> uint8</span> pathLength</span>,</span></span> uint8</span> marginalCount</span>,</span></span> uint8</span> fullCount</span></span> )</span>;</span></span> </span> ///</span> @notice</span> Check if any trust path exists</span></span> ///</span> @dev</span> OPTIONAL - expensive, prefer off-chain computation</span></span> function</span> pathExists</span>(</span></span> bytes32</span> fromNode</span>,</span></span> bytes32</span> toNode</span>,</span></span> uint8</span> maxDepth</span></span> )</span> external</span> view</span> returns</span> (</span>bool</span> exists</span>,</span> uint8</span> depth</span>)</span>;</span></span> </span> ///</span> @notice</span> Validate participant without pre-computed path</span></span> ///</span> @dev</span> OPTIONAL - expensive, prefer validateParticipantWithPath</span></span> function</span> validateParticipant</span>(</span></span> bytes32</span> coordinationType</span>,</span></span> bytes32</span> participantNode</span>,</span></span> uint8</span> marginalThreshold</span>,</span></span> uint8</span> fullThreshold</span></span> )</span> external</span> view</span> returns</span> (</span>bool</span> isValid</span>)</span>;</span></span> }</span></span></code></pre>Semantics</h3> setTrust</code></h4> setTrust</code> MUST revert if:</p> attestation.trustorNode == attestation.trusteeNode</code> (self-trust prohibited)</li> attestation.nonce <= getNonce(attestation.trustorNode)</code></li> attestation.expiry != 0 && attestation.expiry <= block.timestamp</code></li> The signature does not verify per the Signature Authority section</li> The ENS name for trustorNode</code> does not exist (owner is zero address)</li> </ul> If valid:</p> The trust record MUST be stored, keyed by (trustorNode, trusteeNode, scope)</code></li> getNonce(trustorNode)</code> MUST return the attestation's nonce</li> TrustSet</code> MUST be emitted</li> </ul> setTrustBatch</code></h4> setTrustBatch</code> MUST revert if:</p> attestations.length != signatures.length</code></li> Any attestation has a different trustorNode</code> than the first attestation</li> Any individual attestation would fail setTrust</code> validation</li> </ul> Nonces within the batch MUST be strictly increasing.</p> revokeTrust</code></h4> revokeTrust</code> MUST revert if:</p> Caller is not the ENS owner or an approved operator for trustorNode</code></li> No existing trust relationship exists for (trustorNode, trusteeNode, scope)</code> (level is Unknown</code>)</li> </ul> If valid:</p> Trust level MUST be set to None</code></li> TrustRevoked</code> MUST be emitted</li> The relationship MUST remain in storage (not deleted) to preserve the explicit distrust</li> </ul> verifyPath</code> — Path Verification Algorithm</h4> verifyPath</code> validates a pre-computed trust path.</p> Algorithm:</strong></p> function</span> verifyPath</span>(</span></span> TrustPath</span> calldata</span> path</span>,</span></span> ValidationParams</span> calldata</span> params</span></span> )</span> external</span> view</span> returns</span> (</span>bool</span> valid</span>,</span> bool</span> anchorSatisfied</span>)</span> {</span></span> //</span> Path must have at least 2 nodes (validator and target)</span></span> if</span> (</span>path</span>.</span>nodes</span>.</span>length </span><</span> 2</span>)</span> return</span> (</span>false</span>,</span> false</span>)</span>;</span></span> </span> //</span> Path length constraint (edges = nodes - 1)</span></span> if</span> (</span>path</span>.</span>nodes</span>.</span>length </span>-</span> 1</span> ></span> params</span>.</span>maxPathLength</span>)</span> return</span> (</span>false</span>,</span> false</span>)</span>;</span></span> </span> //</span> Track anchor satisfaction</span></span> bool</span> foundAnchor </span>=</span> params</span>.</span>requiredAnchors</span>.</span>length </span>==</span> 0</span>;</span></span> </span> //</span> Verify each edge</span></span> for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> path</span>.</span>nodes</span>.</span>length </span>-</span> 1</span>;</span> i</span>+</span>+</span>)</span> {</span></span> //</span> Try scoped trust first, fall back to universal</span></span> (</span>TrustLevel level</span>,</span> uint64</span> expiry</span>)</span> =</span> getTrust</span>(</span></span> path</span>.</span>nodes</span>[</span>i</span>]</span>,</span></span> path</span>.</span>nodes</span>[</span>i </span>+</span> 1</span>]</span>,</span></span> params</span>.</span>scope</span></span> )</span>;</span></span> </span> //</span> Fall back to universal scope if scoped trust not found</span></span> if</span> (</span>level </span>==</span> TrustLevel</span>.</span>Unknown </span>&&</span> params</span>.</span>scope </span>!=</span> bytes32</span>(</span>0</span>)</span>)</span> {</span></span> (</span>level</span>,</span> expiry</span>)</span> =</span> getTrust</span>(</span></span> path</span>.</span>nodes</span>[</span>i</span>]</span>,</span></span> path</span>.</span>nodes</span>[</span>i </span>+</span> 1</span>]</span>,</span></span> bytes32</span>(</span>0</span>)</span></span> )</span>;</span></span> }</span></span> </span> //</span> Edge must meet minimum trust level</span></span> if</span> (</span>level </span><</span> params</span>.</span>minEdgeTrust</span>)</span> return</span> (</span>false</span>,</span> foundAnchor</span>)</span>;</span></span> </span> //</span> None explicitly voids (even if minEdgeTrust is somehow None)</span></span> if</span> (</span>level </span>==</span> TrustLevel</span>.</span>None</span>)</span> return</span> (</span>false</span>,</span> foundAnchor</span>)</span>;</span></span> </span> //</span> Expiry check</span></span> if</span> (</span>params</span>.</span>enforceExpiry </span>&&</span> expiry </span>!=</span> 0</span> &&</span> expiry </span><</span>=</span> block</span>.</span>timestamp</span>)</span> {</span></span> return</span> (</span>false</span>,</span> foundAnchor</span>)</span>;</span></span> }</span></span> </span> //</span> Anchor check (intermediate nodes only, not first or last)</span></span> if</span> (</span>!</span>foundAnchor </span>&&</span> i </span>></span> 0</span>)</span> {</span></span> for</span> (</span>uint256</span> j </span>=</span> 0</span>;</span> j </span><</span> params</span>.</span>requiredAnchors</span>.</span>length</span>;</span> j</span>+</span>+</span>)</span> {</span></span> if</span> (</span>path</span>.</span>nodes</span>[</span>i</span>]</span> ==</span> params</span>.</span>requiredAnchors</span>[</span>j</span>]</span>)</span> {</span></span> foundAnchor </span>=</span> true</span>;</span></span> break</span>;</span></span> }</span></span> }</span></span> }</span></span> }</span></span> </span> return</span> (</span>true</span>,</span> foundAnchor</span>)</span>;</span></span> }</span></span></code></pre> Scope fallback semantics:</strong></p> When validating an edge, implementations MUST:</p> First check for trust at the specified params.scope</code></li> If not found and params.scope != bytes32(0)</code>, check for trust at universal scope bytes32(0)</code></li> Universal trust applies to all scopes</li> </ol> validateParticipantWithPath</code></h4> This function gates ERC-8001</a> coordination participation.</p> function</span> validateParticipantWithPath</span>(</span></span> bytes32</span> coordinationType</span>,</span></span> TrustPath</span> calldata</span> path</span></span> )</span> external</span> view</span> returns</span> (</span>bool</span> isValid</span>)</span> {</span></span> (</span>bytes32</span> gatekeeperNode</span>,</span> ValidationParams </span>memory</span> params</span>,</span> bool</span> enabled</span>)</span> =</span></span> getIdentityGate</span>(</span>coordinationType</span>)</span>;</span></span> </span> if</span> (</span>!</span>enabled</span>)</span> return</span> true</span>;</span> //</span> No gate = open participation</span></span> </span> //</span> Verify path starts at gatekeeper and ends at participant</span></span> if</span> (</span>path</span>.</span>nodes</span>.</span>length </span><</span> 2</span>)</span> return</span> false</span>;</span></span> if</span> (</span>path</span>.</span>nodes</span>[</span>0</span>]</span> !=</span> gatekeeperNode</span>)</span> return</span> false</span>;</span></span> </span> (</span>bool</span> valid</span>,</span> bool</span> anchorOk</span>)</span> =</span> verifyPath</span>(</span>path</span>,</span> params</span>)</span>;</span></span> return</span> valid </span>&&</span> anchorOk</span>;</span></span> }</span></span></code></pre>Errors</h3> Implementations MUST revert with these errors:</p> error</span> SelfTrustProhibited</span>(</span>)</span>;</span></span> error</span> NonceTooLow</span>(</span>uint64</span> provided</span>,</span> uint64</span> required</span>)</span>;</span></span> error</span> AttestationExpired</span>(</span>uint64</span> expiry</span>,</span> uint64</span> currentTime</span>)</span>;</span></span> error</span> InvalidSignature</span>(</span>)</span>;</span></span> error</span> NotAuthorized</span>(</span>bytes32</span> node</span>,</span> address</span> actor</span>)</span>;</span></span> error</span> ENSNameNotFound</span>(</span>bytes32</span> node</span>)</span>;</span></span> error</span> TrustNotFound</span>(</span>bytes32</span> trustorNode</span>,</span> bytes32</span> trusteeNode</span>,</span> bytes32</span> scope</span>)</span>;</span></span> error</span> GateNotFound</span>(</span>bytes32</span> coordinationType</span>)</span>;</span></span> error</span> InvalidValidationParams</span>(</span>string</span> reason</span>)</span>;</span></span> error</span> BatchTrustorMismatch</span>(</span>)</span>;</span></span> error</span> BatchNonceNotIncreasing</span>(</span>)</span>;</span></span></code></pre>Recommended Reason Codes</h3> For TrustRevoked</code> events, the following reason codes are RECOMMENDED:</p> Reason Code</th> Value</th> Meaning</th></tr></thead> Unspecified</td> bytes32(0)</code></td> No specific reason</td></tr> Misbehavior</td> keccak256("MISBEHAVIOR")</code></td> Agent acted improperly</td></tr> Compromised</td> keccak256("COMPROMISED")</code></td> Key or account compromised</td></tr> Inactive</td> keccak256("INACTIVE")</code></td> Agent no longer active</td></tr> Transfer</td> keccak256("TRANSFER")</code></td> ENS name transferred</td></tr> </tbody></table> Recommended Scopes</h3> For interoperability, the following scope values are RECOMMENDED:</p> Scope</th> Value</th> Use Case</th></tr></thead> Universal</td> bytes32(0)</code></td> Trust applies to all contexts</td></tr> DeFi</td> keccak256("DEFI")</code></td> DeFi coordination</td></tr> Gaming</td> keccak256("GAMING")</code></td> Gaming/metaverse</td></tr> MEV</td> keccak256("MEV")</code></td> MEV protection</td></tr> Commerce</td> keccak256("COMMERCE")</code></td> Agentic commerce</td></tr> </tbody></table> Recommended Coordination Types</h3> For ERC-8001</a> identity gates:</p> Coordination Type</th> Value</th></tr></thead> MEV Coordination</td> keccak256("MEV_COORDINATION")</code></td></tr> DeFi Yield</td> keccak256("DEFI_YIELD")</code></td></tr> Gaming Match</td> keccak256("GAMING_MATCH")</code></td></tr> Commerce Escrow</td> keccak256("COMMERCE_ESCROW")</code></td></tr> </tbody></table> Rationale</h2> Why ENS Instead of a New Identity System?</h3> ENS is finalised EIP-137</a>, battle-tested, and widely adopted. Creating a new identity system would:</p> Add dependency on draft standards</li> Fragment the identity ecosystem</li> Require new adoption efforts</li> </ul> ENS provides everything needed: stable identifiers, ownership semantics, and extensibility.</p> Why Scope as Storage Key?</h3> A trustor may have different trust levels for the same trustee in different contexts. For example:</p> Trust bob.eth</code> fully for DeFi coordination</li> Trust bob.eth</code> marginally for gaming</li> </ul> Making scope part of the storage key (trustorNode, trusteeNode, scope)</code> enables this naturally. Universal trust bytes32(0)</code> serves as a fallback when scoped trust is not specified.</p> Why minEdgeTrust Instead of Marginal/Full Thresholds?</h3> The marginalThreshold</code> and fullThreshold</code> parameters were designed for on-chain graph traversal with marginal accumulation logic. Since on-chain traversal is OPTIONAL (expensive, DoS-prone), and the core primitive is verifyPath</code>, we need only specify the minimum trust level each edge must have.</p> This simplification:</p> Reduces parameter complexity</li> Makes path verification straightforward</li> Leaves accumulation semantics to OPTIONAL extensions</li> </ul> For use cases requiring marginal accumulation, the OPTIONAL validateAgent</code> extension accepts threshold parameters.</p> Why Separate Signing Authority from Transaction Submission?</h3> ENS approvals (isApprovedForAll</code>) are designed for operators to manage names on behalf of owners. However, allowing approved operators to forge attestation signatures would break the cryptographic binding between attestations and ENS owners.</p> By restricting signing authority to the ENS owner (or EIP-1271 for contract owners) while allowing operators to submit transactions like revokeTrust</code>, we preserve:</p> Cryptographic integrity of attestations</li> Operational flexibility for name management</li> Clear security boundaries</li> </ul> Why verifyPath Only (No On-Chain Search)?</h3> On-chain graph traversal is expensive and creates DoS vectors:</p> Branching factor can explode with user-controlled adjacency lists</li> Gas costs are unpredictable</li> Attackers can bloat trustee lists</li> </ul> By requiring pre-computed paths, this standard:</p> Keeps on-chain verification O(path length)</li> Pushes search complexity to off-chain indexers where it belongs</li> Enables predictable gas costs</li> </ul> Implementations MAY add validateAgent</code> and pathExists</code> as OPTIONAL extensions, but these are not required for compliance.</p> Why Four Trust Levels?</h3> The four-level model (Unknown, None, Marginal, Full) is proven by GnuPG's 25+ years of use. Finer granularity adds complexity without clear benefit; coarser granularity loses important distinctions.</p> With minEdgeTrust</code>, applications can choose their security posture:</p> minEdgeTrust: Full</code> — Only fully trusted paths</li> minEdgeTrust: Marginal</code> — Accept marginal trust (default)</li> </ul> Why Required Anchors?</h3> Sybil attacks are the primary threat to web of trust systems. Required anchors force trust paths to traverse established community nodes (DAOs, protocols, auditors), transforming Sybil resistance from application-layer advice into protocol-level enforcement.</p> Backwards Compatibility</h2> This ERC introduces new functionality and does not modify existing standards.</p> ENS Compatibility</strong>: Uses standard ENS interfaces (owner</code>, isApprovedForAll</code>). Works with any ENS deployment. Does not rely on CCIP-Read or other off-chain mechanisms.</p> ERC-8001 Compatibility</strong>: Designed as a module. ERC-8001 coordinators can optionally integrate identity gates.</p> Wallet Compatibility</strong>: Uses EIP-712</a> signatures, compatible with all major wallets. Supports EIP-1271</a> for contract wallets and smart accounts.</p> Reference Implementation</h2> See contracts/TrustRegistry.sol</code></a> for the complete implementation.</p> Security Considerations</h2> Sybil Attacks</h3> An attacker can create many ENS names and establish mutual trust between them.</p> Protocol-level mitigations:</strong></p> Required anchors</strong>: ValidationParams.requiredAnchors</code> forces paths through established community nodes</li> Short path limits</strong>: maxPathLength: 2</code> requires close proximity to validators</li> High trust requirement</strong>: minEdgeTrust: Full</code> rejects marginal trust paths</li> </ul> Application-level mitigations:</strong></p> Weight trust by ENS name age or registration cost</li> Implement additional stake requirements</li> Monitor trust graphs for anomalous patterns off-chain</li> </ul> Trust Graph Manipulation</h3> Attackers may attempt to position themselves in many trust paths.</p> Mitigations:</strong></p> Monitor trust graphs for anomalous patterns off-chain</li> Use minEdgeTrust: Full</code> for high-value coordination</li> Require multiple independent paths via OPTIONAL extensions</li> </ul> Key Compromise</h3> If an ENS name's controller is compromised:</p> Mitigations:</strong></p> Agents SHOULD monitor for unexpected trust changes via TrustSet</code> events</li> Use short expiries (90 days maximum recommended for high-stakes)</li> ENS name owners can rotate controllers</li> Affected agents can issue TrustRevoked</code> to quarantine compromised nodes</li> </ul> ENS Name Transfer</h3> When an ENS name is transferred:</p> New owner inherits trust where they are the trustee</li> New owner can manage trust where they are the trustor</li> Old attestations signed by old owner remain valid until expiry</li> </ul> Mitigations:</strong></p> Use short expiries for high-stakes trust</li> Monitor ENS Transfer</code> events</li> Re-evaluate trust after transfers</li> </ul> Replay Protection</h3> EIP-712</a> domain binding prevents cross-contract replay. Monotonic nonces prevent replay within the same contract. The chainId</code> in the domain prevents cross-chain replay.</p> Stale Trust</h3> Trust relationships may become stale if agents don't update them.</p> Mitigations:</strong></p> Use enforceExpiry: true</code> in validation parameters</li> Set reasonable expiry</code> values on attestations (RECOMMENDED: 90 days maximum for high-stakes)</li> Monitor TrustSet</code> event timestamps off-chain</li> </ul> Off-Chain Path Computation</h3> This standard assumes off-chain indexers compute trust paths. Malicious indexers could:</p> Return suboptimal paths</li> Omit valid paths</li> Return invalid paths (caught by verifyPath</code>)</li> </ul> Mitigations:</strong></p> Users can run their own indexers</li> Multiple independent indexers provide redundancy</li> Invalid paths are always rejected on-chain</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Cross-Chain Function Calls via Hooks 2025-12-12T00:00:00+00:00 Abstract</h2> This ERC introduces hooks for cross-chain function calls. A hook fully specifies what function to call, with what parameters, on which contract, on which chain. Hooks require clients to use ERC-3668</a> to resolve, enabling cross-chain and off-chain verifiable data resolution. Hooks are particularly useful for redirecting metadata to known contracts with verifiable security properties, such as credential registries for Proof-of-Personhood (PoP) or Know-Your-Agent (KYA) for AI agent identity.</p> Motivation</h2> There is a need to resolve data cross-chain, such as credentials like Proof-of-Personhood (PoP), for example from a dedicated identity chain. There is also a need to save these cross-chain function calls onchain, and there is currently no existing standard for saving this type of function call as a string or bytes value onchain, in a maximally human-readable way. It should also be possible for a hook to be included in plain text, for example a markdown file intended to be consumed by AI agents. Hooks allow for a specific function, contract, and chain to be specified in a human-readable way. One of the most important features of hooks is that it allows clients to evaluate whether or not they trust the target contract, for example to resolve a PoP or KYC credential, before calling the function.</p> Use Cases</h3> Cross-Chain Metadata</strong>: Resolve metadata from contracts on other chains</li> Credential Resolution</strong>: Redirect a Proof-of-Person (PoP) or Know-Your-Customer (KYC) record to a trusted credential registry</li> Singleton Registries</strong>: Point to canonical registries with known security properties on any chain</li> Shared Metadata</strong>: Multiple contracts can reference the same metadata source across chains</li> </ul> Specification</h2> 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.</p> Overview</h3> A hook is a fully specified function call containing an optional function selector, function signature with explicit types, human-readable function call with values, return type, and an ERC-7930</a> interoperable address specifying both the target contract and chain. The function selector acts as a checksum to verify the function signature, ensuring type safety and preventing ambiguity. This makes hooks completely self-describing - any client can resolve them without external documentation.</p> Hook Function Signature</h3> Hooks can be encoded with or without an optional function selector. When the selector is omitted, functionSignature</code> is the first parameter.</p> With optional function selector:</strong></p> function</span> hook</span>(</span></span> bytes4</span> functionSelector</span>,</span></span> string</span> calldata</span> functionSignature</span>,</span></span> string</span> calldata</span> functionCall</span>,</span></span> string</span> calldata</span> returnType</span>,</span></span> bytes</span> calldata</span> target</span></span> )</span></span></code></pre> Without function selector:</strong></p> function</span> hook</span>(</span></span> string</span> calldata</span> functionSignature</span>,</span></span> string</span> calldata</span> functionCall</span>,</span></span> string</span> calldata</span> returnType</span>,</span></span> bytes</span> calldata</span> target</span></span> )</span></span></code></pre>bytes4</span> constant</span> HOOK_SELECTOR_WITH_SELECTOR </span>=</span> 0x037f43ed</span>;</span> //</span> When functionSelector is included</span></span> bytes4</span> constant</span> HOOK_SELECTOR_WITHOUT_SELECTOR </span>=</span> 0x6113bfa3</span>;</span> //</span> When functionSelector is omitted</span></span></code></pre>Parameters</h4> functionSelector</code></strong>: (OPTIONAL) The 4-byte selector of the function to call. When provided, this acts as a checksum to verify the functionSignature</code>. If omitted, the hook structure starts with functionSignature</code> as the first parameter. Clients can always derive the selector from functionSignature</code>.</li> functionSignature</code></strong>: The full function signature with explicit parameter types (e.g., "getData((string,uint256))"</code>, "getCredential(string)"</code>). This MUST match the function selector when hashed, if a selector is provided. When the selector is omitted, this is the first parameter in the hook structure.</li> functionCall</code></strong>: A string representation of the function to call with its parameter values (human-readable, e.g., "getData(('alice', 42))"</code>, "getCredential('kyc: 0x76F1Ff...123')"</code>)</li> returnType</code></strong>: The return type in Solidity tuple notation for ABI decoding (e.g., (string)</code>, (uint256, bytes32)</code>, ((string, uint256[], bytes32))</code>)</li> target</code></strong>: An ERC-7930</a> interoperable address specifying both the target contract and chain</li> </ul> Function Call Format</h3> The functionCall</code> parameter uses a Solidity-style syntax:</p> String parameters are enclosed in single quotes: 'value'</code></li> Bytes/hex parameters use the 0x</code> prefix: 0x1234abcd</code></li> Numbers are written as literals: 42</code> or 1000000</code></li> Arrays use square brackets: [1, 2, 3]</code> or ['a', 'b', 'c']</code></li> Structs/tuples use parentheses: ('alice', 42, true)</code></li> </ul> Examples:</strong></p> // Example with optional function selector (acts as checksum)</span></span> hook(0xc41a360a, "getOwner(uint256)", "getOwner(42)", "(address)", 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span> </span> // Example with function selector omitted</span></span> hook("getOwner(uint256)", "getOwner(42)", "(address)", 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span></code></pre>Hook Encoding</h3> Hooks can be encoded in two formats depending on the storage type:</p> Bytes Format</h4> For systems that store bytes</code> values, hooks MUST be ABI-encoded. Use different hook selectors depending on whether the optional function selector is included:</p> With optional function selector:</strong></p> //</span> Hook selector: first 4 bytes of keccak256("hook(bytes4,string,string,string,bytes)")</span></span> bytes4</span> constant</span> HOOK_SELECTOR_WITH_SELECTOR </span>=</span> 0x037f43ed</span>;</span></span> </span> //</span> Function signature with explicit types</span></span> string</span> memory</span> functionSignature </span>=</span> "getContractMetadata(string)"</span>;</span></span> </span> //</span> Optional function selector as checksum (computed from signature)</span></span> bytes4</span> functionSelector </span>=</span> bytes4</span>(</span>keccak256</span>(</span>functionSignature</span>)</span>)</span>;</span> //</span> 0x1837de7f</span></span> </span> //</span> Function call with values</span></span> string</span> memory</span> functionCall </span>=</span> "getContractMetadata('kyc')"</span>;</span></span> </span> //</span> ERC-7930 address: Ethereum mainnet (chain 1) contract</span></span> bytes</span> memory</span> target </span>=</span> hex</span>"000100000101141234567890abcdef1234567890abcdef12345678"</span>;</span></span> </span> bytes</span> memory</span> hookData </span>=</span> abi</span>.</span>encodeWithSelector</span>(</span></span> HOOK_SELECTOR_WITH_SELECTOR</span>,</span></span> functionSelector</span>,</span></span> functionSignature</span>,</span></span> functionCall</span>,</span></span> "(bytes)"</span>,</span> //</span> return type</span></span> target</span></span> )</span>;</span></span> </span> //</span> Store the hook as the value</span></span> originatingContract</span>.</span>setContractMetadata</span>(</span>"kyc"</span>,</span> hookData</span>)</span>;</span></span></code></pre> Without function selector:</strong></p> //</span> Hook selector: first 4 bytes of keccak256("hook(string,string,string,bytes)")</span></span> bytes4</span> constant</span> HOOK_SELECTOR_WITHOUT_SELECTOR </span>=</span> 0x6113bfa3</span>;</span></span> </span> //</span> Function signature with explicit types</span></span> string</span> memory</span> functionSignature </span>=</span> "getContractMetadata(string)"</span>;</span></span> </span> //</span> Function call with values</span></span> string</span> memory</span> functionCall </span>=</span> "getContractMetadata('kyc')"</span>;</span></span> </span> //</span> ERC-7930 address: Ethereum mainnet (chain 1) contract</span></span> bytes</span> memory</span> target </span>=</span> hex</span>"000100000101141234567890abcdef1234567890abcdef12345678"</span>;</span></span> </span> bytes</span> memory</span> hookData </span>=</span> abi</span>.</span>encodeWithSelector</span>(</span></span> HOOK_SELECTOR_WITHOUT_SELECTOR</span>,</span></span> functionSignature</span>,</span> //</span> First parameter when selector is omitted</span></span> functionCall</span>,</span></span> "(bytes)"</span>,</span> //</span> return type</span></span> target</span></span> )</span>;</span></span> </span> //</span> Store the hook as the value</span></span> originatingContract</span>.</span>setContractMetadata</span>(</span>"kyc"</span>,</span> hookData</span>)</span>;</span></span> //</span> Target function: function getContractMetadata(string) external view returns (bytes memory)</span></span></code></pre>String Format</h4> For systems that store string</code> values, hooks MUST be formatted as shown below. The target is an ERC-7930</a> interoperable address.</p> With optional function selector:</strong></p> hook(0x9e574b14, "getContractMetadata(string)", "getContractMetadata('kyc')", "(bytes)", 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span></code></pre> Without function selector:</strong></p> hook("getContractMetadata(string)", "getContractMetadata('kyc')", "(bytes)", 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span></code></pre> Parsers MUST detect the format by checking if the first parameter after hook(</code> starts with 0x</code> followed by 8 hexadecimal characters (an optional function selector) or not.</p> Examples:</strong></p> </span> // Example 1: simple struct parameter</span></span> hook(0xabcdef12, "getData((string,uint256))", "getData(('alice', 42))", "(bytes)", 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span> </span> // Example 2: struct parameter returning struct</span></span> hook(0x12345678, "getCredential((string,uint256,bytes32))", "getCredential(('kyc', 12345, 0xabcd1234...))", "((string,address,uint256))", 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span> </span> // Example 3: nested struct (struct containing a struct)</span></span> hook(0x9abcdef0, "getAgent((string,uint256,(address,bool,string)))", "getAgent(('alice', 42, (0x1234..., true, 'verified')))", "((string,uint256,(address,bool)))", 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span></code></pre>Detecting Hooks</h3> Clients SHOULD be aware in advance which metadata keys may contain hooks. It is intentional that hook-enabled keys are known by clients beforehand, similar to how clients know to look for keys like "image"</code> or "description"</code>.</p> For bytes values, hooks can be detected by checking if the value starts with either hook selector 0x037f43ed</code> (with optional function selector) or 0x6113bfa3</code> (without function selector). For string values, hooks can be detected by checking if the value starts with hook(</code>.</p> Resolving Hooks (Read Operations)</h3> When a client encounters a hook that it wants to use for a read operation:</p> Detect hook format</strong>: For bytes format, check if the value starts with 0x037f43ed</code> (with selector) or 0x6113bfa3</code> (without selector). For string format, parse the first parameter after hook(</code> to determine if it's a selector (starts with 0x</code> + 8 hex chars) or not.</li> Parse the hook</strong>: Extract the functionSelector</code> (if present), functionSignature</code>, functionCall</code>, returnType</code>, and target</code> (ERC-7930</a> address). If the selector is omitted, functionSignature</code> is the first parameter.</li> Verify the selector</strong> (if provided): If functionSelector</code> is present, compute the expected selector from functionSignature</code> as bytes4(keccak256(functionSignature))</code> and verify it matches functionSelector</code>. Reject the hook if they don't match. This verification ensures type safety and prevents ambiguity with structs or overloaded functions. If the selector is omitted, compute it from functionSignature</code> for use in the function call.</li> Parse the target</strong>: Decode the ERC-7930</a> address to extract the chain and contract address</li> Verify the target</strong> (RECOMMENDED): Check that the target contract is known and trusted</li> Parse the function call</strong>: Extract the function name and parameter values from functionCall</code>. Use functionSignature</code> to determine the parameter types for ABI encoding.</li> Enable ERC-3668</a></strong>: Clients MUST enable ERC-3668</a> offchain data retrieval before calling the target</li> Call the target</strong>: Execute the function on the target contract and chain. Use the provided functionSelector</code> if available, otherwise compute it from functionSignature</code> as bytes4(keccak256(functionSignature))</code>. ABI-encode the parameters according to functionSignature</code>.</li> Get the result</strong>: Retrieve the return value from the function call.</li> </ol> Clients MAY choose NOT to resolve hooks if the target contract is not known to be secure and trustworthy. Some clients have ERC-3668</a> disabled by default, but clients MUST enable it before resolving the hook.</p> Write Operations</h3> Write operations are also possible with hooks and follow the same flow as read operations, except that the transaction needs to be signed and submitted to the blockchain. The hook specifies the function to call, parameters, target contract, and chain, but instead of reading the result, the transaction is signed and broadcast to the network for inclusion in a block.</p> Example: Cross-Chain KYC Credential Resolution</h3> A contract on Optimism can redirect its "kyc"</code> metadata key to a trusted KYC provider contract on Ethereum mainnet:</p> Step 1: Store the hook in the originating contract (on Optimism)</strong></p> bytes4</span> constant</span> HOOK_SELECTOR_WITHOUT_SELECTOR </span>=</span> 0x6113bfa3</span>;</span></span> </span> //</span> Function signature with explicit types</span></span> string</span> memory</span> functionSignature </span>=</span> "getCredential(string)"</span>;</span></span> </span> //</span> Function call with values</span></span> string</span> memory</span> functionCall </span>=</span> "getCredential('kyc: 0x76F1Ff0186DDb9461890bdb3094AF74A5F24a162')"</span>;</span></span> </span> //</span> KYCProvider on Ethereum mainnet (ERC-7930 format)</span></span> //</span> Chain: Ethereum mainnet (chain 1), Address: 0x1234...5678</span></span> bytes</span> memory</span> target </span>=</span> hex</span>"000100000101141234567890abcdef1234567890abcdef12345678"</span>;</span></span> </span> //</span> Create hook that calls getCredential('kyc: 0x76F1Ff...') on the KYC provider</span></span> bytes</span> memory</span> hookData </span>=</span> abi</span>.</span>encodeWithSelector</span>(</span></span> HOOK_SELECTOR_WITHOUT_SELECTOR</span>,</span></span> functionSignature</span>,</span> //</span> First parameter when selector is omitted</span></span> functionCall</span>,</span></span> "(string)"</span>,</span> //</span> return type</span></span> target</span></span> )</span>;</span></span> </span> //</span> Store the hook</span></span> originatingContract</span>.</span>setContractMetadata</span>(</span>"kyc"</span>,</span> hookData</span>)</span>;</span></span></code></pre> Step 2: Client resolves the hook</strong></p> //</span> Client reads metadata from originating contract (on Optimism)</span></span> const</span> value</span> =</span> await</span> originatingContract</span>.</span>getContractMetadata</span>(</span>"</span>kyc</span>"</span>)</span>;</span></span> </span> //</span> Client detects this is a hook (starts with HOOK_SELECTOR)</span></span> const</span> hasSelector</span> =</span> value</span>.</span>startsWith</span>(</span>"</span>0x037f43ed</span>"</span>)</span>;</span></span> if</span> (</span>value</span>.</span>startsWith</span>(</span>"</span>0x037f43ed</span>"</span>)</span> \|\|</span> value</span>.</span>startsWith</span>(</span>"</span>0x6113bfa3</span>"</span>)</span>)</span> {</span></span> //</span> Parse the hook (ABI decode after 4-byte selector)</span></span> let</span> functionSelector</span>,</span> functionSignature</span>,</span> functionCall</span>,</span> returnType</span>,</span> target</span>;</span></span> if</span> (</span>hasSelector</span>)</span> {</span></span> (</span>{</span> functionSelector</span>,</span> functionSignature</span>,</span> functionCall</span>,</span> returnType</span>,</span> target</span> }</span> =</span> decodeHook</span>(</span>value</span>)</span>)</span>;</span></span> }</span> else</span> {</span></span> (</span>{</span> functionSignature</span>,</span> functionCall</span>,</span> returnType</span>,</span> target</span> }</span> =</span> decodeHook</span>(</span>value</span>)</span>)</span>;</span></span> functionSelector</span> =</span> null</span>;</span></span> }</span></span> </span> //</span> Verify selector matches the function signature (checksum verification, if provided)</span></span> const</span> computedSelector</span> =</span> keccak256</span>(</span>functionSignature</span>)</span>.</span>slice</span>(</span>0</span>,</span> 10</span>)</span>;</span></span> if</span> (</span>functionSelector</span>)</span> {</span></span> if</span> (</span>functionSelector</span> !==</span> computedSelector</span>)</span> {</span></span> throw</span> new</span> Error</span>(</span>"</span>Selector mismatch - function signature verification failed</span>"</span>)</span>;</span></span> }</span></span> }</span></span> //</span> Use computed selector if not provided</span></span> const</span> selectorToUse</span> =</span> functionSelector</span> \|\|</span> computedSelector</span>;</span></span> </span> //</span> Decode ERC-7930 address to get chain and contract</span></span> const</span> {</span> chainId</span>,</span> address</span> }</span> =</span> decodeERC7930</span>(</span>target</span>)</span>;</span></span> //</span> chainId = 1 (Ethereum mainnet)</span></span> //</span> address = 0x1234567890abcdef1234567890abcdef12345678</span></span> </span> //</span> Verify target is trusted (implementation-specific)</span></span> if</span> (</span>!</span>isTrustedResolver</span>(</span>chainId</span>,</span> address</span>)</span>)</span> {</span></span> throw</span> new</span> Error</span>(</span>"</span>Untrusted resolver</span>"</span>)</span>;</span></span> }</span></span> </span> //</span> Parse the function call string to get function name and parameter values</span></span> const</span> {</span> functionName</span>,</span> args</span> }</span> =</span> parseFunctionCall</span>(</span>functionCall</span>)</span>;</span></span> //</span> functionName = "getCredential"</span></span> //</span> args = ["kyc: 0x76F1Ff0186DDb9461890bdb3094AF74A5F24a162"]</span></span> </span> //</span> Use functionSignature to determine parameter types for ABI encoding</span></span> //</span> functionSignature = "getCredential(string)"</span></span> </span> //</span> Get provider for target chain and enable ERC-3668 (CCIP-Read)</span></span> const</span> targetProvider</span> =</span> getProviderForChain</span>(</span>chainId</span>)</span>;</span></span> const</span> targetContract</span> =</span> new</span> ethers</span>.</span>Contract</span>(</span></span> address</span>,</span></span> [</span>`</span>function </span>${</span>functionSignature</span>}</span> view returns (bytes)</span>`</span>]</span>,</span></span> targetProvider</span>.</span>ccipReadEnabled</span>(</span>true</span>)</span> //</span> Enable CCIP-Read</span></span> )</span>;</span></span> </span> //</span> Resolve from target contract on Ethereum mainnet</span></span> //</span> ABI-encode parameters according to functionSignature</span></span> const</span> resultBytes</span> =</span> await</span> targetContract</span>[</span>functionName</span>]</span>(</span>...</span>args</span>)</span>;</span></span> </span> //</span> ABI-decode using returnType: "(string)"</span></span> const</span> credential</span> =</span> ethers</span>.</span>utils</span>.</span>defaultAbiCoder</span>.</span>decode</span>(</span>[</span>returnType</span>]</span>,</span> resultBytes</span>)</span>;</span></span> //</span> credential = "Maria Garcia /0x76F1Ff.../ ID: 146-DJH-6346-25294"</span></span> }</span></span></code></pre>Rationale</h2> Hooks provide a complete specification for cross-chain function calls, including ERC-7930</a> interoperable address. This makes hooks entirely self-describing - any client can resolve them without external documentation or ABI files. For use cases including resolving credentials from known registries including PoP (Proof of Personhood) and KYC (Know Your Customer) credentials, the client needs to make sure the source of the credential is trustworthy and verified. Hooks allow clients to jump from a user's metadata record, for example, to a KYC credential from a known credential issuer.</p> Why Include Both Function Selector and Function String?</h3> Hooks include both an optional 4-byte function selector and a human-readable function call string. The selector provides type disambiguation (e.g., getData(bytes32)</code> and getData(bytes)</code> have different selectors, but 0x1234...</code> in the string is ambiguous), while the string provides human readability. Clients can verify the selector matches the function signature, rejecting mismatches as errors or tampering.</p> Why Use ERC-7930 Interoperable Addresses?</h3> ERC-7930</a> addresses include chain information, making hooks a complete cross-chain function call specification. A hook specifies exactly what function to call, with what parameters, on which contract, on which chain. This eliminates ambiguity and enables secure cross-chain reads when combined with ERC-3668</a>.</p> Why Include the Return Type?</h3> The returnType</code> parameter allows clients to predict the return values without consulting documentation. It is also possible to predict if the return data is compatible with intended metadata. For example, if a bytes value redirects using hooks, that return value may need to also be bytes, according to the specific metadata standard (not specified here). Applications can impose their own constraints (e.g., requiring (string)</code> for metadata hooks), but hooks themselves support any return type.</p> Why Mandate ERC-3668</a>?</h3> ERC-3668</a> (CCIP-Read) is a powerful technology that enables both cross-chain and verified offchain resolution of metadata. However, because some clients disable ERC-3668</a> by default due to security considerations, hooks explicitly mandate ERC-3668</a> support. This gives clients the opportunity to enable ERC-3668</a> specifically for hook resolution without needing to have it enabled globally. By tying ERC-3668</a> to hooks, clients can make a deliberate choice to enable it when resolving from known, trusted contracts, while keeping it disabled for general use.</p> Backwards Compatibility</h2> Hooks are backwards compatible; clients that are not aware of hooks will simply return the hook encoding as the raw value.</p> Security Considerations</h2> Target Trust</h3> The primary use of hooks is to resolve data from known contracts with verifiable security properties. Clients SHOULD:</p> Maintain a list of trusted target contract addresses or use a third-party registry</li> Fail when resolving from untrusted targets</li> </ul> Recursive Hooks</h3> Implementations SHOULD limit the depth of hook resolution to prevent infinite loops where a hook resolves to another hook. A reasonable limit is 3-5 levels of indirection.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Associated Accounts 2025-11-25T00:00:00+00:00 Abstract</h2> This specification defines a standard for establishing and verifying associations between blockchain accounts. This allows addresses to publicly declare, prove and revoke a relationship with other addresses by sharing a standardized payload. For onchain applications, this payload may be signed by both parties for third-party authentication. This enables use cases like sub-account identity inheritance, authorization delegation, and reputation collation.</p> Motivation</h2> A key motivation is the simplification of multi-address resolution, which is essential for managing complex digital identities across multiple platforms and accounts. This simplification aims to streamline the process of locating and verifying individuals or entities by efficiently handling multiple addresses linked by Associations. By providing a standard mechanism for signaling an association between two accounts, this standard unlocks the capability to link the activities or details of these accounts.</p> The inclusion of arbitrary data into the specified payload ensures flexibility for various use cases such as delegation, hierarchical relationships, and authentication. By maintaining a flexible architecture that accepts an interface identifier paired with arbitrary data bytes, accounts that associate can do so with application-specific context.</p> The system outlined in this document describes a way for two accounts to be linked by a specified data struct which describes the relationship between them. It offers the mechanism by which these parties can sign over the contents to prove validity. It focuses on the structure and process for generating, validating and revoking such records while maintaining an implementation agnostic approach.</p> Specification</h2> 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.</p> Core Concepts</h3> Each Association between two accounts denotes the participating addresses as initiator</code> and approver</code>. These accounts can be on disparate chains with different architectures made possible by a combination of ERC-7930</a> Interoperable Addresses and an enumeration of signature key types. To accommodate non-EVM account types, addresses are recorded in the association as raw bytes.</p> The specification outlines a nested structure for recording Associations:</p> An underlying Associated Account Record (AAR) for storing accounts, timestamps and association context</li> A wrapper Signed Association Record (SAR) structure for storing signature and validation data</li> </ol> Associated Account Record</h3> The following is a Solidity implementation of an AssociatedAccountRecord</code> which contains the shared payload describing the association.</p> ///</span> @notice</span> Represents an association between two accounts.</span></span> struct</span> AssociatedAccountRecord</span> {</span></span> ///</span> @dev</span> The ERC-7930 binary representation of the initiating account's address.</span></span> bytes</span> initiator</span>;</span></span> ///</span> @dev</span> The ERC-7930 binary representation of the approving account's address.</span></span> bytes</span> approver</span>;</span></span> ///</span> @dev</span> The timestamp from which the association is valid.</span></span> uint40</span> validAt</span>;</span></span> ///</span> @dev</span> The timestamp when the association expires.</span></span> uint40</span> validUntil</span>;</span></span> ///</span> @dev</span> Optional 4-byte selector for interfacing with the `data` field.</span></span> bytes4</span> interfaceId</span>;</span></span> ///</span> @dev</span> Optional additional data.</span></span> bytes</span> data</span>;</span></span> }</span></span></code></pre> Where the AssociatedAccountRecord contains:</p> initiator</code> is the binary representation of an ERC-7930 address for the initiating account.</li> approver</code> is the binary representation of an ERC-7930 address for the approving account.</li> validAt</code> is the timestamp from which the association is valid.</li> validUntil</code> is the timestamp at which the association expires (optional).</li> interfaceId</code> is the 4-byte interface or method selector for the data</code> field (optional).</li> data</code> is the arbitrary context data payload (optional).</li> </ul> Signed Association Record</h3> When AssociatedAccountRecord</code>s will be consumed in a trustless context, integrators SHOULD require that both parties sign over the EIP-712</a> hash of the AssociatedAccountRecord</code> (see Support for EIP-712 below). The resulting signatures MUST be included in a SignedAssociationRecord</code>.</p> ///</span> @notice</span> Complete payload containing a finalized association.</span></span> struct</span> SignedAssociationRecord</span> {</span></span> ///</span> @dev</span> The timestamp the association was revoked.</span></span> uint40</span> revokedAt</span>;</span></span> ///</span> @dev</span> The initiator key type specifier.</span></span> bytes2</span> initiatorKeyType</span>;</span></span> ///</span> @dev</span> The approver key type specifier.</span></span> bytes2</span> approverKeyType</span>;</span></span> ///</span> @dev</span> The signature of the initiator.</span></span> bytes</span> initiatorSignature</span>;</span></span> ///</span> @dev</span> The signature of the approver.</span></span> bytes</span> approverSignature</span>;</span></span> ///</span> @dev</span> The underlying AssociatedAccountRecord.</span></span> AssociatedAccountRecord record</span>;</span></span> }</span></span></code></pre> Where the SignedAssociationRecord contains:</p> revokedAt</code> is the timestamp when the association was revoked, which is 0</code> unless the association has been revoked by either party.</li> initiatorSignature</code> is the signature bytes generated by the initiator</code> by signing the EIP-712 compliant hash of the AssociatedAccountRecord.</li> initiatorKeyType</code> is the key type designator for the initiator's signature (see Key Types below).</li> approverSignature</code> is the signature bytes generated by the approver</code> by signing the EIP-712 compliant hash of the AssociatedAccountRecord.</li> approverKeyType</code> is the key type designator for the approver's signature (see Key Types below).</li> record</code> is the AssociatedAccountRecord that was signed by both parties.</li> </ul> Key Types</h3> To accommodate known curves and signing protocols while providing future extensibility, this specification relies on the enumeration of cryptographic curves and signing protocols. Each signature MUST be paired with a valid "Key ID" designator.</p> The Key IDs SHALL be identified as a 2-byte integer according to the following extensible table. We accommodate two types of keys:</p> Applied cryptographic curves (i.e. secp256k1)</li> Protocol integrations (i.e. WebAuthn, contract validation)</li> </ol> To distinguish these key types, the most significant bit in the 2-byte identifier SHALL be used as a bit flag. As such, key type protocols are constructed by bitwise OR: 0x8000 \| PROTOCOL_ID</code>.</p> The resulting table enumerates the known keys and distinguishes between the two types:</p> Key ID</th> Type</th> Curve/Standard</th></tr></thead> 0x0000</td> Delegated</td> Delegated auth</td></tr> 0x0001</td> K1</td> secp256k1</td></tr> 0x0002</td> R1</td> secp256r1</td></tr> 0x0003</td> BLS</td> BLS12-381</td></tr> 0x0004</td> EdDSA</td> Ed25519</td></tr> 0x8001</td> WebAuthn</td> WebAuthn/Passkey</td></tr> 0x8002</td> ERC-1271</a></td> Contract validation</td></tr> 0x8003</td> ERC-6492</a></td> Predeploy contract validation</td></tr> </tbody></table> Delegated Auth</h4> In some contexts it might be ergonomic to delegate authorization to another account, access control mechanism, or external protocol. Implementers leveraging the Delegated</code> key type MUST also publish how consumers can parse the application-specific delegation schema.</p> Support for EIP-712</h3> All signatures contained in this specification MUST comply with EIP-712 wherein the signature preimage can be generated from:</p> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span></span> hex</span>"1901"</span>,</span></span> DOMAIN_SEPARATOR</span>,</span></span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span> keccak256</span>(</span>"AssociatedAccountRecord(bytes initiator,bytes approver,uint40 validAt,uint40 validUntil,bytes4 interfaceId,bytes data)"</span>)</span>,</span></span> keccak256</span>(</span>initiator</span>)</span>,</span> </span></span> keccak256</span>(</span>approver</span>)</span>,</span></span> validAt</span>,</span></span> validUntil</span>,</span></span> interfaceId</span>,</span></span> keccak256</span>(</span>data</span>)</span></span> )</span>)</span></span> )</span>)</span></span></code></pre> Where DOMAIN_SEPARATOR</code> is defined according to EIP-712. The DOMAIN_SEPARATOR</code> for this ERC SHALL be defined as:</p> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span> keccak256</span>(</span>"EIP712Domain(string name,string version)"</span>)</span>,</span></span> keccak256</span>(</span>bytes</span>(</span>"AssociatedAccounts"</span>)</span>)</span>,</span></span> keccak256</span>(</span>bytes</span>(</span>"1"</span>)</span>)</span></span> )</span>)</span></span></code></pre>Onchain Storage</h3> If desired, a SignedAssociationRecord</code> MAY be stored onchain in a context-specific storage contract.</p> An onchain storage contract SHALL comply with the following steps:</p> The SAR MUST be validated according to the steps detailed in the Validation section.</li> The contract MUST emit the AssociationCreated</code> event:</li> </ol> event</span> AssociationCreated</span>(</span></span> bytes32</span> indexed</span> hash</span>, </span>bytes32</span> indexed</span> initiator</span>, </span>bytes32</span> indexed</span> approver</span>, </span>SignedAssociationRecord</span> sar</span></span> )</span>;</span></span></code></pre> where:</p> hash</code> is the indexed hash for the SignedAssociationRecord, equivalent to the EIP-712 hash of the underlying AAR.</li> initiator</code> is the keccak256 hash of the ERC-7930 address of the account that initiated the association.</li> approver</code> is the keccak256 hash of the ERC-7930 address of the account that accepted and completed the association.</li> sar</code> is the completed SignedAssociationRecord.</li> </ul> If a SignedAssociationRecord is stored onchain, it MUST also be revokable onchain (see Revocation section below).</p> Offchain Storage</h3> In some contexts, it might be desirable for Signed Association Records to be stored in an offchain store. While the implementation will differ from application-to-application, the following considerations SHOULD be taken into account:</p> Access to this data store MUST be made available to all expected consumers through publicly accessible endpoints</li> The store MUST perform validation on incoming Associations before storage</li> The location of this offchain store SHOULD be searchable by some standard fetching mechanism, e.g. a text record on an ENS name</li> </ul> Validation</h3> Clients or contracts determining whether a SignedAssociationRecord is valid at the time of consumption MUST check all of the following validation steps:</p> The current timestamp MUST be greater than or equal to the validAt</code> timestamp.</li> If the validUntil</code> timestamp is nonzero, the current timestamp MUST be less than the validUntil</code> timestamp.</li> If the revokedAt</code> timestamp is nonzero, the current timestamp MUST be less than the revokedAt</code> timestamp.</li> If the initiatorSignature</code> field is populated, the signature MUST be valid for the EIP-712 preimage of the underlying AssociatedAccountRecord</code> using an appropriate initiatorKeyType</code> validation mechanism.</li> If the approverSignature</code> field is populated, the signature MUST be valid for the EIP-712 preimage of the underlying AssociatedAccountRecord</code> using an appropriate approverKeyType</code> validation mechanism.</li> </ol> Onchain validation is possible as long as there are sufficient validation mechanisms for the various key types used by the two accounts. In the case that validation occurs onchain, implementations MUST replace "current timestamp" with block.timestamp</code>.</p> Revocation</h3> Onchain Association stores MUST implement a revocation method. This method MUST allow either party of an Association to revoke a valid, active association by submitting a revocation request.</p> In such contexts, storage contracts MUST update the revokedAt</code> field of the SAR to block.timestamp</code> OR the account-specified revocation timestamp, whichever is greater. Then the implementation contract MUST emit the following event upon accepting a valid revocation request:</p> event</span> AssociationRevoked</span>(</span>bytes32</span> indexed</span> hash</span>, </span>bytes32</span> indexed</span> revokedBy</span>, </span>uint256</span> revokedAt</span>)</span>;</span></span></code></pre> where:</p> hash</code> is the indexed unique identifier for the association, equivalent to the EIP-712 hash of the underlying AAR.</li> revokedBy</code> is the indexed keccak256 hash of the ERC-7930 address of the revoking account.</li> revokedAt</code> is the timestamp at which the association is revoked.</li> </ul> Offchain stores MUST allow either account to revoke a stored association and MUST update the revokedAt</code> timestamp accordingly.</p> If a previously revoked association is revoked again with an earlier timestamp, the earlier timestamp MUST take precedence.</p> Rationale</h2> Nested Structure Design</h3> The separation of AssociatedAccountRecord</code> and SignedAssociationRecord</code> into distinct structures serves a critical functional purpose. The inner AssociatedAccountRecord</code> contains the immutable association payload that both parties must agree upon. This record can be shared, reviewed, and prepared while signatures are collected asynchronously from each party. The outer SignedAssociationRecord</code> wrapper accumulates these signatures and metadata without modifying the underlying record.</p> Lack of Existing Standards</h3> Currently, no standardized mechanism exists for establishing verifiable associations between blockchain accounts. Existing approaches are either application-specific or rely on proprietary schemas that limit interoperability. This specification addresses that gap by providing a common format that can be adopted across applications, enabling portability and composability of identity relationships.</p> Supporting App-Scoped Sub Accounts</h3> Today's blockchain ecosystem enforces a rigid one-to-one relationship between onchain identities and addresses, limiting users to a single address per identity. This specification breaks that constraint by enabling users to maintain a unified identity across multiple addresses. Users benefit from maintaining separate accounts for different contexts or applications while preserving the ability to verifiably link them to a primary identity when desired. This standard provides the mechanism for establishing these connections, enabling app-scoped sub accounts that can be provably associated with a root identity without sacrificing the flexibility and security benefits of address separation.</p> Storage Agnosticism</h3> Different association types have varying requirements for accessibility, cost, and decentralization. High-value associations requiring maximum trust minimization may warrant onchain storage despite higher costs, while frequent or ephemeral associations may be better suited for offchain stores. By remaining agnostic to storage location and requiring only that validation rules be consistently applied, this specification allows implementers to choose the appropriate tradeoffs for their use case without fragmenting the standard itself.</p> Security Considerations</h2> For onchain applications, the validation mechanisms for some key types might be gas-cost prohibitive or entirely unavailable. It is the responsibility of the integrator to ensure that unsupported key types are appropriately handled given these constraints.</p> Offchain stores expose a trust vector to consumers. Integrators and consumers MUST take into account this centralization vector and expose the risk to users or offer mechanisms for minimizing the trust assumptions (i.e. storing some state onchain).</p> Associations SHOULD have a canonical storage location given an application. However, in the event that the same Association data is stored both on and offchain, precedence SHOULD be given to the onchain data.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Self-Describing Bytes via EIP-712 Selectors 2025-10-30T00:00:00+00:00 Abstract</h2> This ERC standardizes a convention for tagging ABI-encoded structures placed inside bytes</code> parameters with a compact type selector derived from the EIP-712</a> type string. It also defines a canonical multi-payload wrapper, allowing multiple typed payloads to be carried in a single bytes</code> parameter.</p> Motivation</h2> Many smart contract methods use a bytes</code> parameter to support future extensibility—including common standards such as ERC-721</a> and ERC-1155</a>. The convention of carrying extra data in a bytes</code> parameter was also codified further in ERC-5750</a>.</p> In many practical cases, the bytes</code> payload may encode a structured type that must be ABI-decoded before it can be processed. However:</p> Different contracts use different, ad-hoc conventions for distinguishing among possible payloads.</li> A single contract may need to support multiple encodings.</li> In more complex workflows, a payload may be propagated across multiple contracts, each of which may need to parse it differently.</li> </ul> Currently, there is no standardized convention for identifying the "type" of an encoded payload, nor for supporting multiple data items in a single bytes parameter. This ERC defines a minimal, interoperable convention for self-describing payloads that remain compatible with existing ABI tooling.</p> Specification</h2> 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.</p> Terms</h3> Type string</strong> — the canonical EIP-712 type string, e.g. TransferNote(bytes32 reference,string comment,uint256 deadline)</code></li> Type selector (bytes4</code>)</strong> — keccak256(typeString)[0:4]</code></li> Single-payload</strong> — a selector followed by abi.encode</code> of that struct’s fields</li> Multi-payload wrapper</strong> — DataList(bytes[] items)</code>; each items[i]</code> is a valid single-payload</li> </ul> Single-payload encoding</h3> An ABI-encoded struct is prefixed with a 4-byte selector.</li> The selector is defined as the first 4 bytes of the keccak256 hash of its EIP-712 type string.</li> </ul> typeSelector(T) = bytes4(keccak256(bytes(T)))</span></span> encoding = typeSelector(T) ++ abi.encode(<fields of T>)</span></span></code></pre> Example:</p> T = "TransferNote(bytes32 reference,string comment,uint256 deadline)"</span></span> keccak256(T) = 0xf91f3a243a886588394dfd70af07dce0ca18c55e402d76152d4cb300349c9e9d</span></span> selector = 0xf91f3a24</span></span> encoding = 0xf91f3a24 ++ abi.encode(reference, comment, deadline)</span></span></code></pre> A consumer may look for a known selector before attempting to decode the data, and can easily distinguish between multiple different payloads that it knows how to accept.</p> Multi-payload wrapper</h3> Uses a canonical wrapper type DataList(bytes[] items)</code> with selector 0xae74f986</code>.</li> Each element in the items array is itself a single-struct payload (with its own selector).</li> </ul> DataList(bytes[] items)</span></span> selector(DataList) = bytes4(keccak256("DataList(bytes[] items)")) = 0xae74f986</span></span> encoding = 0xae74f986 ++ abi.encode(items)</span></span></code></pre> Each items[i]</code> MUST be a valid single-payload as above. Consumers can look for this well-known selector, and can then decode the list to be scanned recursively for recognized items.</p> Decoding</h3> Read the first 4 bytes as the selector</strong>.</li> If the selector is 0xae74f986</code>, decode the remainder as (bytes[] items)</code> and parse each item recursively.</li> If the selector is another recognized selector, the remainder should be parsed accordingly.</li> Unknown selectors MUST be ignored.</li> Order is not significant; producers SHOULD avoid duplicates.</li> </ul> Rationale</h2> EIP-712 reuse:</strong> avoids new schema syntax and aligns with the signing ecosystem.</li> 4-byte selectors:</strong> mirror Solidity’s function selector convention for compactness.</li> Simple wrapper:</strong> DataList</code> provides multiplexing without special parsing or new ABI rules.</li> </ul> Backwards Compatibility</h2> Existing contracts that already accept arbitrary bytes</code> remain compatible. Contracts unaware of this ERC can continue to treat the payload as opaque.</p> Security Considerations</h2> Payload bounds:</strong> When parsing DataList</code>, consumers should limit items.length</code> and total payload size (for example ≤ 8 items and ≤ 8 KB).</li> Early exit:</strong> Consumers should stop scanning once all expected selectors are found.</li> Unknown data:</strong> Unrecognized items must be ignored safely.</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Groups - Membership Tokens 2025-10-28T00:00:00+00:00 Abstract</h2> This proposal defines a "Group" as an ERC-20</a> token where token balance represents membership level. Groups are standard ERC-20 tokens with the semantic interpretation that holding tokens means membership in the group. Unlike binary membership, this supports threshold-based membership: holding more tokens grants higher membership tiers or privileges. By being pure ERC-20, Groups inherit full compatibility with existing wallets, explorers, and tooling with no additional implementation burden.</p> Motivation</h2> Many applications need addressable groups of accounts with controlled membership and tiered access:</p> DAOs</strong>: Voting power proportional to token holdings</li> Loyalty programs</strong>: Bronze/Silver/Gold tiers based on token balance</li> Access control</strong>: Different features unlocked at different balance thresholds</li> Partner networks</strong>: Minimum token requirements for partnership benefits</li> </ul> The key insight is that any ERC-20 token can represent group membership</strong>:</p> balanceOf(account) == 0</code> → Not a member</li> balanceOf(account) >= threshold</code> → Member at that tier</li> </ul> This approach provides:</p> Zero implementation overhead</strong>: Any ERC-20 token can be a Group</li> Instant tooling compatibility</strong>: Wallets, explorers, DEXs work out of the box</li> Tiered membership</strong>: Different balance thresholds unlock different privileges</li> Transferable membership</strong>: Standard ERC-20 transfers allow membership trading/delegation</li> </ul> Specification</h2> 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.</p> Requirements</h3> A compliant Group contract:</p> MUST</strong> implement ERC-20</a></li> MUST</strong> implement ERC-165</a></li> SHOULD</strong> implement the optional interface defined below for membership introspection</li> </ol> Membership Semantics</h3> Token balance represents membership level:</p> balanceOf(account) == 0</code> → Account is not</strong> a member</li> balanceOf(account) > 0</code> → Account is</strong> a member</li> balanceOf(account) >= threshold</code> → Account qualifies for that membership tier</li> </ul> Applications define their own thresholds. For example:</p> Basic membership: balanceOf(account) >= 1</code></li> Silver tier: balanceOf(account) >= 100 10*decimals</code></li> Gold tier: balanceOf(account) >= 500 10*decimals</code></li> Platinum tier: balanceOf(account) >= 1000 10*decimals</code></li> </ul> Interface (Optional)</h3> Implementations MAY expose a convenience interface for membership checks:</p> //</span> SPDX-License-Identifier: CC0-1.0</span></span> pragma</span> solidity</span> ^0.8.20</span>;</span></span> </span> ///</span> @title</span> IERC8063 — Optional membership introspection for ERC-20 tokens</span></span> interface</span> IERC8063</span> {</span></span> ///</span> @notice</span> Returns true if `account` holds at least `threshold` tokens</span></span> ///</span> @param</span> account</span> The address to check</span></span> ///</span> @param</span> threshold</span> Minimum balance required for membership at this tier</span></span> function</span> isMember</span>(</span>address</span> account</span>,</span> uint256</span> threshold</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> }</span></span></code></pre> If implemented:</p> isMember(account, threshold)</code> MUST return true</code> if and only if balanceOf(account) >= threshold</code>.</li> isMember(account, 0)</code> MUST return true</code> for any account.</li> </ul> ERC-165 Introspection</h3> supportsInterface(0x36372b07)</code> (ERC-20) SHOULD return true</code></li> If the optional interface is implemented, supportsInterface</code> for it SHOULD return true</code></li> </ul> Deployment Model</h3> Following the ERC-20</a> pattern, each group is its own contract deployment:</p> Group identity</strong>: A group is uniquely identified by its contract address.</li> Deployment</strong>: Deploy any ERC-20 token. The token IS the group.</li> Discovery</strong>: Applications can discover groups through Transfer events, registries, or direct address references.</li> Naming</strong>: name()</code> and symbol()</code> follow standard ERC-20 conventions.</li> </ul> Minting and Burning</h3> Minting and burning are implementation-defined</strong>. Groups MAY implement minting/burning using any approach:</p> Standard mint(address, uint256)</code> function</li> ERC-5679</a> compliant mint(address, uint256, bytes)</code></li> No minting after initial supply (fixed membership)</li> Governance-controlled minting</li> Open minting (anyone can join by minting)</li> </ul> The standard does not mandate any specific minting/burning interface.</p> Tiered Benefits Example</h3> Applications define membership tiers externally:</p> //</span> Example: Partner contract checking membership tiers</span></span> contract</span> PartnerBenefits</span> {</span></span> IERC20 </span>public</span> membershipToken</span>;</span></span> </span></span> uint256</span> public</span> constant</span> BRONZE </span>=</span> 100</span> </span> 10</span></span></span>18</span>;</span></span> uint256</span> public</span> constant</span> SILVER </span>=</span> 500</span> </span> 10</span></span></span>18</span>;</span></span> uint256</span> public</span> constant</span> GOLD </span>=</span> 1000</span> </span> 10</span></span></span>18</span>;</span></span> </span></span> function</span> getDiscount</span>(</span>address</span> user</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span> {</span></span> uint256</span> balance </span>=</span> membershipToken</span>.</span>balanceOf</span>(</span>user</span>)</span>;</span></span> if</span> (</span>balance </span>></span>=</span> GOLD</span>)</span> return</span> 30</span>;</span> //</span> 30% off</span></span> if</span> (</span>balance </span>></span>=</span> SILVER</span>)</span> return</span> 20</span>;</span> //</span> 20% off</span></span> if</span> (</span>balance </span>></span>=</span> BRONZE</span>)</span> return</span> 10</span>;</span> //</span> 10% off</span></span> return</span> 0</span>;</span></span> }</span></span> </span></span> function</span> isMember</span>(</span>address</span> user</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span> return</span> membershipToken</span>.</span>balanceOf</span>(</span>user</span>)</span> ></span> 0</span>;</span></span> }</span></span> }</span></span></code></pre>Optional Extensions</h3> Ownership (via ERC-173</a>)</h4> Implementations that want a single-owner governance model MAY use ERC-173</a> or ERC-8023</a> for standardized ownership.</p> Capped Membership (Balance ≤ 1)</h4> For use cases requiring binary membership (member/non-member with no tiers), implementations MAY enforce balanceOf(account) <= 1</code> for all accounts.</p> Rationale</h2> Pure ERC-20</strong>: A Group is simply an ERC-20 token with membership semantics. No new token standard needed.</li> No minting/burning mandate</strong>: Different use cases need different minting policies. The standard doesn't prescribe one.</li> Threshold-based membership</strong>: More flexible than binary membership; supports tiered access, loyalty programs, and proportional voting naturally.</li> Optional interface</strong>: The isMember</code> function is a convenience; applications can directly call balanceOf</code> if preferred.</li> Maximum compatibility</strong>: Any existing ERC-20 token can be interpreted as a Group by applications.</li> </ul> Backwards Compatibility</h2> This standard is fully backwards compatible with ERC-20</a>. In fact, any existing ERC-20 token can be used as a Group</strong> — the standard simply defines how to interpret token balance as membership.</p> Reference Implementation</h2> Reference contracts are provided in the assets/</code> directory:</p> IERC8063.sol</code></a> — Interface definition</li> ERC8063.sol</code></a> — Reference implementation with membership helpers</li> </ul> Security Considerations</h2> Token economics</strong>: Membership is tied to token balance. Consider the implications of token transfers, trading, and price volatility on membership.</li> Threshold manipulation</strong>: If thresholds are stored onchain, ensure they cannot be manipulated by unauthorized parties.</li> Transfer implications</strong>: Token transfers change membership. Consider whether this is desirable for your use case.</li> Approval risks</strong>: Standard ERC-20 approval risks apply. Approving another address grants them ability to transfer your membership tokens.</li> Decimal handling</strong>: Ensure thresholds account for the token's decimals.</li> Minting security</strong>: If minting is permitted, carefully control who can mint to prevent unauthorized membership grants.</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Scaled UI Amount Extension for ERC-20 Tokens 2025-10-20T00:00:00+00:00 Abstract</h2> This EIP proposes a standard extension to ERC-20</a> tokens that enables issuers to apply an updatable multiplier to the UI (user interface) amount of tokens. This allows for efficient representation of stock splits, without requiring actual token minting or transfers. The extension provides a cosmetic layer that modifies how token balances are displayed to users while maintaining the underlying token economics.</p> Motivation</h2> Current ERC-20 implementations lack an efficient mechanism to handle real-world asset scenarios such as stock splits: When a company performs a 2-for-1 stock split, all shareholders should see their holdings double. Currently, this requires minting new tokens to all holders, which is gas-intensive and operationally complex. Moreover, the internal accounting in DeFi protocols would break from such a split.</p> The inability to efficiently handle this scenario limits the adoption of tokenized real-world assets (RWAs) on Ethereum. This EIP addresses these limitations by introducing a multiplier mechanism that adjusts the displayed balance without altering the actual token supply.</p> Specification</h2> 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.</p> Core Interface</h3> Compliant contracts MUST implement the IScaledUIAmount</code> interface:</p> interface</span> IScaledUIAmount</span> {</span></span> //</span> Emitted when the UI multiplier is updated</span></span> event</span> UIMultiplierUpdated</span>(</span>uint256</span> oldMultiplier</span>, </span>uint256</span> newMultiplier</span>, </span>uint256</span> effectiveAtTimestamp</span>)</span>;</span></span> </span> //</span> OPTIONAL: Emitted during a token transfer with the UI-adjusted amount</span></span> event</span> TransferWithUIAmount</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> amount</span>, </span>uint256</span> uiAmount</span>)</span>;</span></span> </span> //</span> Returns the current UI multiplier</span></span> //</span> Multiplier is represented with 18 decimals (1e18 = 1.0)</span></span> function</span> uiMultiplier</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> }</span></span></code></pre> Note: How the multiplier is updated is an implementation detail left to the token issuer. The reference implementation below shows one approach using a setUIMultiplier</code> function with delayed effectiveness.</p> Optional Extension: Conversion</h3> Contracts MAY implement the IScaledUIAmountConversion</code> extension for on-chain conversion helpers:</p> interface</span> IScaledUIAmountConversion</span> {</span></span> //</span> Converts a raw token amount to UI amount</span></span> function</span> toUIAmount</span>(</span>uint256</span> rawAmount</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> </span> //</span> Converts a UI amount to raw token amount</span></span> function</span> fromUIAmount</span>(</span>uint256</span> uiAmount</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> }</span></span></code></pre>Optional Extension: Balances</h3> Contracts MAY implement the IScaledUIAmountBalances</code> extension for on-chain UI balance queries:</p> interface</span> IScaledUIAmountBalances</span> {</span></span> //</span> Returns the UI-adjusted balance of an account</span></span> function</span> balanceOfUI</span>(</span>address</span> account</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> </span> //</span> Returns the UI-adjusted total supply</span></span> function</span> totalSupplyUI</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> }</span></span></code></pre>Interface Detection</h3> Compliant contracts MUST implement ERC-165</a> and return true</code> when queried for the IScaledUIAmount</code> interface ID.</p> Contracts implementing optional extensions MUST also return true</code> for their respective interface IDs.</p> The interface identifiers are:</p> IScaledUIAmount</code>: 0xa60bf13d</code></li> IScaledUIAmountConversion</code>: 0xTBD</code></li> IScaledUIAmountBalances</code>: 0xd890fd71</code></li> </ul> Implementation Requirements:</h3> ERC-165 Support: Compliant contracts MUST implement ERC-165</a> interface detection.</p> </li> Multiplier Precision: The UI multiplier MUST use 18 decimal places for precision (1e18 represents a multiplier of 1.0).</p> </li> Backwards Compatibility: The standard ERC-20 functions (balanceOf, transfer, transferFrom, etc.) MUST continue to work with raw amounts.</p> </li> Event Emission: The UIMultiplierUpdated event MUST be emitted whenever the multiplier is changed.</p> </li> </ol> Reference Implementation</h3> The following implementation includes the core interface and all optional extensions:</p> contract</span> ScaledUIToken</span> is</span></span> ERC20</span>,</span></span> ERC165</span>,</span></span> IScaledUIAmount</span>,</span></span> IScaledUIAmountConversion</span>,</span></span> IScaledUIAmountBalances</span>,</span></span> Ownable</span></span> {</span></span> uint256</span> private</span> constant</span> MULTIPLIER_DECIMALS </span>=</span> 1e18</span>;</span></span> uint256</span> private</span> _uiMultiplier </span>=</span> MULTIPLIER_DECIMALS</span>;</span> //</span> Initially 1.0</span></span> uint256</span> public</span> _nextUiMultiplier </span>=</span> MULTIPLIER_DECIMALS</span>;</span></span> uint256</span> public</span> _nextUiMultiplierEffectiveAt </span>=</span> 0</span>;</span></span> </span> constructor</span>(</span>string</span> memory</span> name</span>,</span> string</span> memory</span> symbol</span>)</span> ERC20</span>(</span>name, symbol) </span>{</span>}</span></span> </span> //</span> ERC-165 interface detection</span></span> function</span> supportsInterface</span>(</span>bytes4</span> interfaceId</span>)</span> public</span> view</span> virtual</span> override</span> returns</span> (</span>bool</span>)</span> {</span></span> return</span></span> interfaceId </span>==</span> type</span>(</span>IScaledUIAmount</span>)</span>.</span>interfaceId </span>\|\|</span></span> interfaceId </span>==</span> type</span>(</span>IScaledUIAmountConversion</span>)</span>.</span>interfaceId </span>\|\|</span></span> interfaceId </span>==</span> type</span>(</span>IScaledUIAmountBalances</span>)</span>.</span>interfaceId </span>\|\|</span></span> super</span>.</span>supportsInterface</span>(</span>interfaceId</span>)</span>;</span></span> }</span></span> </span> //</span> ============ Core Interface ============</span></span> </span> function</span> uiMultiplier</span>(</span>)</span> public</span> view</span> override</span> returns</span> (</span>uint256</span>)</span> {</span></span> uint256</span> currentTime </span>=</span> block</span>.</span>timestamp</span>;</span></span> if</span> (</span>currentTime </span>></span>=</span> _nextUiMultiplierEffectiveAt</span>)</span> {</span></span> return</span> _nextUiMultiplier</span>;</span></span> }</span> else</span> {</span></span> return</span> _uiMultiplier</span>;</span></span> }</span></span> }</span></span> </span> //</span> Implementation-specific: How the multiplier is updated</span></span> function</span> setUIMultiplier</span>(</span>uint256</span> newMultiplier</span>,</span> uint256</span> effectiveAtTimestamp</span>)</span> external</span> onlyOwner</span> {</span></span> require</span>(</span>newMultiplier </span>></span> 0</span>,</span> "Multiplier must be positive"</span>)</span>;</span></span> </span> uint256</span> currentTime </span>=</span> block</span>.</span>timestamp</span>;</span></span> require</span>(</span>effectiveAtTimestamp </span>></span> currentTime</span>,</span> "Effective At must be in the future"</span>)</span>;</span></span> </span> if</span> (</span>currentTime </span>></span> _nextUiMultiplierEffectiveAt</span>)</span> {</span></span> uint256</span> oldMultiplier </span>=</span> _nextUiMultiplier</span>;</span></span> _uiMultiplier </span>=</span> oldMultiplier</span>;</span></span> _nextUiMultiplier </span>=</span> newMultiplier</span>;</span></span> _nextUiMultiplierEffectiveAt </span>=</span> effectiveAtTimestamp</span>;</span></span> emit</span> UIMultiplierUpdated</span>(</span>oldMultiplier</span>,</span> newMultiplier</span>,</span> effectiveAtTimestamp</span>)</span>;</span></span> }</span> else</span> {</span></span> uint256</span> oldMultiplier </span>=</span> _uiMultiplier</span>;</span></span> _nextUiMultiplier </span>=</span> newMultiplier</span>;</span></span> _nextUiMultiplierEffectiveAt </span>=</span> effectiveAtTimestamp</span>;</span></span> emit</span> UIMultiplierUpdated</span>(</span>oldMultiplier</span>,</span> newMultiplier</span>,</span> effectiveAtTimestamp</span>)</span>;</span></span> }</span></span> }</span></span> </span> //</span> ============ Optional: Conversion Extension ============</span></span> </span> function</span> toUIAmount</span>(</span>uint256</span> rawAmount</span>)</span> public</span> view</span> override</span> returns</span> (</span>uint256</span>)</span> {</span></span> uint256</span> currentTime </span>=</span> block</span>.</span>timestamp</span>;</span></span> if</span> (</span>currentTime </span>></span>=</span> _nextUiMultiplierEffectiveAt</span>)</span> {</span></span> return</span> (</span>rawAmount </span></span> _nextUiMultiplier</span>)</span> /</span> MULTIPLIER_DECIMALS</span>;</span></span> }</span> else</span> {</span></span> return</span> (</span>rawAmount </span></span> _uiMultiplier</span>)</span> /</span> MULTIPLIER_DECIMALS</span>;</span></span> }</span></span> }</span></span> </span> function</span> fromUIAmount</span>(</span>uint256</span> uiAmount</span>)</span> public</span> view</span> override</span> returns</span> (</span>uint256</span>)</span> {</span></span> uint256</span> currentTime </span>=</span> block</span>.</span>timestamp</span>;</span></span> if</span> (</span>currentTime </span>></span>=</span> _nextUiMultiplierEffectiveAt</span>)</span> {</span></span> return</span> (</span>uiAmount </span></span> MULTIPLIER_DECIMALS</span>)</span> /</span> _nextUiMultiplier</span>;</span></span> }</span> else</span> {</span></span> return</span> (</span>uiAmount </span></span> MULTIPLIER_DECIMALS</span>)</span> /</span> _uiMultiplier</span>;</span></span> }</span></span> }</span></span> </span> //</span> ============ Optional: Balances Extension ============</span></span> </span> function</span> balanceOfUI</span>(</span>address</span> account</span>)</span> public</span> view</span> override</span> returns</span> (</span>uint256</span>)</span> {</span></span> return</span> toUIAmount</span>(</span>balanceOf</span>(</span>account</span>)</span>)</span>;</span></span> }</span></span> </span> function</span> totalSupplyUI</span>(</span>)</span> public</span> view</span> override</span> returns</span> (</span>uint256</span>)</span> {</span></span> return</span> toUIAmount</span>(</span>totalSupply</span>(</span>)</span>)</span>;</span></span> }</span></span> </span> //</span> ============ Optional: TransferWithUIAmount Event ============</span></span> </span> function</span> _update</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> amount</span>)</span> internal</span> virtual</span> override</span> {</span></span> super</span>.</span>_update</span>(</span>from</span>,</span> to</span>,</span> amount</span>)</span>;</span></span> uint256</span> uiAmount </span>=</span> toUIAmount</span>(</span>amount</span>)</span>;</span></span> emit</span> TransferWithUIAmount</span>(</span>from</span>,</span> to</span>,</span> amount</span>,</span> uiAmount</span>)</span>;</span></span> }</span></span> }</span></span></code></pre>Rationale</h2> Design Decisions:</p> Separate UI Functions: Rather than modifying the core ERC-20 functions, we provide separate UI-specific functions. This ensures backward compatibility and allows integrators to opt-in to the UI scaling feature.</p> </li> 18 Decimal Precision: Using 18 decimals for the multiplier provides sufficient precision for most use cases while aligning with Ethereum's standard decimal representation.</p> </li> No Automatic Updates: The multiplier must be explicitly set by authorized parties, giving issuers full control over when and how adjustments are made.</p> </li> Raw Amount Preservation: All actual token operations continue to use raw amounts, ensuring that the multiplier is purely a display feature and doesn't affect the underlying token economics.</p> </li> Optional Extensions: Following the pattern established by ERC-721</a> and ERC-1155</a>, helper functions like toUIAmount</code>, fromUIAmount</code>, balanceOfUI</code>, and totalSupplyUI</code> are defined in separate optional interfaces. The TransferWithUIAmount</code> event is defined in the core interface as optional since events do not affect interface IDs. This keeps the core interface minimal while allowing contracts to opt-in to additional on-chain functionality. Integrators can detect support for these extensions using ERC-165</a> interface detection.</p> </li> </ol> Alternative Approaches Considered:</p> Rebasing Tokens: While rebasing tokens adjust supply automatically, they create complexity for integrators and can break composability with DeFi protocols.</p> </li> Wrapper Tokens: Creating wrapper tokens for each adjustment event adds unnecessary complexity and gas costs.</p> </li> Index/Exchange Rate Tokens confer similar advantages to the proposed Scaled UI approach, but is ultimately less intuitive and requires more calculations on the UI layers.</p> </li> Off-chain Solutions: Purely off-chain solutions lack standardization and require trust in centralized providers.</p> </li> </ol> </p> </p> Backwards Compatibility</h3> This EIP is fully backwards compatible with ERC-20. Existing ERC-20 functions continue to work as expected, and the UI scaling features are opt-in through additional functions.</p> Test Cases</h3> Example test scenarios:</p> Initial Multiplier Test:</li> </ol> Verify that initial multiplier is 1.0 (1e18)</p> </li> Confirm balanceOf equals balanceOfUI initially</p> </li> </ul> Stock Split Test:</li> </ol> Set multiplier to 2.0 (2e18) for 2-for-1 split</p> </li> Verify UI balance is double the raw balance</p> </li> Confirm conversion functions work correctly</p> </li> </ul> Security Considerations</h2> Multiplier Manipulation</li> </ol> Unauthorized changes to the UI multiplier could mislead users about their holdings</p> </li> Implementations MUST use robust access control mechanisms</p> </li> The setUIMultiplier function MUST be restricted to authorized addresses (e.g., contract owner or a designated role).</p> </li> </ul> Integer Overflow</li> </ol> Risk of overflow when applying the multiplier</p> </li> Use SafeMath or Solidity 0.8.0+ automatic overflow protection</p> </li> </ul> User Confusion</li> </ol> Clear communication is essential when UI amounts differ from raw amounts</p> </li> Integrators MUST clearly indicate when displaying UI-adjusted balances</p> </li> </ul> Oracle Dependency</li> </ol> For automated multiplier updates, the system may depend on oracles</p> </li> Oracle failures or manipulations could affect displayed balances</p> </li> </ul> Overflow Protection: Implementations MUST handle potential overflow when applying the multiplier.</li> </ol> Implementation Guide for Integrators</h3> Wallet Integration</h4> Wallets supporting this standard should:</p> Check if a token implements IScaledUIAmount</code> interface using ERC-165</p> </li> Optionally check for IScaledUIAmountBalances</code> extension for on-chain balance queries</p> </li> Display both raw and UI amounts, clearly labeled</p> </li> Compute UI balance off-chain using balanceOf()</code> and uiMultiplier()</code>, or use balanceOfUI()</code> if the extension is supported</p> </li> Handle transfers using raw amounts (standard ERC-20 functions)</p> </li> </ol> Example JavaScript integration:</strong></p> const</span> MULTIPLIER_DECIMALS</span> =</span> BigInt</span>(</span>1e18</span>)</span>;</span></span> </span> //</span> Interface IDs for ERC-165 detection</span></span> const</span> ISCALED_UI_AMOUNT_ID</span> =</span> "</span>0xa60bf13d</span>"</span>;</span></span> const</span> ISCALED_UI_BALANCES_ID</span> =</span> "</span>0xd890fd71</span>"</span>;</span></span> </span> //</span> Off-chain conversion functions</span></span> function</span> toUIAmount</span>(</span>rawAmount</span>,</span> multiplier</span>)</span> {</span></span> return</span> (</span>BigInt</span>(</span>rawAmount</span>)</span> </span> BigInt</span>(</span>multiplier</span>)</span>)</span> /</span> MULTIPLIER_DECIMALS</span>;</span></span> }</span></span> </span> function</span> fromUIAmount</span>(</span>uiAmount</span>,</span> multiplier</span>)</span> {</span></span> return</span> (</span>BigInt</span>(</span>uiAmount</span>)</span> </span> MULTIPLIER_DECIMALS</span>)</span> /</span> BigInt</span>(</span>multiplier</span>)</span>;</span></span> }</span></span> </span> async</span> function</span> displayBalance</span>(</span>tokenAddress</span>,</span> userAddress</span>)</span> {</span></span> const</span> token</span> =</span> new</span> ethers</span>.</span>Contract</span>(</span>tokenAddress</span>,</span> ScaledUIAmountABI</span>,</span> provider</span>)</span>;</span></span> </span> //</span> Check if core scaled UI is supported</span></span> const</span> supportsScaledUI</span> =</span> await</span> token</span>.</span>supportsInterface</span>(</span>ISCALED_UI_AMOUNT_ID</span>)</span>;</span></span> </span> if</span> (</span>!</span>supportsScaledUI</span>)</span> {</span></span> //</span> Fall back to standard ERC-20</span></span> const</span> balance</span> =</span> await</span> token</span>.</span>balanceOf</span>(</span>userAddress</span>)</span>;</span></span> return</span> {</span></span> display</span>:</span> formatUnits</span>(</span>balance</span>,</span> decimals</span>)</span>,</span></span> raw</span>:</span> formatUnits</span>(</span>balance</span>,</span> decimals</span>)</span>,</span></span> multiplier</span>:</span> "</span>1.0</span>"</span></span> }</span>;</span></span> }</span></span> </span> //</span> Check if optional balances extension is supported</span></span> const</span> supportsBalancesExt</span> =</span> await</span> token</span>.</span>supportsInterface</span>(</span>ISCALED_UI_BALANCES_ID</span>)</span>;</span></span> </span> const</span> rawBalance</span> =</span> await</span> token</span>.</span>balanceOf</span>(</span>userAddress</span>)</span>;</span></span> const</span> multiplier</span> =</span> await</span> token</span>.</span>uiMultiplier</span>(</span>)</span>;</span></span> </span> //</span> Use on-chain balanceOfUI if available, otherwise compute off-chain</span></span> const</span> uiBalance</span> =</span> supportsBalancesExt</span></span> ?</span> await</span> token</span>.</span>balanceOfUI</span>(</span>userAddress</span>)</span></span> :</span> toUIAmount</span>(</span>rawBalance</span>,</span> multiplier</span>)</span>;</span></span> </span> return</span> {</span></span> display</span>:</span> formatUnits</span>(</span>uiBalance</span>,</span> decimals</span>)</span>,</span></span> raw</span>:</span> formatUnits</span>(</span>rawBalance</span>,</span> decimals</span>)</span>,</span></span> multiplier</span>:</span> formatUnits</span>(</span>multiplier</span>,</span> 18</span>)</span></span> }</span>;</span></span> }</span></span></code></pre>Exchange Integration</h4> Exchanges should:</p> Store and track the multiplier for each supported token</p> </li> Display UI amounts in user interfaces</p> </li> Use raw amounts for all internal accounting</p> </li> Provide clear documentation about the scaling mechanism</p> </li> </ol> Example implementation:</p> const</span> MULTIPLIER_DECIMALS</span> =</span> BigInt</span>(</span>1e18</span>)</span>;</span></span> </span> class</span> ScaledTokenHandler</span> {</span></span> //</span> Off-chain conversion functions</span></span> toUIAmount</span>(</span>rawAmount</span>,</span> multiplier</span>)</span> {</span></span> return</span> (</span>BigInt</span>(</span>rawAmount</span>)</span> </span> BigInt</span>(</span>multiplier</span>)</span>)</span> /</span> MULTIPLIER_DECIMALS</span>;</span></span> }</span></span> </span> fromUIAmount</span>(</span>uiAmount</span>,</span> multiplier</span>)</span> {</span></span> return</span> (</span>BigInt</span>(</span>uiAmount</span>)</span> </span> MULTIPLIER_DECIMALS</span>)</span> /</span> BigInt</span>(</span>multiplier</span>)</span>;</span></span> }</span></span> </span> async</span> processDeposit</span>(</span>tokenAddress</span>,</span> amount</span>,</span> isUIAmount</span>)</span> {</span></span> const</span> token</span> =</span> new</span> ethers</span>.</span>Contract</span>(</span>tokenAddress</span>,</span> ScaledUIAmountABI</span>,</span> provider</span>)</span>;</span></span> </span> let</span> rawAmount</span>;</span></span> if</span> (</span>isUIAmount</span> &&</span> await</span> this</span>.</span>supportsScaledUI</span>(</span>tokenAddress</span>)</span>)</span> {</span></span> const</span> multiplier</span> =</span> await</span> token</span>.</span>uiMultiplier</span>(</span>)</span>;</span></span> rawAmount</span> =</span> this</span>.</span>fromUIAmount</span>(</span>amount</span>,</span> multiplier</span>)</span>;</span></span> }</span> else</span> {</span></span> rawAmount</span> =</span> amount</span>;</span></span> }</span></span> </span> //</span> Process deposit with raw amount</span></span> return</span> this</span>.</span>recordDeposit</span>(</span>tokenAddress</span>,</span> rawAmount</span>)</span>;</span></span> }</span></span> </span> async</span> getDisplayBalance</span>(</span>tokenAddress</span>,</span> userAddress</span>)</span> {</span></span> const</span> token</span> =</span> new</span> ethers</span>.</span>Contract</span>(</span>tokenAddress</span>,</span> ScaledUIAmountABI</span>,</span> provider</span>)</span>;</span></span> const</span> rawBalance</span> =</span> await</span> this</span>.</span>getInternalBalance</span>(</span>userAddress</span>,</span> tokenAddress</span>)</span>;</span></span> </span> if</span> (</span>await</span> this</span>.</span>supportsScaledUI</span>(</span>tokenAddress</span>)</span>)</span> {</span></span> const</span> multiplier</span> =</span> await</span> token</span>.</span>uiMultiplier</span>(</span>)</span>;</span></span> return</span> this</span>.</span>toUIAmount</span>(</span>rawBalance</span>,</span> multiplier</span>)</span>;</span></span> }</span></span> return</span> rawBalance</span>;</span></span> }</span></span> }</span></span> </span></code></pre>DeFi Protocol Integration</h4> DeFi protocols should:</p> Continue using raw amounts for all protocol operations</p> </li> Provide UI helpers for displaying adjusted amounts</p> </li> Emit events with both raw and UI amounts where relevant</p> </li> Document clearly which amounts are used in calculations</p> </li> </ol> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Zero Knowledge Token Wrapper 2025-10-18T00:00:00+00:00 Abstract</h2> This ERC defines a standard for the Zero Knowledge Token Wrapper, a wrapper that adds privacy to tokens — including ERC-20</a>, ERC-721</a>, ERC-1155</a> and ERC-6909</a> — while preserving all of the tokens' original properties, such as transferability, tradability, and composability. It specifies EIP-7503</a>-style provable burn-and-remint flows, enabling users to break on-chain traceability and making privacy a native feature of all tokens on Ethereum.</p> Motivation</h2> Most existing tokens lack native privacy due to regulatory, technical, and issuer-side neglect. Users seeking privacy must rely on dedicated privacy blockchains or privacy-focused dApps, which restrict token usability, reduce composability, limit supported token types, impose whitelists, and constrain privacy schemes.</p> This ERC takes a different approach by introducing a zero knowledge token wrapper that preserves the underlying token’s properties while adding privacy. Its primary goals are:</p> Pluggable privacy: the wrapper preserves all properties of the underlying token while adding privacy.</li> Permissionless privacy: any user can wrap any token into a Zero Knowledge Wrapped Token (ZWToken).</li> Broad token support: compatible with both fungible tokens (e.g., ETH, ERC-20) and non-fungible tokens (e.g., ERC-721).</li> EIP-7503-style privacy: supports provable burn-and-remint flows to achieve high-level privacy.</li> Compatibility with multiple EIP-7503 schemes: supports different provable burn address generation methods and commitment schemes (e.g., Ethereum-native MPT state tree or contract-managed commitments).</li> </ul> Specification</h2> The key words MUST</strong>, MUST NOT</strong>, SHOULD</strong>, SHOULD NOT</strong>, and MAY</strong> in this document are to be interpreted as described in RFC 2119 and RFC 8174.</p> Overview</h3> A Zero Knowledge Wrapped Token (ZWToken) is a wrapped token minted by a Zero Knowledge Token Wrapper. It adds a commitment-based privacy layer to existing tokens, including ERC-20, ERC-721, ERC-1155, ERC-6909. This privacy layer allows private transfers without modifying the underlying token standard, while preserving full composability with existing Ethereum infrastructure.</p> The commitment mechanism underlying this privacy layer may be implemented using Merkle trees, cryptographic accumulators, or any other verifiable cryptographic structure.</p> A Zero Knowledge Wrapped Token (ZWToken) provides the following core functionalities:</p> The ZWToken recipient can be a provable burn address, from which the tokens can later be reminted.</p> Deposit: Wraps an existing token and mints ZWToken to the specified recipient.</li> Transfer: Transfers ZWToken to the specified recipient.</li> Remint: Mints new ZWTokens to the specified recipient after verifying a zero-knowledge proof demonstrating ownership of previously burnt tokens, without revealing the link between them.</li> Withdraw: Burns ZWTokens to redeem the underlying tokens to the specified recipient.</li> </ul> Privacy Features by Token Type</h4> For fungible tokens (FTs), e.g., ERC-20:</p> This ERC enables breaking the traceability of fund flows through the burn and remint processes.</li> The use of provable burn addresses hides the true holder of fungible tokens until the holder performs a withdraw operation of ZWToken.</li> </ul> For non-fungible tokens (NFTs), e.g., ERC-721:</p> This ERC cannot</strong> break the traceability of fund flows through burn and remint, since each NFT is unique and cannot participate in coin-mixing.</li> However, the use of provable burn addresses can still conceal the true holder of the NFT until the holder performs a withdraw operation of ZWToken.</li> </ul> ZWToken-aware Workflow</h4> In the ZWToken-aware workflow, both the user and the system explicitly recognize and interact with ZWToken. ZWToken inherits all functional properties of the underlying token.</p> </p> For example, if the underlying token is ERC-20, ZWToken can be traded on DEXs, used for swaps, liquidity provision, or standard transfers. Similar to how holding WETH provides additional benefits over holding ETH directly, users may prefer to hold ZWToken rather than the underlying token.</p> ZWToken-unaware Workflow</h4> This ERC also supports a ZWToken-unaware workflow. In this mode, all transfers are internally handled through ZWToken, but users remain unaware of its existence.</p> </p> ZWToken functions transparently beneath the user interface, reducing the number of required contract interactions and improving overall user experience for those who prefer not to hold ZWToken directly.</p> Alternative Workflows</h4> The two workflows described above represent only a subset of the interaction patterns supported by this ERC. Additional workflows are also possible, including:</p> Reminting by the recipient:</strong> Alice may transfer</code> (in the ZWToken-aware workflow) or deposit</code> (in the ZWToken-unaware workflow) ZWToken to Bob’s provable burn address</strong> instead of her own. In this case, the remint operation is initiated and proven by Bob rather than Alice</strong>.</p> </li> Recursive reminting:</strong> A reminted ZWToken may also be sent to another provable burn address</strong> controlled by Bob instead of his public address, allowing the privacy state to persist across multiple remint cycles.</p> </li> </ul> The interface:</p> interface</span> IERC8065</span> is</span> IERC165</span> {</span></span> struct</span> RemintData</span> {</span></span> bytes32</span> commitment</span>;</span></span> bytes32</span>[</span>]</span> nullifiers</span>;</span></span> bytes</span> proverData</span>;</span></span> bytes</span> relayerData</span>;</span></span> bool</span> redeem</span>;</span></span> bytes</span> proof</span>;</span></span> }</span></span> </span> //</span> Optional</span></span> event</span> CommitmentUpdated</span>(</span>uint256</span> indexed</span> id</span>, </span>bytes32</span> indexed</span> commitment</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> amount</span>)</span>;</span></span> </span> event</span> Deposited</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>)</span>;</span></span> </span> event</span> Withdrawn</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>)</span>;</span></span> </span> event</span> Reminted</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>, </span>bool</span> redeem</span>)</span>;</span></span> </span> function</span> deposit</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> payable</span>;</span></span> </span> function</span> withdraw</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span>;</span></span> </span> function</span> remint</span>(</span></span> address</span> to</span>,</span></span> uint256</span> id</span>,</span></span> uint256</span> amount</span>,</span></span> RemintData</span> calldata</span> data</span></span> )</span> external</span>;</span></span> </span> //</span> Optional</span></span> function</span> previewDeposit</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> </span> //</span> Optional</span></span> function</span> previewWithdraw</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> </span> //</span> Optional</span></span> function</span> previewRemint</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> RemintData</span> calldata</span> data</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> </span> function</span> getLatestCommitment</span>(</span>uint256</span> id</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span> </span> function</span> hasCommitment</span>(</span>uint256</span> id</span>,</span> bytes32</span> commitment</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> </span> //</span> Optional</span></span> function</span> getCommitLeafCount</span>(</span>uint256</span> id</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> </span> //</span> Optional</span></span> function</span> getCommitLeaves</span>(</span>uint256</span> id</span>,</span> uint256</span> startIndex</span>,</span> uint256</span> length</span>)</span></span> external</span> view</span> returns</span> (</span>bytes32</span>[</span>]</span> memory</span> commitHashes</span>,</span> address</span>[</span>]</span> memory</span> recipients</span>,</span> uint256</span>[</span>]</span> memory</span> amounts</span>)</span>;</span></span> </span> function</span> getUnderlying</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span> }</span></span></code></pre>Deposit / Wrap</h3> ///</span> @notice</span> Deposits a specified amount of the underlying asset and mints the corresponding amount of ZWToken to the given address.</span></span> ///</span> @dev</span></span> ///</span> If the underlying asset is an ERC-20/ERC-721/ERC-1155/ERC-6909 token, the caller must approve this contract to transfer the specified `amount` beforehand.</span></span> ///</span> If the underlying asset is ETH, the caller should send the deposit value along with the transaction (`msg.value`), and `msg.value` MUST be equal to `amount`.</span></span> ///</span> @param</span> to</span> The address that will receive the minted ZWTokens.</span></span> ///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> ///</span> @param</span> amount</span> The amount of the underlying asset to deposit.</span></span> ///</span> @param</span> data</span> Additional data for extensibility, such as fee information, callback data, or metadata.</span></span> function</span> deposit</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> payable</span>;</span></span></code></pre> Depositor SHOULD be msg.sender</code>.</p> </li> The function MUST transfer the specified amount</code> of the underlying asset from depositor</code> to the ZWToken contract.</p> If the underlying asset is an ERC-20, ERC-721, ERC-1155 or ERC-6909 token, the caller MUST approve this contract to transfer the specified amount</code> beforehand.</li> If the underlying asset is ETH, the caller MUST send the deposit value along with the transaction (msg.value</code>), and msg.value</code> MUST be equal to amount</code>.</li> </ul> </li> The function SHOULD mint ZWToken to the recipient to</code>. The amount minted MAY be reduced by fees as defined by the implementation.</p> </li> Commitment Update:</p> For contract-level commitment schemes, since to may be a provable burn address, the implementation SHOULD update the corresponding commitment. However, this MAY be optimized: if to</code> == depositor</code>, the implementation MAY skip updating the commitment, as depositor</code> cannot be a provable burn address (otherwise the transaction could not be initiated).</li> </ul> </li> For protocol-level commitment schemes (e.g., Ethereum’s native Merkle Patricia Trie), the commitment (e.g., state root or block hash) is automatically updated by the protocol.</li> </ul> </li> The function MUST emit a Deposited(depositor, to, id, amount)</code> event upon successful deposit.</p> The amount</code> parameter in the Deposited</code> event represents the net amount of ZWToken received by to</code> after deducting applicable fees, rather than the amount of underlying tokens deposited.</li> </ul> </li> The data</code> parameter is reserved for future extensibility and MAY be used to pass additional information such as fee configurations, callback data, or metadata. Implementations MAY ignore this parameter if not needed.</p> </li> </ul> Withdraw / Unwrap</h3> ///</span> @notice</span> Withdraw underlying tokens by burning ZWToken</span></span> ///</span> @param</span> to</span> The recipient address that will receive the underlying token</span></span> ///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> ///</span> @param</span> amount</span> The amount of ZWToken to burn and redeem for the underlying token</span></span> ///</span> @param</span> data</span> Additional data for extensibility, such as fee information, callback data, or metadata.</span></span> function</span> withdraw</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span>;</span></span></code></pre> Withdrawer SHOULD be msg.sender</code>.</li> The function MUST burn the specified amount</code> of ZWToken from withdrawer.</li> The function SHOULD transfer underlying token to the recipient to</code>. The amount transferred MAY be reduced by fees as defined by the implementation.</li> The function MUST emit a Withdrawn(withdrawer, to, id, amount)</code> event upon successful withdrawal. The amount</code> parameter in the Withdrawn</code> event represents the net amount of underlying tokens received by to</code> after deducting applicable fees, rather than the amount of ZWToken burned.</li> </ul> </li> The data</code> parameter is reserved for future extensibility and MAY be used to pass additional information such as fee configurations, callback data, or metadata. Implementations MAY ignore this parameter if not needed.</li> </ul> Transfer and Update Commitment</h3> The Zero Knowledge Wrapped Token (ZWToken) remains fully compatible with the underlying token’s transfer interface, while extending it to support privacy-preserving operations. When a ZWToken is transferred to a provable burn address, those tokens MUST be eligible for reminting through the remint interface, effectively breaking the traceability of the fund flow.</li> A provable burn address MAY take various forms (e.g., as defined in EIP-7503). Its essential properties are: Such addresses MUST NOT be operable by any user and MUST be provably non-correspondent to any externally owned account (EOA) or smart contract.</li> Only the entity that generates the burn address MAY derive it, for example, through a signature-derived or deterministic generation scheme.</li> </ul> </li> </ul> </li> Commitment Update: For commitment schemes maintained at the contract level: If the recipient is identified as a provable burn address, the contract MUST update the commitment. Example — a recipient that has previously sent any ZWToken MUST NOT be a provable burn address, since such addresses are incapable of initiating outgoing transfers. In this case, commitment update is not required.</li> </ul> </li> </ul> </li> For protocol-level commitment schemes (e.g., Ethereum’s native MPT tree), the contract does not need to manage any commitment state, since the protocol layer already provides verifiable commitment structures.</li> </ul> </li> </ul> Remint</h3> ///</span> @notice</span> Encapsulates all data required for remint operations</span></span> ///</span> @param</span> commitment</span> The commitment (Merkle root) corresponding to the provided proof</span></span> ///</span> @param</span> nullifiers</span> Array of unique nullifiers used to prevent double-remint</span></span> ///</span> @param</span> proverData</span> Generic data for the prover. The meaning and encoding are implementation-specific (e.g., a circuit identifier/version).</span></span> ///</span> @param</span> relayerData</span> Generic data for the relayer. The meaning and encoding are implementation-specific (e.g., fee information).</span></span> ///</span> @param</span> redeem</span> If true, withdraws the equivalent underlying token instead of reminting ZWToken</span></span> ///</span> @param</span> proof</span> Zero-knowledge proof bytes verifying ownership of the provable burn address</span></span> struct</span> RemintData</span> {</span></span> bytes32</span> commitment</span>;</span></span> bytes32</span>[</span>]</span> nullifiers</span>;</span></span> bytes</span> proverData</span>;</span></span> bytes</span> relayerData</span>;</span></span> bool</span> redeem</span>;</span></span> bytes</span> proof</span>;</span></span> }</span></span> </span> ///</span> @notice</span> Remint ZWToken using a zero-knowledge proof to unlink the source of funds</span></span> ///</span> @param</span> to</span> Recipient address that will receive the reminted ZWToken or the underlying token</span></span> ///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> ///</span> @param</span> amount</span> Amount of ZWToken burned from the provable burn address for reminting</span></span> ///</span> @param</span> data</span> Encapsulated remint data including commitment, nullifiers, redeem flag, proof, and relayer information</span></span> function</span> remint</span>(</span></span> address</span> to</span>,</span></span> uint256</span> id</span>,</span></span> uint256</span> amount</span>,</span></span> RemintData</span> calldata</span> data</span></span> )</span> external</span>;</span></span></code></pre> The function MUST verify the zero-knowledge proof proof against the provided commitment to ensure:</p> Ownership of the provable burn address.</li> Correctness parameters of remint</code>, i.e., the zk proof public inputs. address</span> to</span>,</span></span> uint256</span> id</span>,</span></span> uint256</span> amount</span>,</span></span> RemintData </span>calldata</span> data </span>//</span> All fields except data.proof are used as public inputs for zk proof verification</span></span></code></pre></li> </ul> </li> Reminter SHOULD be msg.sender</code>.</p> </li> The function MUST validate the input data.commitment</code> to ensure it exists.</p> </li> The function MUST ensure that none of the data.nullifiers</code> have been used previously. Reuse of any nullifier MUST revert the transaction.</p> This supports batch reminting in a single proof by allowing multiple nullifiers to be provided and consumed atomically.</li> </ul> </li> Upon successful verification:</p> If data.redeem</code> is false, the function MUST mint ZWToken to the recipient to</code>. The amount minted MAY be reduced by fees as defined by the implementation. In this case, the function MUST emit the Reminted</code> event after a successful remint of ZWToken.</li> </ul> </li> If data.redeem</code> is true, the function MUST transfer underlying token to the recipient to</code>. The amount transferred MAY be reduced by fees as defined by the implementation. In this case, the function MUST emit the Reminted</code> event after a successful withdrawal of the underlying token.</li> </ul> </li> The net tokens received by the recipient to</code> MAY be reduced by relayer fees if the relayer charges a fee (as specified in data.relayerData</code>).</li> The function MUST mark each</strong> nullifier in data.nullifiers</code> as spent to prevent double-spending.</li> </ul> </li> The function MUST emit a Reminted(reminter, to, id, amount, data.redeem)</code> event upon successful remint.</p> The amount</code> parameter in the Reminted</code> event represents the net amount of underlying tokens or ZWToken received by to</code> after all applicable fees have been deducted.</li> </ul> </li> </ul> Preview Functions (Optional)</h3> Since the actual token amounts received may differ from the input amounts due to implementation-specific factors (e.g., fees), users need a standardized way to determine the exact amounts they will receive. Following the design pattern established by ERC-4626</a>, the preview functions allow users to simulate the effects of their operations at the current block, returning values as close to and no more than the exact amounts that would result from the corresponding mutable operations if called in the same transaction.</p> ///</span> @notice</span> OPTIONAL: Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block.</span></span> ///</span> @dev</span> MUST return as close to and no more than the exact amount of ZWToken that would be minted in a `deposit` call in the same transaction.</span></span> ///</span> @param</span> to</span> The address that will receive the minted ZWTokens.</span></span> ///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> ///</span> @param</span> amount</span> The amount of underlying tokens to deposit.</span></span> ///</span> @param</span> data</span> Additional data for extensibility, such as fee information.</span></span> ///</span> @return</span> The</span> amount of ZWToken that would be minted to the recipient after deducting applicable fees.</span></span> function</span> previewDeposit</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span></code></pre> previewDeposit(address to, uint256 id, uint256 amount, bytes calldata data)</code>: OPTIONAL. Returns the exact amount of ZWToken that would be minted for the specified amount of underlying tokens. MUST be inclusive of deposit fees. Integrators SHOULD be aware of the existence of deposit fees.</li> MUST NOT revert due to implementation-specific user/global limits.</li> MAY revert due to other conditions that would also cause deposit</code> to revert.</li> </ul> </li> </ul> ///</span> @notice</span> OPTIONAL: Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block.</span></span> ///</span> @dev</span> MUST return as close to and no more than the exact amount of underlying tokens that would be received in a `withdraw` call in the same transaction.</span></span> ///</span> @param</span> to</span> The recipient address that will receive the underlying token.</span></span> ///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> ///</span> @param</span> amount</span> The amount of ZWToken to burn.</span></span> ///</span> @param</span> data</span> Additional data for extensibility, such as fee information.</span></span> ///</span> @return</span> The</span> amount of underlying tokens that would be received by the recipient after deducting applicable fees.</span></span> function</span> previewWithdraw</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span></code></pre> previewWithdraw(address to, uint256 id, uint256 amount, bytes calldata data)</code>: OPTIONAL. Returns the exact amount of underlying tokens that would be received for burning the specified amount of ZWToken. MUST be inclusive of withdrawal fees. Integrators SHOULD be aware of the existence of withdrawal fees.</li> MUST NOT revert due to implementation-specific user/global limits.</li> MAY revert due to other conditions that would also cause withdraw</code> to revert.</li> </ul> </li> </ul> ///</span> @notice</span> OPTIONAL: Allows an on-chain or off-chain user to simulate the effects of their remint at the current block.</span></span> ///</span> @dev</span> MUST return as close to and no more than the exact amount of ZWToken or underlying tokens that would be received in a `remint` call in the same transaction.</span></span> ///</span> @param</span> to</span> Recipient address that will receive the reminted ZWToken or the underlying token.</span></span> ///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> ///</span> @param</span> amount</span> The amount of ZWToken burned from the provable burn address for reminting.</span></span> ///</span> @param</span> data</span> Encapsulated remint data including commitment, nullifiers, redeem flag, proof, and relayer information.</span></span> ///</span> @return</span> The</span> amount of ZWToken or underlying tokens that would be received by the recipient after all applicable fees have been deducted.</span></span> function</span> previewRemint</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> RemintData</span> calldata</span> data</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span></code></pre> previewRemint(address to, uint256 id, uint256 amount, RemintData calldata data)</code>: OPTIONAL. Returns the exact amount of ZWToken (or underlying tokens if data.redeem</code> is true) that would be received for a remint operation. MUST be inclusive of all applicable fees, including remint fees and relayer fees (as specified in data.relayerData</code>).</li> MUST NOT revert due to implementation-specific user/global limits.</li> MAY revert due to other conditions that would also cause remint</code> to revert.</li> </ul> </li> </ul> Query Interfaces</h3> ///</span> @notice</span> Returns the current top-level commitment representing the privacy state</span></span> ///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> ///</span> @return</span> The</span> latest root hash of the commitment tree</span></span> function</span> getLatestCommitment</span>(</span>uint256</span> id</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span> </span> ///</span> @notice</span> Checks if a specific top-level commitment exists</span></span> ///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> ///</span> @param</span> commitment</span> The root hash to verify</span></span> ///</span> @return</span> True</span> if the commitment exists, false otherwise</span></span> function</span> hasCommitment</span>(</span>uint256</span> id</span>,</span> bytes32</span> commitment</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> </span> ///</span> @notice</span> OPTIONAL: Returns the total number of commitment leaves stored</span></span> ///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> ///</span> @return</span> The</span> total count of commitment leaves</span></span> function</span> getCommitLeafCount</span>(</span>uint256</span> id</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> </span> ///</span> @notice</span> OPTIONAL: Retrieves leaf-level commit data and their hashes</span></span> ///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> ///</span> @param</span> startIndex</span> Index of the first leaf to fetch</span></span> ///</span> @param</span> length</span> Number of leaves to fetch</span></span> ///</span> @return</span> commitHashes</span> Hashes of the leaf data</span></span> ///</span> @return</span> recipients</span> Recipient addresses of each leaf</span></span> ///</span> @return</span> amounts</span> Token amounts of each leaf</span></span> function</span> getCommitLeaves</span>(</span>uint256</span> id</span>,</span> uint256</span> startIndex</span>,</span> uint256</span> length</span>)</span></span> external</span> view</span> returns</span> (</span>bytes32</span>[</span>]</span> memory</span> commitHashes</span>,</span> address</span>[</span>]</span> memory</span> recipients</span>,</span> uint256</span>[</span>]</span> memory</span> amounts</span>)</span>;</span></span> </span> ///</span> @notice</span> Returns the address of the underlying token wrapped by this ZWToken</span></span> ///</span> @return</span> The</span> underlying token contract address, or address(0) if the underlying asset is ETH.</span></span> function</span> getUnderlying</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span></code></pre> getLatestCommitment(uint256 id)</code>: MUST return the most recent top-level commitment associated with the specified token identifier, representing the current state of the ZWToken system.</p> For protocol-level commitments, the block number can be used as the commitment, as it can directly map to the block hash.</li> </ul> </li> hasCommitment(uint256 id, bytes32 commitment)</code>: MUST check whether a specific top-level commitment associated with the specified token identifier exists in the contract.</p> For proving ownership of a provable burn address, it does not require the latest commitment.</li> For protocol-level commitments, the block number can be used as the commitment, as it can directly map to the block hash.</li> </ul> </li> getCommitLeafCount(uint256 id)</code>: OPTIONAL. Returns the total number of leaf-level commitments, which helps getCommitLeaves</code> retrieve the leaves. The returned value also represents the current size of the privacy pool.</p> </li> getCommitLeaves(uint256 id, uint256 startIndex, uint256 length)</code>: OPTIONAL. Retrieves leaf-level commitment data from the commitment tree associated with the specified token identifier.</p> On-chain storage of commit data can be used to improve privacy and decentralization but will incur higher gas costs.</li> Event-based reconstruction can be used as an alternative, though it introduces potential centralization risks.</li> </ul> </li> getUnderlying()</code>: MUST return the address of the underlying token that this ZWToken wraps.</p> If the underlying asset is ETH, MUST return address(0)</code>.</li> </ul> </li> </ul> ERC-165</a> Support</h3> Implementations of this ERC MUST implement ERC-165 interface detection.</li> supportsInterface(bytes4)</code> MUST return true</code> for type(IERC8065).interfaceId</code> (in addition to any other supported interfaces), allowing other contracts to reliably detect whether a token is a ZWToken wrapper.</li> </ul> Events</h3> //</span> Optional: Emitted when a contract-maintained commitment is updated</span></span> ///</span> @notice</span> OPTIONAL event emitted when a commitment is updated in the contract</span></span> ///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> ///</span> @param</span> commitment</span> The new top-level commitment hash</span></span> ///</span> @param</span> to</span> The recipient address associated with the commitment</span></span> ///</span> @param</span> amount</span> The amount related to this commitment update</span></span> event</span> CommitmentUpdated</span>(</span>uint256</span> indexed</span> id</span>, </span>bytes32</span> indexed</span> commitment</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> amount</span>)</span>;</span></span> </span> ///</span> @notice</span> Emitted when underlying tokens are deposited and ZWToken is minted to the recipient</span></span> ///</span> @param</span> from</span> The address sending the underlying tokens</span></span> ///</span> @param</span> to</span> The address receiving the minted ZWToken (after fees)</span></span> ///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> ///</span> @param</span> amount</span> The net amount of ZWToken minted to `to` after deducting applicable fees</span></span> event</span> Deposited</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>)</span>;</span></span> </span> ///</span> @notice</span> Emitted when ZWToken is burned to redeem underlying tokens to the recipient</span></span> ///</span> @param</span> from</span> The address burning the ZWToken</span></span> ///</span> @param</span> to</span> The address receiving the redeemed underlying tokens (after fees)</span></span> ///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> ///</span> @param</span> amount</span> The net amount of underlying tokens received by `to` after deducting applicable fees</span></span> event</span> Withdrawn</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>)</span>;</span></span> </span> ///</span> @notice</span> Emitted upon successful reminting of ZWToken or withdrawal of underlying tokens via a zero-knowledge proof</span></span> ///</span> @param</span> from</span> The address initiating the remint operation</span></span> ///</span> @param</span> to</span> The address receiving the reminted ZWToken or withdrawn underlying tokens (after fees)</span></span> ///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> ///</span> @param</span> amount</span> The net amount of ZWToken or underlying tokens received by `to` after all applicable fees have been deducted</span></span> ///</span> @param</span> redeem</span> If true, withdraws the equivalent underlying tokens instead of reminting ZWToken</span></span> event</span> Reminted</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>, </span>bool</span> redeem</span>)</span>;</span></span></code></pre> CommitmentUpdated(uint256 indexed id, bytes32 indexed commitment, address indexed to, uint256 amount)</code> is OPTIONAL and may be emitted when a contract-maintained commitment is updated, such as when ZWToken is sent to a potential provable burn address. It allows users to reconstruct commitments and generate zero-knowledge proofs, where id</code> is the token identifier, commitment</code> is the new commitment, to</code> is the recipient, and amount</code> is the committed token amount.</p> </li> Deposited(address indexed from, address indexed to, uint256 indexed id, uint256 amount)</code> signals that underlying tokens have been deposited and ZWToken minted to the recipient, where from</code> is the sender, to</code> is the recipient, id</code> is the token identifier and amount</code> is the net amount of ZWToken minted to to</code> after deducting applicable fees.</p> </li> Withdrawn(address indexed from, address indexed to, uint256 indexed id, uint256 amount)</code> signals that ZWToken has been burned to redeem underlying tokens to the recipient, where from</code> is the burner, to</code> is the receiver, id</code> is the token identifier and amount</code> is the net amount of underlying tokens received by to</code> after deducting applicable fees.</p> </li> Reminted(address indexed from, address indexed to, uint256 indexed id, uint256 amount, bool redeem)</code> MUST be emitted upon successful reminting of ZWToken or withdrawal of underlying tokens via a zero-knowledge proof, where from</code> is the reminter, to</code> is the recipient, id</code> is the token identifier and amount</code> is the net amount of ZWToken or underlying tokens received by to</code> after all applicable fees have been deducted.</p> </li> </ul> Rationale</h2> Permissionless Wrapping: Launching a new zk-native token is unlikely to achieve sufficient liquidity or adoption, and major token issuers are unlikely to deploy zk variants due to regulatory and operational constraints. A permissionless wrapper makes privacy a native feature for existing tokens. ZWToken does not require issuer consent—any existing token can be wrapped, ensuring openness and equal accessibility regardless of issuer policies.</p> </li> Composable Privacy: Wrapped tokens remain fully compatible with their underlying token standards, preserving interoperability across the Ethereum ecosystem. Users and dApps can treat ZWToken as the underlying token when privacy is not required, making privacy an optional and composable extension rather than a separate system.</p> </li> Awareness of ZWToken: This ERC supports both ZWToken-aware and ZWToken-unaware workflows, each with distinct advantages. In the ZWToken-aware workflow, ZWToken inherits all functional properties of the underlying token and can interact seamlessly with existing DeFi protocols. In the ZWToken-unaware workflow, ZWToken operates transparently beneath the user interface, reducing the number of required contract interactions and improving user experience for those who prefer not to hold ZWToken directly.</p> </li> Multiple Token Standard Support: This ERC only depends on the transferability of the underlying token, enabling broad compatibility with token standards such as ERC-20, ERC-721, ERC-1155, and ERC-6909. Non-transferable tokens (e.g., Soulbound Tokens, SBTs) are out of scope. Implementations may require extra care for:</p> Fee-on-transfer tokens.</li> Rebasing tokens (consider wrapping an existing non-rebasing wrapper to avoid rebase-handling complexity).</li> </ul> </li> Fee Mechanisms: Fee structures are implementation-specific and not defined by this ERC. Implementations MAY apply fees during deposit, remint, or withdraw phases, and MAY support various fee models (e.g., fixed fees, percentage-based fees, or no fees).</p> </li> Relayer-Enabled Remint: This ERC supports relayer functionality, allowing third parties to submit remint transactions on behalf of users while receiving a fee. This design mitigates privacy leakage caused by revealing the original sender's address when paying gas fees.</p> </li> Data Extensibility:</p> The meaning and encoding of proverData</code> and relayerData</code> are implementation-specific.</li> Implementations MAY encode prover-specific metadata in data.proverData</code> (e.g., a circuit identifier/version, a proving key identifier, or packed auxiliary public inputs).</li> Implementations MAY encode relayer-specific metadata in data.relayerData</code> (e.g., fee information, a fee token, or other fee model parameters).</li> A single universal encoding is impractical because proving schemes and relayer compensation models can vary significantly.</li> If cross-implementation interoperability is desired, a separate ERC (or profile) SHOULD standardize encoding(s) for proverData</code> and/or relayerData</code>.</li> </ul> </li> Commitment Generalization: The ERC adopts a generic commitment abstraction, supporting various schemes such as Merkle trees or other verifiable cryptographic accumulators. This flexibility enables developers to adapt the standard to different privacy or scalability trade-offs.</p> </li> Proof System Generalization: Proofs are passed as bytes calldata, allowing the use of SNARKs, STARKs, or any other zero-knowledge proof system, ensuring future-proof interoperability across cryptographic frameworks.</p> </li> Provable Burn Address Generalization: This ERC does not prescribe a specific method for generating Provable Burn Addresses, as long as the following conditions are met. One example is adopting zk-friendly hash functions such as Poseidon to replace keccak256 in the address generation algorithm.</p> Such addresses MUST NOT be operable by any user and MUST be provably non-correspondent to any externally owned account (EOA) or smart contract.</li> Only the entity that generates the burn address MAY derive it, for example through a signature-derived or deterministic generation scheme.</li> </ul> </li> Dual Commitment Options: The ERC supports both contract-maintained commitments and protocol-level commitments (using blockhash as the commitment).</p> Contract-maintained commitments reduce proof complexity, allowing smaller ZK circuits and enabling proof generation directly in browsers or mobile devices, at the cost of higher gas consumption during transfers.</li> Using blockhash as the commitment eliminates on-chain maintenance overhead but increases the complexity of off-chain proof generation.</li> </ul> </li> Preview Functions: Following the design pattern established by ERC-4626</a>, this ERC includes optional preview functions (previewDeposit</code>, previewWithdraw</code>, previewRemint</code>) that simulate the exact outcomes of their corresponding mutable operations.</p> Since the actual token amounts received may differ from the input amounts due to implementation-specific factors (e.g., fees), users and integrators need a standardized way to determine the exact amounts.</li> These functions provide a standardized interface for querying the net token amounts, enabling accurate UX displays and informed decision-making before executing transactions.</li> Each preview function mirrors the parameters of its corresponding mutable operation to ensure accurate calculations that may depend on any of these parameters.</li> </ul> </li> </ul> Backwards Compatibility</h2> This ERC introduces no breaking changes. It extends the functionality of the underlying token without modifying or overriding its base interfaces.</p> Reference Implementation</h2> //</span> SPDX-License-Identifier: MIT</span></span> pragma</span> solidity</span> ^0.8.20</span>;</span></span> </span> import</span> {</span>ERC20</span>}</span> from</span> "@openzeppelin/contracts/token/ERC20/ERC20.sol"</span>;</span></span> import</span> {</span>IERC20</span>}</span> from</span> "@openzeppelin/contracts/token/ERC20/IERC20.sol"</span>;</span></span> import</span> {</span>SafeERC20</span>}</span> from</span> "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol"</span>;</span></span> import</span> {</span>ERC165</span>}</span> from</span> "@openzeppelin/contracts/utils/introspection/ERC165.sol"</span>;</span></span> import</span> {</span>IERC165</span>}</span> from</span> "@openzeppelin/contracts/utils/introspection/IERC165.sol"</span>;</span></span> </span> interface</span> IVerifier</span> {</span></span> function</span> verifyProof</span>(</span></span> bytes</span> calldata</span> proof</span>,</span></span> uint256</span>[</span>]</span> calldata</span> input</span></span> )</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> }</span></span> </span> contract</span> ZWToken</span> is</span> IERC8065</span>, </span>ERC20</span>, </span>ERC165</span> {</span></span> using</span> SafeERC20</span> for</span> IERC20</span>;</span></span> </span> IERC20 </span>public</span> immutable</span> underlying</span>;</span></span> IVerifier </span>public</span> immutable</span> verifier</span>;</span></span> </span> mapping</span>(</span>bytes32</span> =></span> bool</span>)</span> public</span> usedNullifier</span>;</span></span> </span> event</span> Deposited</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>)</span>;</span></span> event</span> Withdrawn</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>)</span>;</span></span> event</span> Reminted</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>, </span>bool</span> redeem</span>)</span>;</span></span> </span> constructor</span>(</span></span> string</span> memory</span> name_</span>,</span></span> string</span> memory</span> symbol_</span>,</span></span> address</span> underlying_</span>,</span></span> address</span> verifier_</span></span> )</span> ERC20</span>(</span>name_, symbol_) </span>{</span></span> require</span>(</span>underlying_ </span>!=</span> address</span>(</span>0</span>)</span>,</span> "Invalid underlying"</span>)</span>;</span></span> require</span>(</span>verifier_ </span>!=</span> address</span>(</span>0</span>)</span>,</span> "Invalid verifier"</span>)</span>;</span></span> underlying </span>=</span> IERC20</span>(</span>underlying_</span>)</span>;</span></span> verifier </span>=</span> IVerifier</span>(</span>verifier_</span>)</span>;</span></span> }</span></span> </span> function</span> deposit</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> /</span>data</span>/</span>)</span> external</span> payable</span> override</span> {</span></span> require</span>(</span>amount </span>></span> 0</span>,</span> "amount must > 0"</span>)</span>;</span></span> require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span> underlying</span>.</span>safeTransferFrom</span>(</span>msg.sender</span>,</span> address</span>(</span>this</span>)</span>,</span> amount</span>)</span>;</span></span> _mint</span>(</span>to</span>,</span> amount</span>)</span>;</span></span> emit</span> Deposited</span>(</span>msg.sender</span>,</span> to</span>,</span> id</span>,</span> amount</span>)</span>;</span></span> }</span></span> </span> function</span> withdraw</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> /</span>data</span>/</span>)</span> external</span> override</span> {</span></span> require</span>(</span>amount </span>></span> 0</span>,</span> "amount must > 0"</span>)</span>;</span></span> require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span> _burn</span>(</span>msg.sender</span>,</span> amount</span>)</span>;</span></span> underlying</span>.</span>safeTransfer</span>(</span>to</span>,</span> amount</span>)</span>;</span></span> emit</span> Withdrawn</span>(</span>msg.sender</span>,</span> to</span>,</span> id</span>,</span> amount</span>)</span>;</span></span> }</span></span> </span> function</span> remint</span>(</span></span> address</span> to</span>,</span></span> uint256</span> id</span>,</span></span> uint256</span> amount</span>,</span></span> IERC8065</span>.</span>RemintData</span> calldata</span> data</span></span> )</span> external</span> override</span> {</span></span> require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span> //</span> NOTE</span>: This reference implementation uses a verifier circuit that consumes a single nullifier as a public input.</span></span> //</span> The ERC-8065 specification allows `data.nullifiers` to contain multiple nullifiers so implementations can</span></span> //</span> support batch reminting (consuming multiple nullifiers atomically within one proof).</span></span> require</span>(</span>data</span>.</span>nullifiers</span>.</span>length </span>==</span> 1</span>,</span> "Only single nullifier supported"</span>)</span>;</span></span> bytes32</span> nullifier </span>=</span> data</span>.</span>nullifiers</span>[</span>0</span>]</span>;</span></span> require</span>(</span>!</span>usedNullifier</span>[</span>nullifier</span>]</span>,</span> "nullifier used"</span>)</span>;</span></span> </span> bytes32</span> headerHash </span>=</span> blockhash</span>(</span>uint256</span>(</span>data</span>.</span>commitment</span>)</span>)</span>;</span></span> require</span>(</span>headerHash </span>!=</span> bytes32</span>(</span>0</span>)</span>,</span> "commitment not found"</span>)</span>;</span></span> </span> //</span> Example encoding (implementation-specific):</span></span> //</span> if relayerData.length >= 32, first 32 bytes are interpreted as relayerFee (uint256)</span></span> uint256</span> relayerFee </span>=</span> 0</span>;</span></span> if</span> (</span>data</span>.</span>relayerData</span>.</span>length </span>></span>=</span> 32</span>)</span> {</span></span> assembly</span> {</span></span> relayerFee </span>:=</span> calldataload</span>(</span>data</span>.</span>relayerData</span>.</span>offset</span>)</span></span> }</span></span> }</span></span> </span> //</span> Replay protection by chain id and contract address is handled externally––</span></span> //</span> they MUST be included as parameters when generating the provable burn address and proof.</span></span> //</span> (For example, the Poseidon hash that defines the burn address should incorporate these values.)</span></span> //</span> No contract-side enforcement is implemented here.</span></span> uint256</span>[</span>]</span> memory</span> input </span>=</span> new</span> uint256</span>[](</span>7</span>)</span>;</span></span> input</span>[</span>0</span>]</span> =</span> uint256</span>(</span>headerHash</span>)</span>;</span></span> input</span>[</span>1</span>]</span> =</span> uint256</span>(</span>nullifier</span>)</span>;</span></span> input</span>[</span>2</span>]</span> =</span> uint256</span>(</span>uint160</span>(</span>to</span>)</span>)</span>;</span></span> input</span>[</span>3</span>]</span> =</span> uint256</span>(</span>id</span>)</span>;</span></span> input</span>[</span>4</span>]</span> =</span> uint256</span>(</span>amount</span>)</span>;</span></span> input</span>[</span>5</span>]</span> =</span> uint256</span>(</span>data</span>.</span>redeem </span>?</span> 1</span> :</span> 0</span>)</span>;</span></span> input</span>[</span>6</span>]</span> =</span> uint256</span>(</span>relayerFee</span>)</span>;</span></span> </span> require</span>(</span>verifier</span>.</span>verifyProof</span>(</span>data</span>.</span>proof</span>,</span> input</span>)</span>,</span> "bad proof"</span>)</span>;</span></span> </span> usedNullifier</span>[</span>nullifier</span>]</span> =</span> true</span>;</span></span> </span> //</span> Fee handling is implementation-specific</span></span> //</span> This example implementation applies only relayer fees (parsed from relayerData above)</span></span> //</span> In this example, relayerFee is interpreted as a percentage with denominator 10000</span></span> uint256</span> remain </span>=</span> amount</span>;</span></span> if</span> (</span>relayerFee </span>></span> 0</span>)</span> {</span></span> uint256</span> feeDenominator </span>=</span> 10000</span>;</span></span> require</span>(</span>relayerFee </span><</span> feeDenominator</span>,</span> "invalid relayer fee"</span>)</span>;</span></span> remain </span>=</span> amount </span>-</span> amount </span></span> relayerFee </span>/</span> feeDenominator</span>;</span></span> require</span>(</span>remain </span>></span> 0</span>,</span> "invalid remain"</span>)</span>;</span></span> }</span></span> </span> if</span> (</span>data</span>.</span>redeem</span>)</span> {</span></span> underlying</span>.</span>safeTransfer</span>(</span>to</span>,</span> remain</span>)</span>;</span></span> if</span> (</span>relayerFee </span>></span> 0</span>)</span> {</span></span> underlying</span>.</span>safeTransfer</span>(</span>msg.sender</span>,</span> amount </span>-</span> remain</span>)</span>;</span></span> }</span></span> }</span> else</span> {</span></span> _mint</span>(</span>to</span>,</span> remain</span>)</span>;</span></span> if</span> (</span>relayerFee </span>></span> 0</span>)</span> {</span></span> _mint</span>(</span>msg.sender</span>,</span> amount </span>-</span> remain</span>)</span>;</span></span> }</span></span> }</span></span> emit</span> Reminted</span>(</span>msg.sender</span>,</span> to</span>,</span> id</span>,</span> remain</span>,</span> data</span>.</span>redeem</span>)</span>;</span></span> }</span></span> </span> function</span> getLatestCommitment</span>(</span>uint256</span> id</span>)</span> external</span> view</span> override</span> returns</span> (</span>bytes32</span>)</span> {</span></span> require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span> return</span> bytes32</span>(</span>block</span>.</span>number</span>)</span>;</span></span> }</span></span> </span> function</span> hasCommitment</span>(</span>uint256</span> id</span>,</span> bytes32</span> commitment</span>)</span> external</span> view</span> override</span> returns</span> (</span>bool</span>)</span> {</span></span> require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span> bytes32</span> headerHash </span>=</span> blockhash</span>(</span>uint256</span>(</span>commitment</span>)</span>)</span>;</span></span> return</span> headerHash </span>!=</span> bytes32</span>(</span>0</span>)</span>;</span></span> }</span></span> </span> function</span> getUnderlying</span>(</span>)</span> external</span> view</span> override</span> returns</span> (</span>address</span>)</span> {</span></span> return</span> address</span>(</span>underlying</span>)</span>;</span></span> }</span></span> </span> //</span> Optional preview functions</span></span> function</span> previewDeposit</span>(</span>address</span> /</span>to</span>/</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> /</span>data</span>/</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span> {</span></span> require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span> //</span> This example implementation has no deposit fees, so the output equals the input.</span></span> //</span> Implementations with fees SHOULD deduct them here.</span></span> return</span> amount</span>;</span></span> }</span></span> </span> function</span> previewWithdraw</span>(</span>address</span> /</span>to</span>/</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> /</span>data</span>/</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span> {</span></span> require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span> //</span> This example implementation has no withdrawal fees, so the output equals the input.</span></span> //</span> Implementations with fees SHOULD deduct them here.</span></span> return</span> amount</span>;</span></span> }</span></span> </span> function</span> previewRemint</span>(</span>address</span> /</span>to</span>/</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> IERC8065</span>.</span>RemintData</span> calldata</span> data</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span> {</span></span> require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span> //</span> Example encoding (implementation-specific):</span></span> //</span> Parse relayerFee from relayerData (if provided)</span></span> uint256</span> relayerFee </span>=</span> 0</span>;</span></span> if</span> (</span>data</span>.</span>relayerData</span>.</span>length </span>></span>=</span> 32</span>)</span> {</span></span> relayerFee </span>=</span> abi</span>.</span>decode</span>(</span>data</span>.</span>relayerData</span>[</span>:</span>32</span>]</span>,</span> (</span>uint256</span>)</span>)</span>;</span></span> }</span></span> //</span> Apply relayer fee (percentage with denominator 10000)</span></span> uint256</span> remain </span>=</span> amount</span>;</span></span> if</span> (</span>relayerFee </span>></span> 0</span>)</span> {</span></span> uint256</span> feeDenominator </span>=</span> 10000</span>;</span></span> require</span>(</span>relayerFee </span><</span> feeDenominator</span>,</span> "invalid relayer fee"</span>)</span>;</span></span> remain </span>=</span> amount </span>-</span> amount </span></span> relayerFee </span>/</span> feeDenominator</span>;</span></span> }</span></span> return</span> remain</span>;</span></span> }</span></span> </span> function</span> supportsInterface</span>(</span>bytes4</span> interfaceId</span>)</span></span> public</span></span> view</span></span> virtual</span></span> override</span>(</span>ERC165</span>,</span> IERC165</span>)</span></span> returns</span> (</span>bool</span>)</span></span> {</span></span> return</span> interfaceId </span>==</span> type</span>(</span>IERC8065</span>)</span>.</span>interfaceId </span>\|\|</span> super</span>.</span>supportsInterface</span>(</span>interfaceId</span>)</span>;</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> Double-Remint Prevention: Each remint operation MUST include one or more unique nullifiers (data.nullifiers</code>) to prevent double-remint attacks.</p> Reusing any nullifier MUST revert.</li> On success, all provided nullifiers MUST be marked as spent.</li> </ul> </li> Over-Minting Protection: The total supply of ZWToken MAY temporarily exceed the supply of the underlying token. However, the surplus represents provably burnt tokens, which are permanently removed from circulation and cannot be redeemed.</p> </li> Local Proof Generation: Circuits SHOULD remain as small and efficient as possible to enable users to generate zero-knowledge proofs locally (e.g., within browsers or mobile devices). This minimizes reliance on third-party provers that may introduce privacy leakage risks.</p> </li> Provable Burn Address Security: Provable burn addresses MAY follow different generation schemes (e.g., as proposed in EIP-7503). The essential properties are:</p> These addresses MUST be non-operable and provably non-correspondent to any externally owned account (EOA) or smart contract.</li> Only the generator of the burn address MAY deterministically derive it, for instance, through a signature-derived scheme.</li> Implementations SHOULD prefer zk-friendly hash functions (e.g., Poseidon) in place of keccak256 to improve proof efficiency and reduce circuit size.</li> </ul> </li> Burn and Remint Process Privacy:</p> Burn amounts SHOULD appear indistinguishable from ordinary transfers to prevent correlation with remint amounts.</li> Burn and remint events SHOULD be separated in time to reduce linkability.</li> Each burn operation MUST use a unique Provable Burn Address that can be used only once.</li> </ul> </li> Fully On-Chain Operation: The protocol operates entirely on-chain and requires no trusted backend. It can be directly integrated into wallets or dApps without introducing custodial or centralized dependencies.</p> </li> Commit Data Privacy: When generating proofs, users SHOULD retrieve as much commitment data as possible to maximize anonymity. Relying on selective or limited data sources may allow inference of the specific commit path being proven, weakening privacy guarantees.</p> </li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Diamond Storage 2025-10-11T00:00:00+00:00 Abstract</h2> This standard formalizes the diamond storage pattern originally introduced by ERC-2535 Diamonds</a> and widely adopted across smart contracts.</p> Though originally created for proxy contracts, diamond storage can be used to organize storage and data access within any</em> smart contract.</p> Diamond storage defines the location of structs in contract storage using the keccak256</code> hash of human-readable identifiers.</p> ERC-8042</a> standardizes this simple and production-proven approach, offering a lightweight alternative to ERC-7201</a> for new and existing projects.</p> Motivation</h2> On March 10, 2020, a change to the Solidity compiler introduced the ability to assign structs to any storage location. This enabled a new pattern for using separate areas of storage. The pattern became known as diamond storage, as it was first popularized by ERC-2535 Diamonds and has since been widely used.</p> Later, on June 20, 2023, ERC-7201 was introduced to standardize this general storage pattern. However, the formula that ERC-7201 proposed for generating storage locations differed from the one already established and in active use by diamond storage.</p> ERC-8042 standardizes diamond storage for new projects and validates past diamond storage implementations.</p> While ERC-7201 defines a generalized mechanism for storage namespaces, ERC-8042 preserves the simplicity and backward compatibility of the diamond storage convention already deployed in production across many projects.</p> Developers may prefer diamond storage for its simplicity, restricted ASCII identifiers, and direct hash-based computation of storage locations.</p> This standard can be used by tools to find and access data within smart contract storage.</p> Specification</h2> Diamond storage defines where structs are located in contract storage.</p> A diamond storage identifier is defined as a string containing only printable ASCII characters. That is characters 0x20</code> through 0x7E</code> inclusive.</p> The location of a diamond storage struct is determined by the keccak256</code> hash of a diamond storage identifier.</p> Recommendations</h3> Use Solidity's string literals</h4> A string literal is an ASCII string type that is literally written between quotes, for example: "this is a string literal"</code>.</p> It is recommended to use Solidity's string literals to create diamond storage identifiers because the Solidity compiler enforces that they only contain printable ASCII characters, characters 0x20</code> through 0x7E</code> inclusive. Hex (\xNN</code>) and Unicode (\uNNNN</code>) escape sequences should NOT</strong> be used in diamond storage identifiers.</p> It is recommended to use compile-time constant string literals. Here is an example:</p> bytes32 constant STORAGE_POSITION = keccak256("myproject.erc721.registry");</code></p> </li> Use unique, human-readable, meaningful strings</h4> A human-readable string is a string that humans can normally read and understand, like "Transaction successful".</p> A meaningful string in this context is a string that appropriately names or describes a storage space, or uses a pattern to do so. For example, "myproject.erc721.registry"</code> is a hierarchical pattern that specifies ERC-721</a> related storage for a registry. The string "car.fish.piano.run"</code> is not a meaningful string because it is random and does not appropriately name or describe something.</p> Diamond storage identifiers should be unique, human-readable, meaningful strings.</p> </li> Do NOT use Unicode literals</h4> Unicode literals can contain invisible characters and other non-ASCII characters which violates the specification of this standard.</p> Here is an example of a Unicode literal in Solidity: string memory a = unicode"Hello 😃";</code>.</p> Unicode literals should NOT</strong> be used to create diamond storage identifiers.</p> </li> Do not use the space 0x20</code> character</h4> Including the space (0x20</code>) character in diamond storage identifiers is not recommended, as it may interfere with tooling such as the NatSpec tag described next.</p> </li> </ol> ERC-8042 NatSpec tag</h3> ERC-7201 defines the NatSpec tag @custom:storage-location <FORMULA_ID>:<NAMESPACE_ID></code>, where <FORMULA_ID></code> identifies a formula used to compute the storage location of a struct based on the namespace id.</p> The formula identified by erc8042</code> is defined as erc8042(id: string literal) = keccak256(id)</code>. In Solidity, this corresponds to the expression keccak256(id)</code>. When using this formula the annotation becomes @custom:storage-location erc8042:<NAMESPACE_ID></code>. For example, @custom:storage-location erc8042:myproject.erc721.registry</code> annotates diamond storage with id "myproject.erc721.registry"</code> rooted at erc8042("myproject.erc721.registry")</code>.</p> Rationale</h2> Proxy contracts and contracts that use DELEGATECALL</code> need a reliable and secure way to define, document, and manage separate areas of smart contract storage.</p> In March 2020, diamond storage established a way to do this and has been in use since then. However, diamond storage wasn't formalized as a standard, which is important to clarify its mechanics, usage and precise specification.</p> In June 2023, ERC-7201 Namespaced Storage Layout standardized the general pattern but has looser restrictions on namespace ids and a more complicated formula for calculating storage locations. Some people may prefer using ERC-7201, especially if they may auto-generate machine-readable or random strings for their namespace ids.</p> Some people may prefer ERC-8042 Diamond Storage for its ASCII-enforced, human-readable, meaningful strings and simple calculation of storage locations.</p> ERC-2535 Diamonds first introduced the pattern of distinct storage areas for smart contracts. ERC-7201 later standardized the idea. ERC-8042 standardizes the original, simpler diamond storage variant for new projects and legacy compatibility.</p> Though originally created for proxy contracts, diamond storage can be used to organize storage and data access within any</em> smart contract.</p> Comparing ERC-8042 and ERC-7201</h3> ERC-7201</h4> ERC-7201 applies a formula to a namespace id to generate a storage location. Per the ERC-7201 specification a namespace id is a string that should not contain any whitespace characters. A namespace id has no other restrictions. So a namespace id could be something meaningful like mycompany.projectA.erc721</code> or it could be a series of random bytes, characters or words, etc.</p> ERC-7201 uses the following formula, given in Solidity, to generate a storage location: keccak256(abi.encode(uint256(keccak256(bytes(namespace id))) - 1)) & ~bytes32(uint256(0xff))</code>.</p> The first part of the ERC-7201 formula keccak256(abi.encode(uint256(keccak256(bytes(namespace id))) - 1))</code> ensures that the input bytes to the second call to keccak256</code> will not match any input bytes used by Solidity's types that also use keccak256</code> to determine storage locations. This makes it possible to use any sequence of bytes for the namespace id.</p> </li> The last part of ERC-7201, & ~bytes32(uint256(0xff))</code> ensures that the final storage location is a multiple of 256 which may provide a gas optimization in the future.</p> </li> </ol> ERC-8042</h4> ERC-8042 identifiers can only contain printable ASCII characters and recommends using Solidity's string literals which enforces this constraint.</p> ERC-8042 recommends human-readable, meaningful strings for diamond storage identifiers.</p> ERC-8042 uses the following formula, given in Solidity, to generate a storage location: keccak256(string literal)</code>.</p> Backwards Compatibility</h2> Diamond storage as described by this standard has been in use for 5 years. This standard recognizes and standardizes all previous uses of diamond storage that conform to the specification.</p> Reference Implementation</h2> This is a simple example of a contract that uses diamond storage:</p> /*</span></span> </span>@title</span> ERC721Registry</span></span> * </span>@notice</span> A registry contract for tracking ERC721 contracts.</span></span> * Allows adding ERC721 contract addresses up to a configurable limit.</span></span> * </span>@dev</span> EIP-8042 Diamond Storage is used to organize and manage access to storage.</span></span> /</span></span> contract</span> ERC721Registry</span> {</span></span> </span> ///</span> @notice</span> Reverts when the registry reaches its configured capacity.</span></span> error</span> ERC721RegistryFull</span>(</span>)</span>;</span></span> </span></span> ///</span> @notice</span> Struct storage position defined by keccak256 hash </span></span> ///</span> of diamond storage identifier.</span></span> bytes32</span> constant</span> STORAGE_POSITION </span>=</span> keccak256</span>(</span>"myproject.erc721.registry"</span>)</span>;</span></span> </span></span> ///</span> @notice</span> @notice</span> Storage layout for the ERC721 registry, following EIP-8042. </span></span> ///</span> @dev</span> - `erc721Contracts`: Dynamic array of registered ERC721 contract addresses.</span></span> ///</span> - `registryLimit`: Maximum allowed entries.</span></span> ///</span> @custom:storage</span>-location erc8042:myproject.erc721.registry</span></span> struct</span> ERC721RegistryStorage</span> {</span></span> address</span>[</span>]</span> erc721Contracts</span>;</span></span> uint256</span> registryLimit</span>;</span> </span></span> }</span></span> </span> ///</span> @notice</span> Returns a pointer to the ERC721RegistryStorage struct in storage.</span></span> ///</span> @dev</span> Uses inline assembly to access the storage slot defined by STORAGE_POSITION.</span></span> ///</span> @return</span> s</span> The ERC173Storage struct in storage.</span></span> function</span> getStorage</span>(</span>)</span> internal</span> pure</span> returns</span> (</span>ERC721RegistryStorage</span> storage</span> s</span>)</span> {</span></span> bytes32</span> position </span>=</span> STORAGE_POSITION</span>;</span></span> assembly</span> {</span></span> s</span>.</span>slot </span>:=</span> position</span></span> }</span></span> }</span></span> </span> ///</span> @notice</span> Sets the maximum number of ERC721 contracts the registry can hold. </span></span> ///</span> @param</span> _newLimit</span> New registry capacity limit.</span></span> function</span> setRegistryLimit</span>(</span>uint256</span> _newLimit</span>)</span> internal</span> {</span></span> getStorage</span>(</span>)</span>.</span>registryLimit </span>=</span> _newLimit</span>;</span></span> }</span></span> </span> ///</span> @notice</span> Adds an ERC721 contract address to the registry.</span></span> ///</span> @dev</span> Reverts with `ERC721RegistryFull` if the registry is full.</span></span> ///</span> @param</span> _erc721Contract</span> Address of the ERC721 contract to register.</span></span> function</span> addERC721Contract</span>(</span>address</span> _erc721Contract</span>)</span> internal</span> {</span> </span></span> ERC721RegistryStorage </span>storage</span> s </span>=</span> getStorage</span>(</span>)</span>;</span></span> </span> if</span>(</span>s</span>.</span>erc721Contracts</span>.</span>length </span>==</span> s</span>.</span>registryLimit</span>)</span> {</span></span> revert</span> ERC721RegistryFull</span>(</span>)</span>;</span></span> }</span></span> </span></span> s</span>.</span>erc721Contracts</span>.</span>push</span>(</span>_erc721Contract</span>)</span>;</span> </span></span> }</span></span> </span> ///</span> @notice</span> Returns a list of all registered ERC721 contract addresses.</span></span> ///</span> @return</span> Array</span> of registered ERC721 contract addresses.</span></span> function</span> getERC721Registry</span>(</span>)</span> internal</span> view</span> returns</span> (</span>address</span>[</span>]</span> memory</span>)</span> {</span></span> return</span> getStorage</span>(</span>)</span>.</span>erc721Contracts</span>;</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> Uniqueness of identifiers</h3> Two independent contracts or libraries using the same human-readable string will map to the same storage slot. Developers must ensure that diamond storage identifiers are unique within a contract system to prevent unintentional data overlap or corruption. A common practice is to prefix identifiers with a project, organization, or standard name (for example, "myproject.erc721.registry"</code>).</p> ASCII Input Restriction to Prevent Storage Collisions</h3> To prevent storage collisions, diamond storage identifiers must consist only of printable ASCII characters, specifically the range 0x20</code> to 0x7E</code> inclusive. Identifiers must not include Unicode escape sequences (\uNNNN</code>) or hexadecimal escape sequences (\xNN</code>).</p> Solidity’s storage slot encoding, as produced by abi.encode(p)</code>, contains non-printable bytes, particularly null bytes (0x00</code>), due to Solidity’s default storage layout and padding rules.</p> Allowing identifiers to include such bytes could enable a malicious developer to craft an identifier like "config\x00\x00..."</code>. The bytes of such an identifier could collide with the storage encoded input of mappings, dynamic arrays, strings and bytes which use keccak256</code> to compute storage locations. Such collisions could result in overwrites, corruption of contract state, or security vulnerabilities.</p> Restricting identifiers to printable ASCII removes this exploitable source of collision. While this restriction does not provide a mathematical guarantee that collisions are impossible — because, in theory, a sufficiently large storage layout position (p</code>) could accidentally contain all printable ASCII bytes — the probability of this occurring is extremely small, and impractical.</p> By using human-readable, meaningful strings for identifiers, the practical likelihood of any collision is virtually zero, providing strong protection for the integrity and safety of contract storage.</p> String Literals</h3> The specification recommends using string literals to create diamond storage identifiers because the Solidity compiler enforces that only printable ASCII characters are used. However, string literals should not use Unicode escape sequences (\uNNNN</code> ) or hexadecimal escape sequences (\xNN</code> ).</p> Unicode Literals</h3> Unicode literals (e.g. unicode"Hello 😃"</code>) should not be used to create diamond storage identifiers because they can contain non-printable bytes and characters, and they can be used to obfuscate identifiers by using characters that look like other characters. For example, the Cyrillic character а</code> (\u0430</code>) looks identical to the ASCII character a</code> (\u0061</code>).” In addition Unicode has control characters that change the direction text is displayed.</p> keccak256</code> Hash Collision Resistance</h3> The location of a diamond storage struct is determined by the output of the keccak256</code> hash function. Some developers may wonder about the likelihood that a diamond storage struct lands at an address where it will accidentally overwrite existing storage data. The 256-bit address space of contract storage is so vast that the likelihood of data overlap is statistically improbable.</p> Solidity mappings, dynamic arrays, strings and bytes also use keccak256</code> to determine their location in contract storage.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Contract-Level Onchain Metadata 2025-10-10T00:00:00+00:00 Abstract</h2> This ERC defines a standard for storing contract-level metadata onchain. It extends ERC-7572</a>'s contract-level metadata concept by providing onchain storage. Contracts MAY optionally use ERC-8042</a>'s Diamond Storage pattern for predictable storage locations, enabling cross-chain compatibility and supporting upgradable contracts.</p> Motivation</h2> Contract metadata today typically relies on offchain storage such as URLs or IPFS, creating trust and availability risks—servers go down, domains expire, and malicious actors can modify data without onchain record. Storing metadata onchain makes contract identity censorship-resistant and enables wallets and block explorers to display verifiable information without trusting external services.</p> Specification</h2> 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.</p> Required Metadata Function and Event</h3> Contracts implementing this ERC MUST implement the following interface:</p> interface</span> IERC8049</span> {</span></span> ///</span> @notice</span> Get contract metadata value for a key.</span></span> function</span> getContractMetadata</span>(</span>string</span> calldata</span> key</span>)</span> external</span> view</span> returns</span> (</span>bytes</span> memory</span>)</span>;</span></span> </span></span> ///</span> @notice</span> Emitted when contract metadata is updated.</span></span> event</span> ContractMetadataUpdated</span>(</span>string</span> indexed</span> indexedKey</span>, </span>string</span> key</span>, </span>bytes</span> value</span>)</span>;</span></span> }</span></span></code></pre> Contracts implementing this ERC MAY also expose a setContractMetadata(string calldata key, bytes calldata value)</code> function to allow metadata updates, with write policy determined by the contract.</p> Contracts implementing this ERC MUST emit the following event when metadata is set:</p> event</span> ContractMetadataUpdated</span>(</span>string</span> indexed</span> indexedKey</span>, </span>string</span> key</span>, </span>bytes</span> value</span>)</span>;</span></span></code></pre>Key/Value Pairs</h3> This ERC specifies that the key is a string type and the value is bytes type. This provides flexibility for storing any type of data while maintaining an intuitive string-based key interface.</p> Optional Key Parameters</h3> Keys MAY include parameters to represent variations or instances of a metadata type, such as "registration: 1"</code> or "name: Maria"</code>; see ERC-8119</a>: Key Parameters.</p> Optional Diamond Storage</h3> Contracts implementing this ERC MAY use Diamond Storage pattern for predictable storage locations. If implemented, contracts MUST use the namespace ID "erc8049.contract.metadata.storage"</code>.</p> The Diamond Storage pattern provides predictable storage locations for data, which is useful for cross-chain applications using inclusion proofs and for upgradable contracts. For more details on Diamond Storage, see ERC-8042</a>.</p> Value Interpretation</h3> If no standard is specified for a metadata value, clients MAY assume the value is a UTF-8 encoded string (bytes(string)) unless otherwise specified by the implementing contract or protocol.</p> Examples</h3> Example: Basic Contract Information</h4> A contract can store basic information about itself:</p> Key: "name"</code> → Value: bytes("MyToken")</code></li> Key: "description"</code> → Value: bytes("A decentralized exchange")</code></li> Key: "collaborators"</code> → Value: bytes(abi.encodePacked(address1, address2, address3))</code></li> </ul> Example: ENS Name for Contract</h4> A contract can specify its ENS name using this standard:</p> Key: "ens_name"</code> → Value: bytes("mycontract.eth")</code></li> </ul> This allows clients to discover the contract's ENS name and resolve it to get additional information about the contract.</p> Optional Metadata Hooks</h3> Contracts implementing this ERC MAY use hooks to redirect metadata resolution to a different contract. For the full specification, see ERC-8121</a>. When using hooks with contract metadata, the target function MUST be getContractMetadata(string)</code> returning bytes</code>. The hook selector is 0x9e574b14</code>.</p> Rationale</h2> This design prioritizes simplicity and flexibility by using a string-key, bytes-value store that provides an intuitive interface for any type of contract metadata. The minimal interface with a single getContractMetadata</code> function provides all necessary functionality. The optional setContractMetadata</code> function enables flexible access control for metadata updates. The required ContractMetadataUpdated</code> event provides transparent audit trails with indexed key for efficient filtering. Contracts that need predictable storage locations can optionally use Diamond Storage pattern. This makes the standard suitable for diverse use cases including contract identification, collaboration tracking, and custom metadata storage.</p> Backwards Compatibility</h2> Fully compatible with existing smart contracts.</li> Non-supporting clients can ignore the scheme.</li> </ul> Reference Implementation</h2> The interface is defined in the Required Metadata Function and Event section above. Here are reference implementations:</p> Basic Implementation</h3> pragma</span> solidity</span> ^0.8.25</span>;</span></span> </span> import</span> "./IERC8049.sol"</span>;</span></span> </span> contract</span> BasicContractMetadata</span> is</span> IERC8049</span> {</span></span> //</span> Simple mapping for contract-level metadata</span></span> mapping</span>(</span>string</span> key </span>=></span> bytes</span> value</span>)</span> private</span> _metadata</span>;</span></span> </span> function</span> getContractMetadata</span>(</span>string</span> calldata</span> key</span>)</span> external</span> view</span> override</span> returns</span> (</span>bytes</span> memory</span>)</span> {</span></span> return</span> _metadata</span>[</span>key</span>]</span>;</span></span> }</span></span> </span> function</span> setContractMetadata</span>(</span>string</span> calldata</span> key</span>,</span> bytes</span> calldata</span> value</span>)</span> external</span> {</span></span> _metadata</span>[</span>key</span>]</span> =</span> value</span>;</span></span> emit</span> ContractMetadataUpdated</span>(</span>key</span>,</span> key</span>,</span> value</span>)</span>;</span></span> }</span></span> }</span></span></code></pre>Diamond Storage Implementation</h3> pragma</span> solidity</span> ^0.8.25</span>;</span></span> </span> import</span> "./IERC8049.sol"</span>;</span></span> </span> contract</span> DiamondContractMetadata</span> is</span> IERC8049</span> {</span></span> struct</span> ContractMetadataStorage</span> {</span></span> mapping</span>(</span>string</span> key </span>=></span> bytes</span> value</span>)</span> metadata</span>;</span></span> }</span></span> </span> //</span> keccak256("erc8049.contract.metadata.storage")</span></span> bytes32</span> private</span> constant</span> CONTRACT_METADATA_STORAGE_LOCATION </span>=</span></span> keccak256</span>(</span>"erc8049.contract.metadata.storage"</span>)</span>;</span></span> </span> function</span> _getContractMetadataStorage</span>(</span>)</span> private</span> pure</span> returns</span> (</span>ContractMetadataStorage</span> storage</span> $</span>)</span> {</span></span> bytes32</span> location </span>=</span> CONTRACT_METADATA_STORAGE_LOCATION</span>;</span></span> assembly</span> {</span></span> $</span>.</span>slot </span>:=</span> location</span></span> }</span></span> }</span></span> </span> function</span> getContractMetadata</span>(</span>string</span> calldata</span> key</span>)</span> external</span> view</span> override</span> returns</span> (</span>bytes</span> memory</span>)</span> {</span></span> ContractMetadataStorage </span>storage</span> $ </span>=</span> _getContractMetadataStorage</span>(</span>)</span>;</span></span> return</span> $</span>.</span>metadata</span>[</span>key</span>]</span>;</span></span> }</span></span> </span> function</span> setContractMetadata</span>(</span>string</span> calldata</span> key</span>,</span> bytes</span> calldata</span> value</span>)</span> external</span> {</span></span> ContractMetadataStorage </span>storage</span> $ </span>=</span> _getContractMetadataStorage</span>(</span>)</span>;</span></span> $</span>.</span>metadata</span>[</span>key</span>]</span> =</span> value</span>;</span></span> emit</span> ContractMetadataUpdated</span>(</span>key</span>,</span> key</span>,</span> value</span>)</span>;</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> This ERC is designed to put metadata onchain, providing security benefits through onchain storage.</p> Implementations that choose to use the optional Diamond Storage pattern should consider the security considerations of ERC-8042</a>.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Referable NFT Royalties 2025-10-02T00:00:00+00:00 Abstract</h2> This ERC proposes Royalty Motivatio Specif The key words "MUST", Interface</h3> The IRNFTRoyalty </span> </span> </span> </span> </span> </span> </span> Implementations Additional interfaces </ul> RECOMMENDED Typed Struct</p> Structs</h4> RoyaltyInfo</code>: recipient: The address royaltyAmount</code>: </ul> </li> ReferenceRoyalty</code>: royaltyInfos</code>: referenceDepth</code>: </ul> </li> </ul> Functions</h4> getReferenceRoyaltyInfo(address Returns a ReferenceRoyalty Includes primary-level MUST return zero </ul> </li> getReferenceRoyaltyInfo(address Returns a ReferenceRoyalty Includes primary-level MUST return the </ul> </li> setReferenceRoyalty(address Configures royalties recipients and royaltyFractions referenceDepth limits MUST be restricted MUST enforce a total </ul> </li> setReferenceRoyalty(address Signature-based MUST verify signer The signer parameter </ul> </li> supportsReferenceRoy Returns true if </ul> </li> royaltyNonce(address Returns the current </ul> </li> </ul> Events</h4> ReferenceRoyaltiesP </ul> Example</h3> For an rNFT (contract Configuration:</p> Primary royalties: Depth 1: Two referenced Depth 2: No royalties </ul> </li> getReferenceRoyaltyInfo(0xABC, Returns:</p> { royaltyInfos: [ </li> </ul> </li> Sale for 100 ETH:</p> getReferenceRoyaltyInfo(0xABC, { royaltyInfos: [ </li> </ul> </li> </ul> Rationale</h2> Fixed Royalty Query: Multiple Recipients: Single Depth Limit: Standalone Design: Voluntary Royalties: Transparency: On-chain ERC-165 Discoverability: EIP-712 Signatures: </ul> Backwards This standard is Checking ERC-165: Calling getReferenc Optionally leveraging </ul> pragma </span> import import import import import import </span> import </span> interface </span> contract </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> Access Control: Total Royalty Cap Gas Limits: referen Input Validation: Interface Signaling: Signature Replay: </ul> Copyright</h2> Copyright and related Agent Council Oracles 2025-09-28T00:00:00+00:00 Distribution, a standalone royalty distribution for Referable Non-Fungible Tokens (rNFTs). It enables royalty distribution to multiple recipients at the primary level and referenced NFTs in the directed acyclic graph (DAG), with a single depth limit to control propagation. The standard is independent of ERC-2981</a>. and token-standard-agnostic, but expects ERC-5521</a> rNFTs, which in practice build on ERC-721</a> ownership semantics. It includes a function to query fixed royalty amounts (in basis points) for transparency. Royalties are voluntary, transparent, and configurable on-chain, supporting collaborative ecosystems and fair compensation.</p> n</h2> ;wg-eips.ritovision.com/5521/">ERC-5521</a> introduces Referable NFTs (rNFTs), which form a DAG through "referring" and "referred" relationships. Existing royalty standards like ERC-2981</a> do not account for this structure or support multiple recipients per level. This EIP addresses the need for a royalty mechanism that:</p> recipients per royalty level (e.g., creators and collaborators).</li> to referenced NFTs in the DAG.</li> with a single reference depth.</li> to query fixed royalty amounts without a sale price.</li> to query fixed royalty amounts with a sale price.</li> of ERC-721</a> or ERC-2981</a>.</li> for marketplaces and users.</li> via ERC-165</a> supportsInterface.</li> EIP-712</a> signature-based configuration to streamline marketplace or owner-driven updates.</li> ication</h2> "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.</p> interface defines the royalty distribution for rNFTs and MUST inherit ERC165</code> so that supporting contracts can advertise compliance via ERC-165</a>:</p> data-lang="solidity">//</span> SPDX-License-Identifier: CC0-1.0</span></span> class="z-keyword">pragma</span> solidity</span> ^0.8.0</span>;</span></span> class="z-storage z-type">interface</span> IRNFTRoyalty</span> is</span> ERC165</span> {</span></span> class="z-storage z-type"> struct</span> RoyaltyInfo</span> {</span></span> class="z-support"> address</span> recipient</span>;</span> //</span> Address to receive royalty</span></span> class="z-support"> uint256</span> royaltyAmount</span>;</span> //</span> Royalty amount (in wei for sale-based queries, basis points for fixed queries)</span></span> }</span></span> class="z-storage z-type"> struct</span> ReferenceRoyalty</span> {</span></span> RoyaltyInfo</span>[</span>]</span> royaltyInfos</span>;</span> //</span> Array of recipients and their royalty amounts</span></span> class="z-support"> uint256</span> referenceDepth</span>;</span> //</span> Maximum depth in the reference DAG for royalty distribution</span></span> }</span></span> class="z-storage z-type"> event</span> ReferenceRoyaltiesPaid</span>(</span></span> class="z-support"> address</span> indexed</span> rNFTContract</span>,</span></span> class="z-support"> uint256</span> indexed</span> tokenId</span>,</span></span> class="z-support"> address</span> indexed</span> buyer</span>,</span></span> class="z-support"> address</span> marketplace</span>,</span></span> class="z-variable"> ReferenceRoyalty</span> royalties</span></span> )</span>;</span></span> class="z-storage z-type"> function</span> getReferenceRoyaltyInfo</span>(</span></span> class="z-support"> address</span> rNFTContract</span>,</span></span> class="z-support"> uint256</span> tokenId</span>,</span></span> class="z-support"> uint256</span> salePrice</span></span> )</span> external</span> view</span> returns</span> (</span>ReferenceRoyalty</span> memory</span> royalties</span>)</span>;</span></span> class="z-storage z-type"> function</span> getReferenceRoyaltyInfo</span>(</span></span> class="z-support"> address</span> rNFTContract</span>,</span></span> class="z-support"> uint256</span> tokenId</span></span> )</span> external</span> view</span> returns</span> (</span>ReferenceRoyalty</span> memory</span> royalties</span>)</span>;</span></span> class="z-storage z-type"> function</span> setReferenceRoyalty</span>(</span></span> class="z-support"> address</span> rNFTContract</span>,</span></span> class="z-support"> uint256</span> tokenId</span>,</span></span> class="z-support"> address</span>[</span>]</span> memory</span> recipients</span>,</span></span> class="z-support"> uint256</span>[</span>]</span> memory</span> royaltyFractions</span>,</span></span> class="z-support"> uint256</span> referenceDepth</span></span> )</span> external</span>;</span></span> </span></span> class="z-storage z-type"> function</span> setReferenceRoyalty</span>(</span></span> class="z-support"> address</span> rNFTContract</span>,</span></span> class="z-support"> uint256</span> tokenId</span>,</span></span> class="z-support"> address</span>[</span>]</span> memory</span> recipients</span>,</span></span> class="z-support"> uint256</span>[</span>]</span> memory</span> royaltyFractions</span>,</span></span> class="z-support"> uint256</span> referenceDepth</span>,</span></span> class="z-support"> address</span> signer</span>,</span></span> class="z-support"> uint256</span> deadline</span>,</span></span> class="z-support"> bytes</span> calldata</span> signature</span></span> )</span> external</span>;</span></span> class="z-storage z-type"> function</span> supportsReferenceRoyalties</span>(</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> </span></span> class="z-storage z-type"> function</span> royaltyNonce</span>(</span>address</span> signer</span>,</span> address</span> rNFTContract</span>,</span> uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> }</span></span></code></pre> ERC-165 requirement</h3> MUST return true for supportsInterface(type(IRNFTRoyalty).interfaceId)</code>.</li> (e.g., AccessControl) SHOULD be forwarded via super.supportsInterface(interfaceId)</code> when using inheritance.</li> guration">Signature-Based Configuration</h3> and flexible configuration, implementations MUST support the following semantics for the signature overload:</p> recovered EIP-712 signer MUST satisfy one of: ract).ownerOf(tokenId)</code> at verification time.</li> message MUST include a nonce; the contract MUST track, verify, and increment a nonce to prevent replay.</li> EIP-712 domain and struct as below (reference implementation provided).</li> compared against block.timestamp; signatures with block.timestamp > deadline MUST be rejected.</li> version = "2", chainId, verifyingContract = address(this)</li> data-lang="plain">SetReferenceRoyalty(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> bytes32 recipientsHash, // keccak256(abi.encode(recipients))</span></span> bytes32 royaltyFractionsHash, // keccak256(abi.encode(royaltyFractions))</span></span> uint256 referenceDepth,</span></span> address signer,</span></span> uint256 deadline,</span></span> uint256 nonce</span></span> )</span></span></code></pre>Key Components</h3> to receive the royalty payment.</li> The royalty amount, in wei for getReferenceRoyaltyInfo</code> with salePrice, or basis points (e.g., 100 = 1%) for getReferenceRoyaltyInfo</code> without salePrice.</li> An array of RoyaltyInfo</code> for multiple recipients at the primary level and referenced NFTs.</li> A single value limiting royalty distribution to referenced NFTs in the DAG.</li> rNFTContract, uint256 tokenId, uint256 salePrice)</code>:</p> struct with royalty amounts in wei, calculated from the salePrice.</li> royalties and referenced NFT royalties up to referenceDepth</code>.</li> amounts if no royalties are configured or if salePrice is zero.</li> rNFTContract, uint256 tokenId)</code>:</p> struct with fixed royalty amounts in basis points (e.g., 100 = 1%).</li> royalties and referenced NFT royalties up to referenceDepth.</li> configured royalty fractions without sale price calculations.</li> rNFTContract, uint256 tokenId, address[] recipients, uint256[] royaltyFractions, uint256 referenceDepth)</code>:</p> for the specified rNFT.</li> (in basis points) define primary-level royalties.</li> royalty distribution to referenced NFTs.</li> to authorized parties (e.g., rNFT contract owner).</li> primary-level royalty cap of ≤ 1000 basis points (10%).</li> rNFTContract, uint256 tokenId, address[] recipients, uint256[] royaltyFractions, uint256 referenceDepth, address signer, uint256 deadline, bytes signature)</code>:</p> configuration per EIP-712.</li> authorization, nonce, and enforce deadline to reject expired signatures.</li> specifies which address is expected to have signed the message, enabling relayer execution.</li> alties()</code>:</p> the contract implements this standard. Discovery MUST rely on ERC-165.</li> signer, address rNFTContract, uint256 tokenId) external view returns (uint256)</code>:</p> nonce used for EIP-712 signatures.</li> aid</code>: Emitted when royalties are paid, logging the rNFT contract, token ID, buyer, marketplace, and ReferenceRoyalty</code> details (with royaltyAmount in wei).</li> model">Royalty Distribution Model</h3> The rNFT’s royaltyInfos array specifies multiple recipients and their fractions (e.g., 5% total, split as 3% and 2%).</li> At each hop, a total forwarded share equal to REFERRED_ROYALTY_FRACTION (e.g., 200 bps / 2%) is carved out and distributed across all referenced NFTs at that depth proportional to their configured weights (fallback: evenly if all weights are zero).</li> (Primary Level): The 10% (1000 bps) cap applies to the primary-level configured royaltyFractions. Propagated/reference-level flows are governed separately by REFERRED_ROYALTY_FRACTION and referenceDepth.</li> MUST cap referenceDepth</code>; this reference implementation enforces <= 3 (RECOMMENDED).</li> The getReferenceRoyaltyInfo</code> function without salePrice returns royalty fractions in basis points, enabling transparent inspection.</li> 0xABC, token ID 1) with referenceDepth</code> = 2:</p> 5% (3% to creator, 2% to collaborator).</li> NFTs; a total of 2% is forwarded at depth 1 and split equally (1% each) under equal weights.</li> (capped by referenceDepth).</li> 1)</code>:</p> {recipient: creator, royaltyAmount: 300}, {recipient: collaborator, royaltyAmount: 200}, {recipient: tokenA_owner, royaltyAmount: 100}, {recipient: tokenB_owner, royaltyAmount: 100} ], referenceDepth: 2 }.</p> 1, 100 ether) returns:</p> {recipient: creator, royaltyAmount: 3 ether}, {recipient: collaborator, royaltyAmount: 2 ether}, {recipient: tokenA_owner, royaltyAmount: 1 ether}, {recipient: tokenB_owner, royaltyAmount: 1 ether} ], referenceDepth: 2 }.</p> The new getReferenceRoyaltyInfo</code> function without salePrice allows users to inspect fixed royalty fractions (in basis points), improving transparency.</li> The RoyaltyInfo</code> array supports collaborative projects.</li> Simplifies configuration and reduces gas costs.</li> Ensures compatibility with any ERC-5521 contract.</li> Aligns with marketplace practices.</li> storage and fixed-amount queries enable verifiable royalties.</li> Marketplaces and wallets can reliably detect support via supportsInterface, avoiding ad-hoc feature flags.</li> Off-chain approvals enable safe, gas-efficient configurations.</li> Compatibility</h2> independent of ERC-2981 and targets ERC-5521 rNFTs, which in practice build on ERC-721 ownership semantics. Marketplaces can integrate by:</p> supportsInterface(type(IRNFTRoyalty).interfaceId)</code>.</li> eRoyaltyInfo</code> (with or without sale price).</li> the signature-based configuration for off-chain workflows.</li> ion">Reference Implementation</h2> data-lang="plain">// SPDX-License-Identifier: CC0-1.0</span></span> solidity ^0.8.0;</span></span> "@openzeppelin/contracts/access/AccessControl.sol";</span></span> "@openzeppelin/contracts/utils/cryptography/EIP712.sol"; </span></span> "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";</span></span> "@openzeppelin/contracts/utils/introspection/IERC165.sol";</span></span> "@openzeppelin/contracts/token/ERC721/IERC721.sol";</span></span> "@openzeppelin/contracts/utils/ReentrancyGuard.sol";</span></span> "./IRNFTRoyalty.sol";</span></span> IERC_5521 is IERC165 {</span></span> function setNode(uint256 tokenId, address[] memory addresses, uint256[][] memory tokenIds) external;</span></span> function referringOf(address _address, uint256 tokenId) external view returns (address[] memory, uint256[][] memory);</span></span> function referredOf(address _address, uint256 tokenId) external view returns (address[] memory, uint256[][] memory);</span></span> function supportsInterface(bytes4 interfaceId) external view returns (bool);</span></span> }</span></span> RNFTRoyalty is IRNFTRoyalty, AccessControl, EIP712, ReentrancyGuard {</span></span> using ECDSA for bytes32;</span></span> bytes32 public constant CONFIGURATOR_ROLE = keccak256("CONFIGURATOR_ROLE");</span></span> uint256 private constant MAX_ROYALTY_FRACTION = 1000; // 10%</span></span> uint256 private constant REFERRED_ROYALTY_FRACTION = 200; // 2%</span></span> uint256 private constant MAX_CHAIN_STEPS = 32;</span></span> uint256 private constant MAX_RECIPIENTS = 64;</span></span> // storage</span></span> mapping(address => mapping(uint256 => ReferenceRoyalty)) private _royalties;</span></span> event ReferenceRoyaltyConfigured(</span></span> address indexed rNFTContract,</span></span> uint256 indexed tokenId,</span></span> address indexed setter,</span></span> address[] recipients,</span></span> uint256[] royaltyFractions,</span></span> uint256 referenceDepth,</span></span> bool viaSignature</span></span> );</span></span> // EIP-712 typed data & nonce</span></span> bytes32 private constant _SET_TYPEHASH =</span></span> keccak256("SetReferenceRoyalty(address rNFTContract,uint256 tokenId,bytes32 recipientsHash,bytes32 royaltyFractionsHash,uint256 referenceDepth,address signer,uint256 deadline,uint256 nonce)");</span></span> // (signer => rNFT => tokenId => nonce)</span></span> mapping(address => mapping(address => mapping(uint256 => uint256))) private _sigNonces;</span></span> constructor() EIP712("RNFTRoyalty", "2") {</span></span> _grantRole(DEFAULT_ADMIN_ROLE, msg.sender);</span></span> _grantRole(CONFIGURATOR_ROLE, msg.sender);</span></span> }</span></span> // ===== IRNFTRoyalty =====</span></span> // expose nonce for off-chain signing</span></span> function royaltyNonce(address signer, address rNFTContract, uint256 tokenId)</span></span> external</span></span> view</span></span> returns (uint256)</span></span> {</span></span> return _sigNonces[signer][rNFTContract][tokenId];</span></span> }</span></span> function setReferenceRoyalty(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address[] calldata recipients,</span></span> uint256[] calldata royaltyFractions,</span></span> uint256 referenceDepth</span></span> ) external onlyRole(CONFIGURATOR_ROLE) {</span></span> _configureRoyalty(rNFTContract, tokenId, recipients, royaltyFractions, referenceDepth);</span></span> emit ReferenceRoyaltyConfigured(</span></span> rNFTContract,</span></span> tokenId,</span></span> msg.sender,</span></span> recipients,</span></span> royaltyFractions,</span></span> referenceDepth,</span></span> false</span></span> );</span></span> }</span></span> /// @notice Configure reference royalty via EIP-712 signature (supports relayers).</span></span> /// @dev</span></span> /// - Uses explicit `signer` for nonce lookup and authorization; caller can be a relayer.</span></span> /// - Includes `deadline` in the signed struct; reverts with "Signature expired" if now > deadline.</span></span> /// - Non-reentrant to defend against malicious `rNFT.ownerOf` implementations.</span></span> /// - Authorization: `signer` must have `CONFIGURATOR_ROLE` or be current `ownerOf(tokenId)`.</span></span> /// - Nonce scope: per-signer-per-token; increments on success to prevent replay.</span></span> function setReferenceRoyalty(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address[] calldata recipients,</span></span> uint256[] calldata royaltyFractions,</span></span> uint256 referenceDepth,</span></span> address signer,</span></span> uint256 deadline,</span></span> bytes calldata signature</span></span> ) external nonReentrant {</span></span> _checkParams(rNFTContract, recipients, royaltyFractions, referenceDepth);</span></span> bytes32 recipientsHash = keccak256(abi.encode(recipients));</span></span> bytes32 fractionsHash = keccak256(abi.encode(royaltyFractions));</span></span> // Compute expected signer digest and use per-signer-per-token nonce (explicit signer for relaying)</span></span> require(signer != address(0), "Invalid signer");</span></span> uint256 nonce = _sigNonces[signer][rNFTContract][tokenId];</span></span> require(block.timestamp <= deadline, "Signature expired");</span></span> bytes32 structHash = keccak256(</span></span> abi.encode(</span></span> _SET_TYPEHASH,</span></span> rNFTContract,</span></span> tokenId,</span></span> recipientsHash,</span></span> fractionsHash,</span></span> referenceDepth,</span></span> signer,</span></span> deadline,</span></span> nonce</span></span> )</span></span> );</span></span> bytes32 digest = _hashTypedDataV4(structHash);</span></span> address recovered = ECDSA.recover(digest, signature);</span></span> require(recovered == signer && signer != address(0), "Invalid signature");</span></span> // Authorization: CONFIGURATOR_ROLE or current owner</span></span> bool authorized = hasRole(CONFIGURATOR_ROLE, signer);</span></span> if (!authorized) {</span></span> address owner = _safeOwnerOf(IERC721(rNFTContract), tokenId);</span></span> require(signer == owner, "Signer not authorized");</span></span> }</span></span> // effects: bump nonce to prevent replay</span></span> _sigNonces[signer][rNFTContract][tokenId] = nonce + 1;</span></span> // configure royalties</span></span> _configureRoyalty(rNFTContract, tokenId, recipients, royaltyFractions, referenceDepth);</span></span> emit ReferenceRoyaltyConfigured(</span></span> rNFTContract,</span></span> tokenId,</span></span> signer,</span></span> recipients,</span></span> royaltyFractions,</span></span> referenceDepth,</span></span> true</span></span> );</span></span> }</span></span> /// @notice Compute reference royalty distribution for a concrete sale price (values in wei).</span></span> /// @param rNFTContract RNFT contract implementing IERC_5521</span></span> /// @param tokenId Token id</span></span> /// @param salePrice Sale price in wei</span></span> function getReferenceRoyaltyInfo(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> uint256 salePrice</span></span> ) external view returns (ReferenceRoyalty memory royalties) {</span></span> royalties = _royalties[rNFTContract][tokenId];</span></span> if (salePrice == 0) {</span></span> uint256 len = royalties.royaltyInfos.length;</span></span> if (len == 0) return royalties;</span></span> RoyaltyInfo[] memory zeroed = new RoyaltyInfo[](len);</span></span> for (uint256 i = 0; i < len; i++) {</span></span> zeroed[i] = RoyaltyInfo(royalties.royaltyInfos[i].recipient, 0);</span></span> }</span></span> royalties.royaltyInfos = zeroed;</span></span> return royalties;</span></span> }</span></span> RoyaltyInfo[] memory chainRoyalties = _calculateChainRoyalties(rNFTContract, tokenId, salePrice);</span></span> royalties.royaltyInfos = chainRoyalties;</span></span> return royalties;</span></span> }</span></span> /// @notice Compute reference royalty distribution in basis points (bps), i.e. relative amounts.</span></span> /// @param rNFTContract RNFT contract implementing IERC_5521</span></span> /// @param tokenId Token id</span></span> function getReferenceRoyaltyInfo(</span></span> address rNFTContract,</span></span> uint256 tokenId</span></span> ) external view returns (ReferenceRoyalty memory royalties) {</span></span> royalties = _royalties[rNFTContract][tokenId];</span></span> if (royalties.royaltyInfos.length == 0) return royalties;</span></span> RoyaltyInfo[] memory bpsRoyalties = _calculateChainRoyalties(rNFTContract, tokenId, 0);</span></span> royalties.royaltyInfos = bpsRoyalties;</span></span> return royalties;</span></span> }</span></span> function supportsReferenceRoyalties() external pure returns (bool) {</span></span> return true;</span></span> }</span></span> // ===== ERC-165 =====</span></span> function supportsInterface(bytes4 interfaceId)</span></span> public</span></span> view</span></span> override(AccessControl, IERC165)</span></span> returns (bool)</span></span> {</span></span> return</span></span> interfaceId == type(IRNFTRoyalty).interfaceId \|\|</span></span> super.supportsInterface(interfaceId);</span></span> }</span></span> // ===== Internal =====</span></span> function _checkParams(</span></span> address rNFTContract,</span></span> address[] calldata recipients,</span></span> uint256[] calldata royaltyFractions,</span></span> uint256 referenceDepth</span></span> ) internal pure {</span></span> require(rNFTContract != address(0), "Invalid contract");</span></span> require(recipients.length == royaltyFractions.length, "Length mismatch");</span></span> require(recipients.length <= MAX_RECIPIENTS, "Too many recipients");</span></span> require(referenceDepth <= 3, "Depth too high");</span></span> for (uint256 i = 0; i < recipients.length; ++i) {</span></span> require(recipients[i] != address(0), "Zero recipient");</span></span> }</span></span> }</span></span> function _configureRoyalty(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address[] calldata recipients,</span></span> uint256[] calldata royaltyFractions,</span></span> uint256 referenceDepth</span></span> ) internal {</span></span> uint256 totalFraction = 0;</span></span> for (uint256 i = 0; i < royaltyFractions.length; i++) {</span></span> totalFraction += royaltyFractions[i];</span></span> }</span></span> require(totalFraction <= MAX_ROYALTY_FRACTION, "Royalty cap exceeded");</span></span> ReferenceRoyalty memory config;</span></span> config.referenceDepth = referenceDepth;</span></span> config.royaltyInfos = new RoyaltyInfo[](recipients.length);</span></span> for (uint256 i = 0; i < recipients.length; i++) {</span></span> config.royaltyInfos[i] = RoyaltyInfo(recipients[i], royaltyFractions[i]);</span></span> }</span></span> _royalties[rNFTContract][tokenId] = config;</span></span> }</span></span> function _safeOwnerOf(IERC721 rNFT, uint256 tokenId) internal view returns (address) {</span></span> address owner = rNFT.ownerOf(tokenId);</span></span> require(owner != address(0), "No owner");</span></span> return owner;</span></span> }</span></span> function _calculateChainRoyalties(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> uint256 salePrice</span></span> ) internal view returns (RoyaltyInfo[] memory) {</span></span> ReferenceRoyalty memory currentRoyalty = _royalties[rNFTContract][tokenId];</span></span> if (currentRoyalty.royaltyInfos.length == 0) {</span></span> return new RoyaltyInfo[](0);</span></span> }</span></span> RoyaltyInfo[] memory staged = new RoyaltyInfo[](MAX_CHAIN_STEPS 32 + 32);</span></span> uint256 count = 0;</span></span> uint256 totalShare = _sumShares(currentRoyalty);</span></span> (uint256 netPrimary, uint256 remainder) = _splitRoyalty(totalShare, salePrice, currentRoyalty.referenceDepth > 0);</span></span> count = _appendDistribution(staged, count, currentRoyalty, netPrimary);</span></span> if (remainder == 0) {</span></span> return _shrink(staged, count);</span></span> }</span></span> // Layered aggregation (BFS) to support multi-parent merges</span></span> uint256 maxItems = MAX_CHAIN_STEPS * 32 + 32;</span></span> address[] memory curContracts = new address[](maxItems);</span></span> uint256[] memory curIds = new uint256[](maxItems);</span></span> uint256[] memory curAmts = new uint256[](maxItems);</span></span> uint256[] memory curDepths = new uint256[](maxItems);</span></span> uint256 curCount = 0;</span></span> if (remainder > 0 && currentRoyalty.referenceDepth > 0) {</span></span> curContracts[0] = rNFTContract;</span></span> curIds[0] = tokenId;</span></span> curAmts[0] = remainder;</span></span> curDepths[0] = currentRoyalty.referenceDepth;</span></span> curCount = 1;</span></span> }</span></span> address[] memory processedContracts = new address[](maxItems);</span></span> uint256[] memory processed = new uint256[](maxItems);</span></span> uint256 processedCount = 0;</span></span> while (curCount > 0) {</span></span> address[] memory nextContracts = new address[](maxItems);</span></span> uint256[] memory nextIds = new uint256[](maxItems);</span></span> uint256[] memory nextAmts = new uint256[](maxItems);</span></span> uint256[] memory nextDepths = new uint256[](maxItems);</span></span> uint256 nextCount = 0;</span></span> for (uint256 iL = 0; iL < curCount; iL++) {</span></span> address curContract = curContracts[iL];</span></span> uint256 curId = curIds[iL];</span></span> uint256 amt = curAmts[iL];</span></span> uint256 depth = curDepths[iL];</span></span> if (amt == 0) continue;</span></span> IERC_5521 curRNFT = IERC_5521(curContract);</span></span> IERC721 curRNFT721 = IERC721(curContract);</span></span> bool seen = false;</span></span> for (uint256 p = 0; p < processedCount; p++) {</span></span> if (processed[p] == curId && processedContracts[p] == curContract) { seen = true; break; }</span></span> }</span></span> if (seen) {</span></span> address cycOwner = _safeOwnerOf(curRNFT721, curId);</span></span> staged[count++] = RoyaltyInfo(cycOwner, amt);</span></span> continue;</span></span> }</span></span> uint256 maxChildren = 32;</span></span> address[] memory childContracts = new address[](maxChildren);</span></span> uint256[] memory childIds = new uint256[](maxChildren);</span></span> uint256 children = _collectReferring(curRNFT, curContract, curId, childContracts, childIds);</span></span> if (depth == 0 \|\| children == 0) {</span></span> address fallbackOwner = _safeOwnerOf(curRNFT721, curId);</span></span> staged[count++] = RoyaltyInfo(fallbackOwner, amt);</span></span> processedContracts[processedCount] = curContract;</span></span> processed[processedCount++] = curId;</span></span> continue;</span></span> }</span></span> uint256 keepBase = (amt * (10_000 - REFERRED_ROYALTY_FRACTION)) / 10_000;</span></span> uint256 passBase = amt - keepBase;</span></span> uint256[] memory childWeights = new uint256[](maxChildren);</span></span> ReferenceRoyalty[] memory childConfigs = new ReferenceRoyalty[](maxChildren);</span></span> uint256 sumWeights = 0;</span></span> for (uint256 j = 0; j < children; j++) {</span></span> address childContract = childContracts[j];</span></span> uint256 cid = childIds[j];</span></span> ReferenceRoyalty memory cfg = _royalties[childContract][cid];</span></span> childConfigs[j] = cfg;</span></span> if (cfg.royaltyInfos.length > 0) {</span></span> uint256 w = _sumShares(cfg);</span></span> childWeights[j] = w;</span></span> sumWeights += w;</span></span> }</span></span> }</span></span> if (sumWeights == 0) {</span></span> uint256 each = amt / children;</span></span> uint256 rem = amt - (each * children);</span></span> for (uint256 j = 0; j < children; j++) {</span></span> address ow = _safeOwnerOf(IERC721(childContracts[j]), childIds[j]);</span></span> uint256 share = each + (j == children - 1 ? rem : 0);</span></span> staged[count++] = RoyaltyInfo(ow, share);</span></span> }</span></span> processedContracts[processedCount] = curContract;</span></span> processed[processedCount++] = curId;</span></span> continue;</span></span> }</span></span> uint256 passDistributed = 0;</span></span> uint256 lastWeightedIdx = 0;</span></span> uint256[] memory keepShares = new uint256[](children);</span></span> uint256[] memory passShares = new uint256[](children);</span></span> for (uint256 j = 0; j < children; j++) {</span></span> if (childWeights[j] == 0) continue;</span></span> lastWeightedIdx = j;</span></span> uint256 kShare = (keepBase * childWeights[j]) / sumWeights;</span></span> uint256 pShare = (passBase * childWeights[j]) / sumWeights;</span></span> keepShares[j] = kShare;</span></span> passShares[j] = pShare;</span></span> passDistributed += pShare;</span></span> }</span></span> // Remainders: pass and keep</span></span> uint256 passRemainder = passBase - passDistributed;</span></span> if (passRemainder > 0) {</span></span> passShares[lastWeightedIdx] += passRemainder;</span></span> }</span></span> uint256 keepDistributed = 0;</span></span> for (uint256 j2 = 0; j2 < children; j2++) {</span></span> keepDistributed += keepShares[j2];</span></span> }</span></span> uint256 keepRemainder = keepBase - keepDistributed;</span></span> if (keepRemainder > 0) {</span></span> keepShares[lastWeightedIdx] += keepRemainder;</span></span> }</span></span> for (uint256 j = 0; j < children; j++) {</span></span> if (childWeights[j] == 0) continue;</span></span> uint256 kShare = keepShares[j];</span></span> uint256 pShare = passShares[j];</span></span> ReferenceRoyalty memory cfgj = childConfigs[j];</span></span> uint256 cid2 = childIds[j];</span></span> address childContract = childContracts[j];</span></span> uint256 nextDepth = depth > 0 ? depth - 1 : 0;</span></span> if (nextDepth == 0) {</span></span> // Depth exhausted: distribute both keep and pass to child's recipients</span></span> count = _appendDistribution(staged, count, cfgj, kShare + pShare);</span></span> } else {</span></span> if (kShare > 0) {</span></span> count = _appendDistribution(staged, count, cfgj, kShare);</span></span> }</span></span> if (pShare > 0) {</span></span> bool merged = false;</span></span> for (uint256 nx = 0; nx < nextCount; nx++) {</span></span> if (nextIds[nx] == cid2 && nextContracts[nx] == childContract) {</span></span> nextAmts[nx] += pShare;</span></span> if (nextDepth > nextDepths[nx]) {</span></span> nextDepths[nx] = nextDepth;</span></span> }</span></span> merged = true;</span></span> break;</span></span> }</span></span> }</span></span> if (!merged) {</span></span> nextContracts[nextCount] = childContract;</span></span> nextIds[nextCount] = cid2;</span></span> nextAmts[nextCount] = pShare;</span></span> nextDepths[nextCount] = nextDepth;</span></span> nextCount++;</span></span> }</span></span> }</span></span> }</span></span> }</span></span> processedContracts[processedCount] = curContract;</span></span> processed[processedCount++] = curId;</span></span> }</span></span> for (uint256 k = 0; k < nextCount; k++) {</span></span> curContracts[k] = nextContracts[k];</span></span> curIds[k] = nextIds[k];</span></span> curAmts[k] = nextAmts[k];</span></span> curDepths[k] = nextDepths[k];</span></span> }</span></span> curCount = nextCount;</span></span> }</span></span> return _shrink(staged, count);</span></span> }</span></span> function _splitRoyalty(uint256 totalRate, uint256 salePrice, bool canPropagate)</span></span> internal</span></span> pure</span></span> returns (uint256 netPrimary, uint256 forwardedAmount)</span></span> {</span></span> if (totalRate == 0) {</span></span> return (0, 0);</span></span> }</span></span> if (!canPropagate) {</span></span> if (salePrice == 0) {</span></span> return (totalRate, 0);</span></span> }</span></span> return ((salePrice * totalRate) / 10_000, 0);</span></span> }</span></span> if (salePrice == 0) {</span></span> if (totalRate <= REFERRED_ROYALTY_FRACTION) {</span></span> return (0, totalRate);</span></span> }</span></span> return (totalRate - REFERRED_ROYALTY_FRACTION, REFERRED_ROYALTY_FRACTION);</span></span> }</span></span> uint256 gross = (salePrice * totalRate) / 10_000;</span></span> uint256 forwarded = (salePrice * REFERRED_ROYALTY_FRACTION) / 10_000;</span></span> if (forwarded > gross) {</span></span> forwarded = gross;</span></span> }</span></span> return (gross > forwarded ? gross - forwarded : 0, forwarded);</span></span> }</span></span> function _sumShares(ReferenceRoyalty memory config) internal pure returns (uint256 total) {</span></span> for (uint256 i = 0; i < config.royaltyInfos.length; i++) {</span></span> total += config.royaltyInfos[i].royaltyAmount;</span></span> }</span></span> }</span></span> function _collectReferring(</span></span> IERC_5521 rNFT,</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address[] memory childContracts,</span></span> uint256[] memory childIds</span></span> ) internal view returns (uint256 childCount) {</span></span> (address[] memory refContracts, uint256[][] memory refTokenIds) =</span></span> rNFT.referringOf(rNFTContract, tokenId);</span></span> uint256 maxChildren = childIds.length;</span></span> uint256 listLen = refContracts.length;</span></span> if (refTokenIds.length < listLen) {</span></span> listLen = refTokenIds.length;</span></span> }</span></span> for (uint256 i = 0; i < listLen && childCount < maxChildren; i++) {</span></span> uint256[] memory ids = refTokenIds[i];</span></span> for (uint256 j = 0; j < ids.length && childCount < maxChildren; j++) {</span></span> childContracts[childCount] = refContracts[i];</span></span> childIds[childCount] = ids[j];</span></span> childCount++;</span></span> }</span></span> }</span></span> }</span></span> function _appendDistribution(</span></span> RoyaltyInfo[] memory staged,</span></span> uint256 count,</span></span> ReferenceRoyalty memory config,</span></span> uint256 amount</span></span> ) internal pure returns (uint256) {</span></span> uint256 len = config.royaltyInfos.length;</span></span> if (len == 0) {</span></span> return count;</span></span> }</span></span> require(count + len <= staged.length, "royalty overflow");</span></span> if (amount == 0) {</span></span> for (uint256 i = 0; i < len; i++) {</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[i].recipient, 0);</span></span> }</span></span> return count;</span></span> }</span></span> uint256 totalShare = _sumShares(config);</span></span> if (totalShare == 0) {</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[0].recipient, amount);</span></span> for (uint256 i = 1; i < len; i++) {</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[i].recipient, 0);</span></span> }</span></span> return count;</span></span> }</span></span> uint256 remaining = amount;</span></span> for (uint256 i = 0; i < len; i++) {</span></span> uint256 share = config.royaltyInfos[i].royaltyAmount;</span></span> if (share == 0) {</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[i].recipient, 0);</span></span> continue;</span></span> }</span></span> uint256 portion = (amount * share) / totalShare;</span></span> if (portion > remaining) {</span></span> portion = remaining;</span></span> }</span></span> remaining -= portion;</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[i].recipient, portion);</span></span> }</span></span> if (remaining > 0) {</span></span> staged[count - 1].royaltyAmount += remaining;</span></span> }</span></span> return count;</span></span> }</span></span> function _shrink(RoyaltyInfo[] memory staged, uint256 count)</span></span> internal</span></span> pure</span></span> returns (RoyaltyInfo[] memory out)</span></span> {</span></span> out = new RoyaltyInfo[](count);</span></span> for (uint256 i = 0; i < count; i++) {</span></span> out[i] = staged[i];</span></span> }</span></span> }</span></span> function recordRoyaltyPayment(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address buyer,</span></span> ReferenceRoyalty memory royalties</span></span> ) external {</span></span> emit ReferenceRoyaltiesPaid(rNFTContract, tokenId, buyer, msg.sender, royalties);</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> setReferenceRoyalty</code> MUST be restricted to authorized roles (e.g., via AccessControl).</li> (Primary Level): The 10% (1000 bps) cap applies to the primary-level configured royaltyFractions. Propagated/reference-level flows are governed separately by REFERRED_ROYALTY_FRACTION and referenceDepth.</li> ceDepth</code> MUST be capped (e.g., ≤ 3) to avoid high gas costs.</li> Ensure non-zero addresses and valid royalty fractions.</li> Ensure supportsInterface forwards properly to parents.</li> Use a per-signer-per-(rNFTContract, tokenId) nonce, and increment after successful verification. Implementations MUST document the chosen scope.</li> rights waived via CC0</a>.</p> Abstract</h2> This ERC defines a standard interface for oracle contracts that use multi-agent councils to resolve arbitrary information queries. It enables dApps to request resolutions, general information arbitration, and build consensus and validation in a trust-minimized way, with agents submitting answers to the queries on-chain. The ERC works by a requester opening a query to be resolved. The contract then emits the RequestCreated event with parameters specifying the query, number of infoAgents, commit deadline, and reward/bond amounts, specifications, and capabilities required. A commit phase is initiated where InfoAgents can participate by staking the required bond and submitting a hash of the answer to the query as a commit. After the quorum of infoAgents have committed, the reveal process is initiated where infoAgents post the key to the commit hash. A judgeAgent is then selected to review the committed hash and answers provided by the infoAgents. The judgeAgent then selects the infoAgents which answered the query correctly and the reward is divided among the winners. The infoAgents which answered incorrectly lose their bond. The interface supports permissionless participation, bond-based incentives, and optional extensions for reputation, disputes, and callbacks, making it suitable for applications like semantic data oracles and prediction markets.</p> Motivation</h2> With AI agents advancing rapidly, we can build trust-minimized oracles that are cheaper, faster, and more scalable than traditional human or node-based systems. Traditional data oracles primarily provide quantitative feeds and are often centralized or expensive for arbitrary, one-off queries. With AI agents becoming reliable for factual resolutions from public sources, this EIP standardizes an interface for agent councils to handle query resolution via commit-reveal-judging flows, fostering interoperability across implementations. It is generalizable for discrete (defined options) or open-ended queries, with hooks for collusion deterrence and verification. Integration with reputation systems (such as that in ERC-8004</a>) is recommended but optional to keep the core lightweight.</p> This is generalizable for any resolvable information, making it useful for both qualitative and quantitative data. Existing examples we see this standard being useful for are, tracing information tasks (off-chain data processing with on-chain validation hooks), resolving prediction markets, and creating verified info feeds for DeFi platforms (aggregating real-time semantic data from multiple sources).</p> We envision an information market evolving where agents compete to answer queries, exchanging data resolutions for tokenized incentives.</p> Specification</h2> 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.</p> This EIP proposes the IAgentCouncilOracle</code> interface, which defines methods and events for a council-based resolution flow. Implementations MUST support the core flow: request creation, agent commitment, reveal, judging/aggregation, and reward distribution. An OPTIONAL dispute resolution extension is also included. Off-chain processing (LLM inference and analysis) is handled by agents, with on-chain elements opened to coordination and verification of information.</p> The council consists of two agent roles: Info Agents (who submit individual information) and Judge Agents (who aggregate and resolve consensus). We make this distinction to clarify how responsibilities from this standard are assigned.</p> Main Types</h3> //</span> Struct for query requests</span></span> struct</span> AgentCapabilities</span> {</span></span> string</span>[</span>]</span> capabilities</span>;</span> //</span> text, vision, audio etc</span></span> string</span>[</span>]</span> domains</span>;</span> //</span> Expertise areas</span></span> }</span></span> </span> struct</span> Request</span> {</span></span> address</span> requester</span>;</span></span> uint256</span> rewardAmount</span>;</span> //</span> Total reward (native token or ERC-20)</span></span> address</span> rewardToken</span>;</span> //</span> native or ERC-20 token</span></span> uint256</span> bondAmount</span>;</span> //</span> Bond per agent (native token or ERC-20)</span></span> address</span> bondToken</span>;</span> //</span> native or ERC-20 token</span></span> uint256</span> numInfoAgents</span>;</span> //</span> Target number of info agents</span></span> uint256</span> deadline</span>;</span> //</span> Unix timestamp for commit phase end</span></span> string</span> query</span>;</span> //</span> The information query</span></span> string</span> specifications</span>;</span> //</span> Additional miscellaneous instructions (optional in implementations)</span></span> AgentCapabilities requiredCapabilities</span>;</span> //</span> For filtering agents (optional in implementations)</span></span> }</span></span></code></pre>Interface</h3> interface</span> IAgentCouncilOracle</span> {</span></span> //</span> Events for transparency and monitoring</span></span> event</span> RequestCreated</span>(</span>uint256</span> indexed</span> requestId</span>, </span>address</span> requester</span>, </span>string</span> query</span>, </span>uint256</span> rewardAmount</span>, </span>uint256</span> numInfoAgents</span>, </span>uint256</span> bondAmount</span>)</span>;</span></span> event</span> AgentCommitted</span>(</span>uint256</span> indexed</span> requestId</span>, </span>address</span> agent</span>, </span>bytes32</span> commitment</span>)</span>;</span></span> event</span> AgentRevealed</span>(</span>uint256</span> indexed</span> requestId</span>, </span>address</span> agent</span>, </span>bytes</span> answer</span>)</span>;</span> //</span> Or bytes for flexibility</span></span> event</span> JudgeSelected</span>(</span>uint256</span> indexed</span> requestId</span>, </span>address</span> judge</span>)</span>;</span></span> event</span> ResolutionFinalized</span>(</span>uint256</span> indexed</span> requestId</span>, </span>bytes</span> finalAnswer</span>)</span>;</span> //</span> Or bytes</span></span> event</span> RewardsDistributed</span>(</span>uint256</span> indexed</span> requestId</span>, </span>address</span>[</span>]</span> winners</span>, </span>uint256</span>[</span>]</span> amounts</span>)</span>;</span></span> event</span> ResolutionFailed</span>(</span>uint256</span> indexed</span> requestId</span>, </span>string</span> reason</span>)</span>;</span></span> event</span> DisputeInitiated</span>(</span>uint256</span> indexed</span> requestId</span>, </span>address</span> disputer</span>, </span>string</span> reason</span>)</span>;</span></span> event</span> DisputeWindowOpened</span>(</span>uint256</span> indexed</span> requestId</span>, </span>uint256</span> endTimestamp</span>)</span>;</span></span> event</span> DisputeResolved</span>(</span>uint256</span> indexed</span> requestId</span>, </span>bool</span> overturned</span>, </span>bytes</span> finalAnswer</span>)</span>;</span></span> </span></span> </span> //</span> Core methods</span></span> function</span> createRequest</span>(</span>string</span> calldata</span> query</span>,</span> uint256</span> numInfoAgents</span>,</span> uint256</span> rewardAmount</span>,</span> uint256</span> bondAmount</span>,</span> uint256</span> deadline</span>,</span> address</span> rewardToken</span>,</span> address</span> bondToken</span>,</span> string</span> calldata</span> specifications</span>,</span> AgentCapabilities</span> calldata</span> requiredCapabilities</span>)</span> external</span> payable</span> returns</span> (</span>uint256</span> requestId</span>)</span>;</span></span> //</span> Commit: Permissionless, with bond</span></span> function</span> commit</span>(</span>uint256</span> requestId</span>,</span> bytes32</span> commitment</span>)</span> external</span> payable</span>;</span></span> //</span> Reveal: Submit answer matching commitment</span></span> function</span> reveal</span>(</span>uint256</span> requestId</span>,</span> bytes</span> calldata</span> answer</span>,</span> uint256</span> nonce</span>)</span> external</span>;</span></span> //</span> Judge/Aggregate: Called by selected judge or automatic for discrete option queries</span></span> function</span> aggregate</span>(</span>uint256</span> requestId</span>,</span> bytes</span> calldata</span> finalAnswer</span>,</span> address</span>[</span>]</span> calldata</span> winners</span>,</span> bytes</span> calldata</span> reasoning</span>)</span> external</span>;</span> //</span> Winners for reward classification</span></span> //</span> Distribute: Auto or manual post-aggregation</span></span> function</span> distributeRewards</span>(</span>uint256</span> requestId</span>)</span> external</span>;</span></span> //</span> Get final resolution</span></span> function</span> getResolution</span>(</span>uint256</span> requestId</span>)</span> external</span> view</span> returns</span> (</span>bytes</span> memory</span> finalAnswer</span>,</span> bool</span> finalized</span>)</span>;</span></span> </span> //</span> Optional Dispute Methods</span></span> function</span> initiateDispute</span>(</span>uint256</span> requestId</span>,</span> string</span> calldata</span> reason</span>)</span> external</span> payable</span>;</span></span> function</span> resolveDispute</span>(</span>uint256</span> requestId</span>,</span> bool</span> overturn</span>,</span> bytes</span> calldata</span> newAnswer</span>,</span> address</span>[</span>]</span> calldata</span> newWinners</span>)</span> external</span>;</span></span> </span> //</span> Getters for oracle flow data</span></span> function</span> getRequest</span>(</span>uint256</span> requestId</span>)</span> external</span> view</span> returns</span> (</span>Request</span> memory</span>)</span>;</span></span> function</span> getCommits</span>(</span>uint256</span> requestId</span>)</span> external</span> view</span> returns</span> (</span>address</span>[</span>]</span> memory</span> agents</span>,</span> bytes32</span>[</span>]</span> memory</span> commitments</span>)</span>;</span></span> function</span> getReveals</span>(</span>uint256</span> requestId</span>)</span> external</span> view</span> returns</span> (</span>address</span>[</span>]</span> memory</span> agents</span>,</span> bytes</span>[</span>]</span> memory</span> answers</span>)</span>;</span></span> }</span></span></code></pre> We do not enforce limits on the number or size of items in capabilities, domains, queries, or answers to maintain flexibility for evolving agent ecosystems and models. However, it is RECOMMENDED implementations impose reasonable limits on metrics such as the number of items (ex. max 64), bytes per item (ex. max 64), and/or total encoded bytes (ex. max 8192) to mitigate gas costs and DoS risks. Implementations MUST document any such limits in their code or README and MUST revert with descriptive errors (ex. CapListTooLong) if exceeded. For high-gas environments, implementations SHOULD use off-chain references (such as an IPFS hash on-chain or some external domain) for verbosity, storing only these references in the struct.</p> Core Flow</h3> Implementations MUST follow this sequence for interoperability:</p> Request Creation</strong>: Requester calls createRequest</code>, providing query, params (ex. numInfoAgents</code>, bondAmount</code>), and rewardAmount</code> (with msg.value</code> or ERC-20</a> transfer). If rewardToken == address(0)</code>, this is the native asset and createRequest MUST be payable and expect msg.value to fund the reward (and native bonds if used). If rewardToken != address(0)</code>, it MUST be an ERC-20</a> and implementations SHOULD pull funds via transferFrom</code>. Emits RequestCreated</code>. The bond is a slashable stake an agent put in, and be penalized if the submission turns out to be wrong, malicious etc. The amount and token for the bond (specified with bondAmount</code> and bondToken</code>) is implementation-specific and these MAY be different from the values used for the reward.</p> </li> Commit Process</strong>: Permissionless Info Agents call commit</code> with a hash (RECOMMENDED: keccak256(abi.encode(answer, nonce))</code>) and bond. Caps at numInfoAgents</code>. Phase ends at deadline or when all InfoAgents are committed. Emits AgentCommitted</code>.</p> </li> Reveal/Collection Process</strong>: Committed Info Agents call reveal</code> to submit answers. MUST match commitment. Emits AgentRevealed</code>. Proceed only if quorum (RECOMMENDED: >50% reveals) otherwise emit ResolutionFailed</code> and refund. This helps reduce coordination/collusion of submissions as they aren’t revealed early.</p> </li> Judging Process</strong>: After reveals, select a Judge Agent (RECOMMENDED: randomly from a separate pool, distinct from Info Agents) and emit JudgeSelected. The Judge Agent calls aggregate to submit the final answer and classify winners (majority agents). For open-ended and discrete queries, the Judge MUST synthesize revealed submissions (semantic consensus via LLM) and provide reasoning as part of the submission. In ties, the Judge MAY provide a tie-breaker with reasoning. Emits ResolutionFinalized</p> </li> Reward Distribution Process</strong>: Call distributeRewards</code> to payout correct Info Agents / Judge Agent based on config (proportional or equal splits, with implementation specific params for ratios like Judge fee percentage). Refund bonds to correct Info Agents; forfeit others. Emits RewardsDistributed</code>. Implementations MAY forfeit the Judge Agent’s bond and redistribute to correct Info Agents or proposer if the judge fails to resolve within the allotted window.</p> </li> </ol> Off-chain storage (such as IPFS for reveals/reasoning) MAY be used, with on-chain hashes for verifiability.</p> Optional Extensions</h3> Dispute Standard</strong>: Implementations MAY add a dispute mechanism post-finalization.</p> Suggested flow: After finalization, open a dispute window. Any party MAY call initiateDispute</code> with a disputeBond</code> (ex. 1.5-2x original bond) and on-chain reason (such as a hash of detailed reasoning, optionally on IPFS), emitting DisputeInitiated</code>. Re-select a Judge (randomly, with higher minReputation threshold). Judge reviews and calls resolveDispute</code> to uphold or overturn, submitting new answers/winners if overturned. If upheld, the disputer’s bond is forfeited to the correct agents and arbitration creator. If overturned, return the disputer's bond, provide reimbursement (ex. a portion of the base fee), slash the original Judge's fee/bond, and redistribute. Dispute Judge receives reimbursement (ex. some fixed/percentage fee). Emits DisputeResolved</code>.</p> Configurable params: disputeWindow</code> (duration), disputeBond</code>, minDisputeJudgeReputation</code> (higher than original), disputerReimbursement</code>, judgeReimbursement</code>. MAY integrate ERC-8004</a> for re-runs/proofs with validation hooks; partial payouts/escrow during window for efficiency.</p> Reputation Hooks</strong>: MAY integrate with ERC-8004</a> for filtering (min reputation for agents or judges) or proportional rewards. RECOMMENDED: Set a minimum reputation for Judge Agents, higher than for Info Agents, as they make a final decision. This creates an identifiable on-chain trail for accountability.</p> Callbacks</strong>: MAY add callback(address target, uint256 requestId)</code> for notifying requester contracts.</p> ERC-20</a> Rewards</strong>: Extend with token transfers instead of the native token.</p> Configs (such as phase durations, quorums, reward ratios) are implementation-specific parameters.</p> Rationale</h2> This interface standardizes a council flow for AI-driven oracles, balancing minimal on-chain logic with off-chain flexibility. Commit-reveal prevents front-running and judging enables consensus on complex queries. Bonds and optional reputation help deter attacks.</p> Reputation scores provide a rationale for enhanced security: they enable proportional reward distribution, gating participation to experienced agents, and reducing collusion risks by aligning incentives with proven performance. Without reputation, attack vectors may increase, but the core bond system offers baseline protection and we expect this baseline to allow for a self regulating rewards incentive market that drives agents to act in good faith.</p> We considered a single-round, plaintext submission model. While simpler and cheaper, it is susceptible to (i) copying attacks where later agents replicate early submissions, (ii) MEV/front-running of plaintext answers, and (iii) coercion/censorship risks when answers must be revealed before full participation. Plain text answers are easily identified and may be delayed, susceptible to being reordered, or unfavorable answers may be censored compromising the integrity of the Info Agents answers. By contrast, a commit-reveal flow keeps content hidden during the commit phase: adversaries cannot cheaply target specific answers.</p> Weighted voting (a common alternative in oracles like Universal Market Access) was evaluated as a potential replacement for distinct roles where agents could stake bonds or reputation to vote with proportional influence. This could reduce moving parts but weakens explainability and accountability for open-ended queries. Instead, a Judge allows for semantic interpretation of answers. Our role-based approach mitigates this by random Judge selection and optional reputation thresholds, promoting broader participation while maintaining checks (Judge Agents can tie-break with reasoning). This also aligns better with AI agent ecosystems, where specialized agents mirror real-world councils or juries, fostering an "information market".</em> A lack of a Judge Agent would limit the ERC to only discrete information and make it unclear how non-discrete data is resolved. We standardize the Info/Judge split for the core flow (specialization + reasoning from the Judge), while leaving weighted aggregation as an OPTIONAL extension</strong> for discrete queries.</p> Using a single agent reduces complexity but mixes retrieval/synthesis with adjudication. We determined that explicit role separation enables (a) different capability/reputation thresholds, (b) clearer slashing semantics for adjudication failures, and (c) better human-auditable reasoning trails. We intentionally separate roles for specialization and explainability.</p> The commit-reveal process is more gas-intensive (requiring two transactions per Info Agent: commit and reveal) but provides increased security through ease of verifiability and reduced attack surfaces like front-running. The increased gas is offset by preventing costly disputes from copied or manipulated answers. Other existing commit-reveal mechanisms were considered but were too constrained for our resolution flow and would have increased complexity. For example, ERC-5732</a> does not provide a built-in reveal mechanism. The reveal is a critical step in the agent council flow to ensure quorum and prevent collusion. The ERC-162</a> commit and reveal process was also considered but is not easily applicable to text fields and resolution flow here.</p> Longer form responses written directly to the blockchain may be gas-prohibitive for complex queries so off-chain storage like IPFS for larger reveals/reasoning is recommended, with on-chain hashes for integrity. This trades some security (IPFS links are not permanent and could be censored) for cost savings, but implementations can mitigate this via decentralized pinning services or agent domains from ERC-8004</a>. Creating different schemes for off-chain verifiability significantly increases complexity. To enhance usability, our core interface keeps methods lightweight, and optional extensions like disputes remain modular, allowing simple implementations for low-stakes queries while scaling to high-security ones.</p> This ERC is meant to be complimentary to recent standards like ERC-8004</a>, which provides a foundational step toward enabling agent-to-agent communication. Features like Identity, Reputation, and Validation can strengthen the verifiability and fidelity of answers from Info Agents and rulings from Judge Agents. For instance, implementations can filter participants via ERC-8004</a>'s reputation scores (minReputation params for agents). They can also use validation hooks to verify off-chain computations cryptographically, reducing reliance on bonds alone. The framework for Agent Council Oracles differs significantly. It focuses on a standard mechanism for agents to reach consensus without human input, emphasizing on-chain coordination flows (commit-reveal-judge) for query resolution.</strong> While ERC-8004</a> is geared toward trustless agent interoperability and off-chain logic, our EIP builds atop it by standardizing automated information arbitration. This can apply to specific use cases such as data oracles or prediction markets. The integration with ERC-8004</a> is optional to keep the core lightweight, but recommended for high-stakes scenarios. Other differentiators unique to our standard include our bond incentives and dispute windows, which add economic security layers otherwise absent in multi-agent coordination layers.</p> Backwards Compatibility</h2> No conflicts with existing standards.</p> Security Considerations</h2> Collusion: Mitigated by bonds (refundable for honest participation, forfeited for failures), random judge selection, and optional reputation. Bonds disincentivize spam and non-reveals by redistributing to participants.</li> Spam: Prevented by bonds and caps.</li> Failures: Refunds for low participation or abandonment.</li> Disputes: Optional for high-stakes, with higher stakes/thresholds.</li> Fairness of random selection of Judge relies on the crypto strength of randomness Implementations should audit for reentrancy and use verifiable randomness.</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Multi-step Contract Ownership 2025-09-16T00:00:00+00:00 Abstract</h2> We define a multi-stepped contract ownership interface for more secure contract ownership management. This makes the ownership transfer into 3 distinct steps. With the first 2 steps, performed by the original owner (initiate → confirm) and the remaining 1 step performed by the new owner (accept).</p> We enforce an optional time window between the initiate and confirm stages to give additional room for review, and make ownership key compromise scenarios less fatal.</p> Motivation</h2> Ownership management is crucial in on-chain security and a significant portion of the security assumptions of defi protocols, smart contract wallets and on-chain utilities rely on the contract ownership.</p> The single-step transferOwnership()</code> style ownership mechanism has been in the industry for a long time, (e.g.,ERC-173</a>), and has been used ubiquitously as an industry standard. As the industry evolves and attacks get more sophisticated there is a strong need for a multi-step, time gated ownership management process to enhance the ecosystem’s contract ownership to be more reviewable, stoppable, thorough and secure.</p> The main objective of this standard is to make ownership more secure and handled in a multi-stepped approach that enables the operation to be conducted with more caution and lesser operational mistakes, while being immune to potential scam attacks.</p> Key factors taken into consideration for the standard:</p> Reduce probability of operational mistakes.</li> Foster on-chain reviewal practice for ownership transfer.</li> Ability to rollback ownership transfer, during the transfer process.</li> Simplicity.</li> </ol> 1. Reduce probability of operational mistakes:</strong> The standard makes the ownership transfer stage into 3 different clear steps. Initiation → Confirmation → Acceptance. The owner will have the enforced ability to review the newOwner address secured by the pre-set buffer time. Also to reduce any operational mistakes or possible scams (e.g., address poisoning) the address is required as the parameter in each Initiation & Confirmation stage.</p> 2. Foster on-chain reviewal practice for ownership transfer:</strong> We not only targets this as a contract interface and implementation methodology, but also hopes to foster an ecosystem-level awareness and security practice to thoroughly review, confirm the ownership transfer. The standard helps operators of Smart Contract to review newOwner address on-chain, and further confirm again if the address is indeed correct.</p> 3. Ability to rollback ownership transfer, during the transfer process:</strong> Whether through an operational mistake or private key leak of owner account, or other reasons, the ability to rollback ownership transfer within the time buffer highly increases the security and operational burden.</p> Even in the extreme case of owner private key leak, if the buffer time is set enough, the original owner can earn time to evacuate the funds from the protocol, and possibly prohibit ownership transfer through DoS of ownership (attack → initiate , original owner(defender) → re initiate. which will reset the time back to 0).</p> 4. Simplicity:</strong> MultistepOwnable</code> is targeted to be a simple contract given the diverse use cases and scenarios it could be applied. The process for ownership transfer is concise but thorough enough to allow owners review each step. This is the rationale behind making the ownership transfer time buffer and buffer time update capability optional.</p> Specification</h2> The keywords "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.</p> A multi-step ownable contract MUST implement the following interface:</p> ///</span> @title</span> Multistep Ownership Standard</span></span> interface</span> MultiStepOwnable</span> {</span></span> </span> event</span> OwnershipTransferInitiated</span>(</span>address</span> indexed</span> prevOwner</span>, </span>address</span> indexed</span> newOwner</span>)</span>;</span> </span></span> event</span> OwnershipTransferConfirmed</span>(</span>address</span> indexed</span> prevOwner</span>, </span>address</span> indexed</span> newOwner</span>)</span>;</span></span> event</span> OwnershipTransferred</span>(</span>address</span> indexed</span> prevOwner</span>, </span>address</span> indexed</span> newOwner</span>)</span>;</span></span> </span> ///</span> @dev</span> initiate the ownership transfer. First step of ownership transfer.</span></span> ///</span> moves the newOwner to the preConfirmed stage.</span></span> ///</span> </span></span> ///</span> @param</span> newOwner</span> the address of the new owner of the contract.</span></span> ///</span> stored as preConfirmedOwner.</span></span> function</span> initiateOwnershipTransfer</span>(</span>address</span> newOwner</span>)</span> external</span>;</span></span> </span></span> ///</span> @dev</span> confirm the ownership transfer. Second step of ownership transfer.</span></span> ///</span> confirmation can only be done after the transfer-buffer period from initiation.</span></span> ///</span> newOwner should match with the initiation step's newOwner.</span></span> ///</span> To initiate ownership transfer to a different newOwner, initiation step should be re-conducted.</span></span> ///</span></span> ///</span> @param</span> newOwner</span> the address of the new owner of the contract.</span></span> ///</span> stored as pendingOwner.</span></span> function</span> confirmOwnershipTransfer</span>(</span>address</span> newOwner</span>)</span> external</span>;</span></span> </span></span> ///</span> @dev</span> cancels the pending ownership transfer. Before the final step of ownership transfer (acceptOwnershipTransfer()).</span></span> ///</span> This function should wipe out the pendingOwner.</span></span> ///</span> By calling this function, ownership transfer process is canceled and should be reinitiated from initiateOwnershipTransfer().</span></span> function</span> cancelPendingOwnershipTransfer</span>(</span>)</span> external</span>;</span></span> </span> ///</span> @dev</span> accepts the ownership transfer. Final step of ownership transfer.</span></span> ///</span> This function can only be called by the newOwner that was confirmed in step 2.</span></span> ///</span> The contract should perform access control e.g.,</span></span> ///</span> msg.sender == pendingOwner()</span></span> function</span> acceptOwnershipTransfer</span>(</span>)</span> external</span>;</span></span> </span></span> ///</span> @notice</span> only the address returned by owner() has authority as the owner.</span></span> ///</span> pendingOwner() and preConfirmedOwner() should not possess any</span></span> ///</span> authority/access/right.</span></span> ///</span> @dev</span> returns the owner of the contract</span></span> function</span> owner</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span> </span></span> ///</span> @dev</span> returns the pending owner of the account.</span></span> ///</span> pending owner should not have any authority/access/right.</span></span> function</span> pendingOwner</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span> </span></span> ///</span> @dev</span> returns the pre-confirmed owner of the account.</span></span> ///</span> pre-confirmed owner should not have any authority/access/right.</span></span> function</span> preConfirmedOwner</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span> </span></span> ///</span> @dev</span> returns the ownership transfer buffer time (in seconds).</span></span> ///</span> the buffer is enforced between initiation <> confirmation of ownership transfer. </span></span> ///</span> the standard does not enforce the value range. it is highly recommended to be between 2 <> 14 days.</span></span> function</span> getOwnershipTransferBuffer</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> }</span></span></code></pre> The MultiStepOwnable</code> contract MAY implement the UpdateableOwnershipTransferBuffer</code> interface to enable buffer period modification.</p> The contract MUST update the buffer period with a 2 step approach of initiation (initiateOwnershipBufferUpdate()</code>) and then confirmation (confirmOwnershipBufferUpdate()</code>) after the existing buffer period. The buffer period should be enforced between these 2 function calls. If this behavior is not enforced, the security of ownershipTransferBuffer</code> could break during owner key compromise scenario.</p> ///</span> @title</span> UpdateableOwnershipTransferBuffer. Extension of MultiStepOwnable.</span></span> interface</span> UpdateableOwnershipTransferBuffer</span> {</span></span> </span> ///</span> @dev</span> initiates the update of ownership transfer time buffer.</span></span> function</span> initiateOwnershipBufferUpdate</span>(</span>uint256</span> newBuffer</span>)</span> external</span>;</span></span> </span></span> ///</span> @dev</span> confirms the update of ownership transfer time buffer.</span></span> ///</span> confirmation SHOULD revert if existing time buffer did not pass since</span></span> ///</span> initiation of ownership transfer time buffer.</span></span> function</span> confirmOwnershipBufferUpdate</span>(</span>uint256</span> newBuffer</span>)</span> external</span>;</span></span> }</span></span></code></pre>Rationale</h2> A time buffer for ownership transfer is introduced to foster a process of reviewing the new owner address on-chain. However, this remains an optional behavior to allow flexibility in ownership management. Removing the optional time buffer would be similar to the implementation of Ownable2Step</code> with an additional step for confirmation.</p> </li> Enforcing a time buffer to update the ownership transfer time buffer is crucial for maintaining the security of the MultiStepOwnable</code> contract. When the owner key is compromised, this allows the original owner of the account to be able to DoS and prohibit the ownership transfer to the malicious entity when the ownership transfer buffer is sufficiently long enough.</p> </li> For compatibility with existing ownership mechanisms, the standard is designed to be compatible with the existing ownership mechanism for fetching the owner through owner()</code>.</p> </li> </ol> Backwards Compatibility</h2> TBD </p> Security Considerations</h2> Only owner should be available to call initiateOwnershipTransfer()</code> & confirmOwnershipTransfer()</code> & cancelPendingOwnershipTransfer()</code>.</li> OwnershipTransferBuffer</code> should be set together when owner is set. e.g., constructor()</code>, initialize()</code>.</li> If OwnershipTransferBuffer</code> is set, it should be strictly enforced between initiation and confirmation.</li> Before the new owner performs acceptOwnership()</code>, the original, existing owner should still hold all rights as the owner. Because the owner is still unchanged.</li> </ol> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Minimal Wallet-Managed Auto-Login for SIWE 2025-09-02T00:00:00+00:00 Abstract</h2> Defines a wallet-local allowlist for automatic signing of ERC-4361</a> messages when simple, deterministic match rules succeed. Policies are created and managed only by the wallet/user.</p> Motivation</h2> Users repeatedly sign identical Sign-In With Ethereum (SIWE) messages for trusted apps. A small, explicit match policy enables zero-prompt login without involving apps.</p> Users already get prompted by their wallets if they trust a certain app when they initially connect to it - this flow can also authorize auto-login if applicable.</p> Specification</h2> 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.</p> The term “wallet” refers to wallet user interfaces, regardless of whether mobile, web-based or browser extensions.</p> Overview</h3> Each allow-policy is defined as:</p> {</span></span> "</span>domain</span>"</span>: </span>"</span>example.com</span>"</span>,</span> //</span> exact match to SIWE domain</span></span> "</span>uriPrefix</span>"</span>: </span>"</span>https://example.com/</span>"</span>,</span> //</span> SIWE URI MUST start with this</span></span> "</span>allowedChains</span>"</span>:</span> [</span>1</span>]</span>,</span> //</span> list of allowed chainIds</span></span> "</span>allowedResources</span>"</span>:</span> [</span>"</span>https://example.com/login</span>"</span>]</span>,</span> //</span> exact set match</span></span> "</span>supportsEIP6492</span>"</span>: </span>true</span>,</span> //</span> required for smooth UX when using hardware wallets</span></span> "</span>expiresAt</span>"</span>: </span>1700000000000</span> //</span> UNIX timestamp when this policy expires, or 0 for no expiry</span></span> }</span></span></code></pre>Auto-sign rule</h3> Given a parsed ERC-4361</a> message M</code>, the wallet MAY</strong> auto-sign if</strong>:</p> M.domain == policy.domain</code></li> M.uri</code> startsWith</strong> policy.uriPrefix</code></li> If M.chainId present: M.chainId</code> is in policy.allowedChains</code></li> If policy.allowedResources non-empty: the set of M.resources</code> is a subset of policy.allowedResources</code> (order does not matter); otherwise no resources will be allowed at all</li> If policy.expiresAt</code> is non-zero, the current time is less than policy.expiresAt</code></li> </ol> All other SIWE validations (nonce uniqueness, time validity, signature domain binding) remain as per ERC-4361</a> and MUST be enforced by the wallet.</p> Management of policies</h3> Policies are created, listed, updated, and deleted only</strong> within the wallet UI - wallets decide how much control they want to give to users over this.</p> It’s recommended that each wallet:</p> includes a default list of policies for popular apps</li> automatically creates policies for apps that it considers safe, after the first SIWE signature, with user consent - this implies a different flow where, upon receiving the SIWE message sign request, the wallet will not go through the regular message signing flow, but prompt the user “App X wants to log-in with your account” with a checkbox to “Automatically sign into in the future”</li> </ul> There’s no app-provided hints or headers that influence policy creation.</p> Hardware wallet compatibility and ERC-6492</a></h3> Auto-signing is not viable with hardware wallet accounts, as the user will be prompted without context or expectation to sign the login message.</p> This is why we include the supportsEIP6492</code> property. If it is set to false</code>, the wallet MUST not auto-login if the account's primary signer is a hardware wallet, as the app has no way of verifying a smart contract signature.</p> However, if it's set to true</code>, the wallet MAY perform auto-login as long as 1) it can enable EIP-7702</a> on the account OR the account is a smart account 2) it can authorize a limited-scope session key or delegation just for the auto-login. If said conditions are met, the wallet MAY generate a login signature without prompting the user on their hardware device. That said, enabling EIP-7702 and the session key/delegation will require prompting the user, so it's up to the wallet to walk the user through it. The exact mechanism of how wallets should manage the session key/delegation is out of scope of this ERC, but ERC-7710</a> may be used.</p> RPC method</h3> Wallets MAY implement an RPC method, wallet_getCurrentAutoLoginPolicy</code>, which has no parameters and returns an object describing the current policy for the calling app.</p> {</span></span> //</span> the object that describes the active policy, or null</span></span> "</span>activePolicy</span>"</span>:</span> {</span></span> "</span>domain</span>"</span>:</span> "</span>example.com</span>"</span>,</span></span> "</span>uriPrefix</span>"</span>:</span> "</span>https://example.com/</span>"</span>,</span></span> "</span>allowedChains</span>"</span>:</span> [</span>1</span>]</span>,</span></span> "</span>allowedResources</span>"</span>:</span> [</span>"</span>https://example.com/login</span>"</span>]</span>,</span></span> "</span>supportsEIP6492</span>"</span>:</span> true</span>,</span></span> "</span>expiresAt</span>"</span>:</span> 1700000000000</span></span> }</span>,</span></span> }</span></span></code></pre> The response of this method allows apps to determine whether they can self-initiate login requests without user interaction.</p> If this ERC is disabled in the wallet, or there is no active policy for the calling app, the wallet MUST return null</code> for activePolicy</code>.</p> It's recommended that the wallet returns null</code> if the policy has expired or the app is connected on a non-allowed chain.</p> Rationale</h2> This ERC is designed with minimal modifications to existing apps in mind</li> From a security perspective, it's much easier to "outsource" the job of determining which apps to enable to this policy for to wallets - most wallets already maintain lists of "trusted" apps</li> EIP-712</a> (typed data) is out of scope due to SIWE deciding to build on plain text.</li> </ul> Backwards Compatibility</h2> Backwards compatibility is one of the main goals of this ERC, and it requires no changes to existing apps, building upon ERC-4361</a> as-is.</p> To fully take advantage of this ERC, apps need to self-initiate the login request rather than expecting users to press a log-in button (using wallet_getCurrentAutoLoginPolicy</code>).</p> Reference Implementation</h2> function</span> shouldAutoSign</span>(</span>M</span>,</span> P</span>)</span> {</span></span> if</span> (</span>M</span>.</span>domain</span> !==</span> P</span>.</span>domain</span>)</span> return</span> false</span>;</span></span> if</span> (</span>!</span>M</span>.</span>uri</span>.</span>startsWith</span>(</span>P</span>.</span>uriPrefix</span>)</span>)</span> return</span> false</span>;</span></span> if</span> (</span>!</span>P</span>.</span>allowedChains</span>.</span>includes</span>(</span>M</span>.</span>chainId</span>)</span>)</span> return</span> false</span>;</span></span> if</span> (</span>M</span>.</span>resources</span>)</span> {</span></span> const</span> allowList</span> =</span> P</span>.</span>allowedResources</span> \|\|</span> [</span>]</span></span> if</span> (</span>!</span>M</span>.</span>resources</span>.</span>every</span>(</span>resource</span> =></span> allowList</span>.</span>includes</span>(</span>resource</span>)</span>)</span>)</span> return</span> false</span>;</span></span> }</span></span> if</span> (</span>P</span>.</span>expiresAt</span> !==</span> 0</span> &&</span> Date</span>.</span>now</span>(</span>)</span> >=</span> P</span>.</span>expiresAt</span>)</span> return</span> false</span>;</span></span> //</span> Also enforce standard SIWE validations here.</span></span> return</span> true</span>;</span></span> }</span></span></code></pre>Security Considerations</h2> It’s recommended for Auto login to be OFF by default on wallets’ UIs so that users can explicitly toggle ON for websites they trust.</li> Managing policies it out of scope of this ERC, as most wallets already manage trusted app lists - however, the recommended best practice is to: Include a default list of policies for popular apps</li> Auto-create policies for other apps if the user consents to it</li> </ul> </li> Standard SIWE checks (fresh nonce, correct domain binding, time validity) should still be enforced.</li> uriPrefix</code> should be kept specific (e.g., /login</code>) to avoid over-broad matches.</li> It's recommended to include a top-level setting in each wallet that can disable this ERC.</li> Always match M.domain</code> against the top-level origin of each app, to avoid auto-login working in iframes that are included in a malicious top-level origin.</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Payout Race 2025-08-31T00:00:00+00:00 Abstract</h2> This ERC specifies a small contract surface for a "payout race": a bucket that holds a single payout asset type and transfers the entire bucket to a recipient when a caller pays a fixed required payment</strong> in a configured desired payment asset. The desired payment asset can be ETH or one ERC-20</a>. The payout asset can be ETH or one ERC-20.</p> This ERC is inspired by the Uniswap Foundation's Unistaker</strong> proposal, which introduced the term Payout Race</strong> and motivated this design.</p> Motivation</h2> Many protocols need an ongoing way to convert a continuous stream of value into another asset at or near prevailing market prices. Typical cases include buying back a protocol token using protocol revenue, accumulating a reserve asset, funding incentive budgets, or rebalancing treasuries. Existing patterns have material drawbacks. Integrating an AMM couples outcomes to external liquidity, slippage, and fees, and requires retuning when pool conditions change. General on-chain auctions add operational complexity and higher gas, especially when run continuously.</p> This ERC defines a deterministic, revenue-driven primitive that is analogous to a Dutch auction. Sources of value flow into this contract, filling a "bucket" of purchasable assets. The first caller that supplies the required payment in the desired payment asset receives the entire current balance of the payout token in the bucket. The interface is small, auditable, and easy to compose with upstream controllers that decide when the exchange is economically sound.</p> Specification</h2> The following interface and rules are normative. 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.</p> Definitions</h3> Conforming contract</strong>: Any smart contract that exposes this interface and claims compliance with this ERC. This includes proxies and clones. Requirements in this document apply to the observable runtime behavior of the deployed contract.</p> </li> Payout asset</strong>: Asset dispensed from the bucket. payoutAsset == address(0)</code> means ETH payout.</p> </li> Desired payment asset</strong>: Asset the buyer must pay. Referred to as desiredAsset</code> in the interface. desiredAsset == address(0)</code> means ETH payment.</p> </li> Required payment</strong>: Fixed amount of the desired payment asset (desiredAsset</code>) or ETH that must be provided by the buyer to trigger the payout.</p> </li> </ul> Interface</h3> //</span> SPDX-License-Identifier: CC0-1.0</span></span> pragma</span> solidity</span> ^0.8.24</span>;</span></span> </span> interface</span> IPayoutRace</span> {</span></span> ///</span> @notice</span> Payout asset. address(0) means ETH payout.</span></span> function</span> payoutAsset</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span> </span> ///</span> @notice</span> Desired payment asset. address(0) means ETH payment.</span></span> function</span> desiredAsset</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span> </span> ///</span> @notice</span> Fixed amount required to win the race, denominated in the desired payment asset.</span></span> function</span> requiredPayment</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> </span> ///</span> @notice</span> Destination that receives the buyer's payment.</span></span> function</span> paymentSink</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span> </span> ///</span> @notice</span> Pay the required amount and receive the entire current balance of the payout token to `to`.</span></span> ///</span> @dev</span> Reverts if the computed dispensed amount is zero. Must be safe against reentrancy.</span></span> ///</span> @return</span> dispensed</span> The amount of payout token transferred to `to`.</span></span> function</span> purchase</span>(</span>address</span> to</span>)</span> external</span> payable</span> returns</span> (</span>uint256</span> dispensed</span>)</span>;</span></span> </span> //</span> Admin surface.</span></span> function</span> setRequiredPayment</span>(</span>uint256</span> amount</span>)</span> external</span>;</span></span> function</span> setPaymentSink</span>(</span>address</span> sink</span>)</span> external</span>;</span></span> </span> //</span> Events</span></span> event</span> Purchased</span>(</span>address</span> indexed</span> buyer</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> dispensed</span>, </span>uint256</span> paid</span>)</span>;</span></span> event</span> PaymentConfigUpdated</span>(</span>address</span> desiredAsset</span>, </span>uint256</span> requiredPayment</span>, </span>address</span> sink</span>)</span>;</span></span> }</span></span></code></pre>Required Behavior</h3> Exact required payment.</strong> Callers MUST</strong> provide exactly requiredPayment()</code> in the configured desiredAsset</code> or in ETH to call purchase</code>.</p> </li> Token pairing.</strong> payoutAsset</code> and desiredAsset</code> MUST NOT</strong> both be address(0)</code>. ETH on both sides is disallowed.</p> </li> Desired payment asset immutability.</strong> desiredAsset</code> MUST NOT</strong> change after initialization. A conforming contract MUST NOT</strong> expose any callable setter that can change desiredAsset</code>.</p> </li> Payout asset immutability.</strong> payoutAsset</code> MUST NOT</strong> change after initialization. A conforming contract MUST NOT</strong> expose any callable setter that can change payoutAsset</code>.</p> </li> All-or-nothing dispense.</strong> On purchase</code>, a conforming contract MUST compute the amount to dispense as the live balance of the payout token captured at function entry, before any external calls. The contract MUST transfer exactly this amount to to</code> in a single call and the call MUST revert if this amount is zero.</p> </li> Payment collection.</strong></p> If desiredAsset == address(0)</code>, purchase</code> MUST</strong> require msg.value == requiredPayment()</code> and MUST</strong> forward that ETH to paymentSink()</code>.</li> If desiredAsset != address(0)</code>, purchase</code> MUST</strong> require msg.value == 0</code> and MUST</strong> call transferFrom(msg.sender, paymentSink(), requiredPayment())</code> on desiredAsset</code>.</li> </ul> </li> Admin changes.</strong> A conforming contract MUST</strong> restrict the admin setters to an authorized role and MUST</strong> emit PaymentConfigUpdated</code> when requiredPayment</code> or paymentSink</code> change.</p> </li> </ol> Optional Extensions</h3> Permit for payment</strong>: A conforming contract MAY</strong> expose purchaseWithPermit(...)</code> that accepts EIP-2612</a> permit parameters. If implemented, the function MUST</strong> require desiredAsset != address(0)</code>, MUST</strong> call permit</code> on desiredAsset</code> with the supplied signature, and MUST</strong> collect requiredPayment</code> via transferFrom</code> in the same transaction. The call MUST</strong> revert if desiredAsset</code> does not implement EIP-2612 or if the permit does not yield sufficient allowance.</li> Rescue for unintended assets</strong>: A conforming contract MAY</strong> implement an admin-only rescue</code> function to recover assets that are not the payoutAsset</code> (e.g., unsolicited ERC-20s or ETH sent when payoutAsset</code> is an ERC-20). If provided, the function MUST NOT</strong> transfer the payoutAsset</code>, MUST</strong> emit a Rescued(address token, address to, uint256 amount)</code> event, and MUST</strong> be restricted to an authorized role.</li> </ul> Rationale</h2> A single required payment pairs well with controllers that evaluate when the exchange is economically sound and trigger purchase</code> only when conditions justify it. The onchain primitive then validates the payment and atomically transfers the entire bucket.</li> paymentSink</code> reduces persistent balances in the contract and simplifies audits. Sinks can be treasuries, splitters, or burns.</li> Using the live onchain balance as the source of truth automatically captures rebases and fee-on-transfer mechanics, and keeps the onchain tracking minimized. It also implies that unsolicited transfers to the contract will be included in the next payout, which purchasers may want to account for at the integration level.</li> </ul> Admin Considerations</h3> Access control for admin setters is intentionally unspecified; EIP-173</a> ownership or a role-based pattern is recommended.</p> Some deployments may renounce or restrict admin rights for policy or compliance reasons (for example, renouncing ownership or disabling roles). This ERC does not prescribe any specific mechanism.</p> The reference uses EIP-173</a> style ownership for illustration. Any access control that enforces the Required behavior is acceptable. Deployments may assign distinct roles per setter or make one or more parameters immutable. The specification is agnostic to the mechanism.</p> Parameter Selection and Degenerate Cases</h3> This mechanism works best when value accrues gradually. Large, lumpy deposits can overshoot the required payment threshold and leak value to the first successful caller. Operators should size requiredPayment</code> relative to observed inflow volatility and adjust conservatively. If the payout asset appreciates against the desired payment asset, purchases may stall. If it depreciates, purchases may trigger so frequently that value is lost whenever a large trade pushes the bucket well above the threshold.</p> Changing requiredPayment</code> carries risks. Lowering it can leak value at the moment of change if accrued payout already exceeds the new threshold, since searchers can win a bargain. Raising it can disrupt or bankrupt naive searchers and MEV bots that provide rewards by arbitraging fee collection. Mitigations may include timelocked or scheduled parameter changes, announce windows, caps on per-block deposits, cooldowns after changes, and time-weighted average pricing (TWAP)-based or ratcheted adjustments to requiredPayment</code>.</p> Considered Alternatives: Multi-Asset Sweep</h3> This design could be extended to support multiple payout assets by maintaining an explicit allowlist and, on a successful purchase</code>, sweeping each allowlisted token to the recipient using the same mechanics as the single-asset case.</p> Backwards Compatibility</h2> Compatible with any ERC-20</a>. Wallets and dApps can integrate using standard allowance flows or optional permit</code> helpers.</p> Reference Implementation</h2> //</span> SPDX-License-Identifier: CC0-1.0</span></span> pragma</span> solidity</span> ^0.8.24</span>;</span></span> </span> import</span> {</span>IERC20</span>}</span> from</span> "@openzeppelin/contracts/token/ERC20/IERC20.sol"</span>;</span></span> import</span> {</span>ReentrancyGuard</span>}</span> from</span> "@openzeppelin/contracts/security/ReentrancyGuard.sol"</span>;</span></span> </span> contract</span> PayoutRace</span> is</span> ReentrancyGuard</span> {</span></span> address</span> public</span> immutable</span> payoutAsset</span>;</span> //</span> address(0) for ETH payout</span></span> address</span> public</span> immutable</span> desiredAsset</span>;</span> //</span> address(0) for ETH payment</span></span> uint256</span> public</span> requiredPayment</span>;</span> //</span> fixed amount owed by buyer</span></span> address</span> public</span> paymentSink</span>;</span></span> </span> address</span> private</span> _owner</span>;</span></span> </span> event</span> Purchased</span>(</span>address</span> indexed</span> buyer</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> dispensed</span>, </span>uint256</span> paid</span>)</span>;</span></span> event</span> PaymentConfigUpdated</span>(</span>address</span> desiredAsset</span>, </span>uint256</span> requiredPayment</span>, </span>address</span> sink</span>)</span>;</span></span> event</span> OwnershipTransferred</span>(</span>address</span> indexed</span> oldOwner</span>, </span>address</span> indexed</span> newOwner</span>)</span>;</span></span> </span> modifier</span> onlyOwner</span>(</span>)</span> {</span> require</span>(</span>msg.sender</span> ==</span> _owner</span>,</span> "not owner"</span>)</span>;</span> _</span>;</span> }</span></span> </span> constructor</span>(</span>address</span> _payoutAsset</span>,</span> address</span> _desiredAsset</span>,</span> uint256</span> _required</span>,</span> address</span> _sink</span>)</span> {</span></span> require</span>(</span>!</span>(</span>_payoutAsset </span>==</span> address</span>(</span>0</span>)</span> &&</span> _desiredAsset </span>==</span> address</span>(</span>0</span>)</span>)</span>,</span> "ETH-ETH disallowed"</span>)</span>;</span></span> _owner </span>=</span> msg.sender</span>;</span></span> payoutAsset </span>=</span> _payoutAsset</span>;</span> //</span> zero means ETH payout</span></span> desiredAsset </span>=</span> _desiredAsset</span>;</span> //</span> zero means ETH payment</span></span> requiredPayment </span>=</span> _required</span>;</span></span> paymentSink </span>=</span> _sink</span>;</span></span> emit</span> OwnershipTransferred</span>(</span>address</span>(</span>0</span>)</span>,</span> _owner</span>)</span>;</span></span> emit</span> PaymentConfigUpdated</span>(</span>desiredAsset</span>,</span> requiredPayment</span>,</span> paymentSink</span>)</span>;</span></span> }</span></span> </span> function</span> owner</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span> {</span> return</span> _owner</span>;</span> }</span></span> function</span> transferOwnership</span>(</span>address</span> n</span>)</span> external</span> onlyOwner</span> {</span> _owner </span>=</span> n</span>;</span> emit</span> OwnershipTransferred</span>(</span>msg.sender</span>,</span> n</span>)</span>;</span> }</span></span> </span> ///</span> @notice</span> Accept ETH only when this instance vends ETH</span></span> receive</span>(</span>)</span> external</span> payable</span> {</span></span> require</span>(</span>payoutToken </span>==</span> address</span>(</span>0</span>)</span>,</span> "ETH payout disabled"</span>)</span>;</span></span> }</span></span> </span> //</span> desiredAsset is immutable in this reference; no setter is provided.</span></span> function</span> setRequiredPayment</span>(</span>uint256</span> amount</span>)</span> external</span> onlyOwner</span> {</span> requiredPayment </span>=</span> amount</span>;</span> emit</span> PaymentConfigUpdated</span>(</span>desiredAsset</span>,</span> requiredPayment</span>,</span> paymentSink</span>)</span>;</span> }</span></span> function</span> setPaymentSink</span>(</span>address</span> sink</span>)</span> external</span> onlyOwner</span> {</span> paymentSink </span>=</span> sink</span>;</span> emit</span> PaymentConfigUpdated</span>(</span>desiredAsset</span>,</span> requiredPayment</span>,</span> paymentSink</span>)</span>;</span> }</span></span> </span> function</span> purchase</span>(</span>address</span> to</span>)</span> external</span> payable</span> nonReentrant</span> returns</span> (</span>uint256</span> dispensed</span>)</span> {</span></span> uint256</span> toDispense</span>;</span></span> if</span> (</span>payoutAsset </span>==</span> address</span>(</span>0</span>)</span>)</span> {</span></span> //</span> capture live ETH balance</span></span> toDispense </span>=</span> address</span>(</span>this</span>)</span>.</span>balance</span>;</span></span> }</span> else</span> {</span></span> toDispense </span>=</span> IERC20</span>(</span>payoutAsset</span>)</span>.</span>balanceOf</span>(</span>address</span>(</span>this</span>)</span>)</span>;</span></span> }</span></span> require</span>(</span>toDispense </span>></span> 0</span>,</span> "empty"</span>)</span>;</span></span> </span> //</span> collect payment</span></span> if</span> (</span>desiredAsset </span>==</span> address</span>(</span>0</span>)</span>)</span> {</span></span> require</span>(</span>msg</span>.</span>value </span>==</span> requiredPayment</span>,</span> "bad msg.value"</span>)</span>;</span></span> (</span>bool</span> ok</span>,</span> )</span> =</span> paymentSink</span>.</span>call</span>{</span>value</span>:</span> msg</span>.</span>value</span>}</span>(</span>""</span>)</span>;</span></span> require</span>(</span>ok</span>,</span> "sink transfer failed"</span>)</span>;</span></span> }</span> else</span> {</span></span> require</span>(</span>msg</span>.</span>value </span>==</span> 0</span>,</span> "unexpected ETH"</span>)</span>;</span></span> require</span>(</span>IERC20</span>(</span>desiredAsset</span>)</span>.</span>transferFrom</span>(</span>msg.sender</span>,</span> paymentSink</span>,</span> requiredPayment</span>)</span>,</span> "payment transfer failed"</span>)</span>;</span></span> }</span></span> </span> //</span> payout</span></span> if</span> (</span>payoutAsset </span>==</span> address</span>(</span>0</span>)</span>)</span> {</span></span> (</span>bool</span> ok2</span>,</span> )</span> =</span> to</span>.</span>call</span>{</span>value</span>:</span> toDispense</span>}</span>(</span>""</span>)</span>;</span></span> require</span>(</span>ok2</span>,</span> "ETH payout failed"</span>)</span>;</span></span> }</span> else</span> {</span></span> require</span>(</span>IERC20</span>(</span>payoutAsset</span>)</span>.</span>transfer</span>(</span>to</span>,</span> toDispense</span>)</span>,</span> "token payout failed"</span>)</span>;</span></span> }</span></span> </span> emit</span> Purchased</span>(</span>msg.sender</span>,</span> to</span>,</span> toDispense</span>,</span> requiredPayment</span>)</span>;</span></span> return</span> toDispense</span>;</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> Payout accounting.</strong> The dispensed amount is computed from the live onchain balance of the payout asset. Because ETH-to-ETH is disallowed, there is no ambiguity about subtracting msg.value</code>. Capture the amount to dispense at function entry and use that value for the transfer.</p> </li> Reentrancy and external calls.</strong> Use the Checks-Effects-Interactions pattern and a reentrancy guard. Avoid any external calls before you (a) capture the amount to dispense and (b) forward payment to paymentSink</code>. Do not perform callbacks between collecting payment and completing the payout.</p> </li> Receiver constraints.</strong> The recipient to</code> must be able to receive the asset being dispensed. ETH payouts require a payable fallback; ERC-20</a> payouts require that to</code> is not a contract that reverts on transfer</code>.</p> </li> Payment sink constraints.</strong> The paymentSink</code> must be able to receive the desired payment asset. For ETH payments, paymentSink</code> must be payable. For ERC-20</a> payments, paymentSink</code> must not revert when credited via transferFrom</code>. Using a burn address, splitter, or treasury is acceptable; the specification is agnostic to the mechanism.</p> </li> Unsolicited transfers.</strong> The next payout will include any assets pushed to the contract (e.g., direct ETH sends or ERC-20</a> transfers). Operators should account for this at the integration layer, or front the contract with filters if needed. An optional admin-only rescue</code> for non-payoutAsset</code> assets can mitigate mistakes without affecting conformance.</p> </li> Approvals and permits.</strong> When using ERC-20</a> payments, callers should consider allowance race conditions. If a purchaseWithPermit</code> helper is implemented, verify domain separator, deadline, and nonce handling, and revert on insufficient post‑permit allowance.</p> </li> Admin changes.</strong> Because setters can change requiredPayment</code> or paymentSink</code>, governance should protect these operations. Common mitigations include timelocks, scheduled changes with announcement windows, and immutability for parameters that should never change.</p> </li> Proxies and clones.</strong> Constructors do not run per proxy or minimal clone. Implementations should set payoutAsset</code> and desiredAsset</code> once during initialization and ensure they cannot change afterward. Avoid exposing setters and protect initializers against re-entry or multiple calls.</p> </li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Trustless Agents 2025-08-13T00:00:00+00:00 Abstract</h2> This protocol proposes to use blockchains to discover, choose, and interact with agents across organizational boundaries</strong> without pre-existing trust, thus enabling open-ended agent economies</strong>.</p> Trust models are pluggable and tiered, with security proportional to value at risk, from low-stake tasks like ordering pizza to high-stake tasks like medical diagnosis. Developers can choose from different trust models: reputation systems using client feedback, validation via stake-secured re-execution, zero-knowledge machine learning (zkML) proofs, or trusted execution environment (TEE) oracles.</p> Motivation</h2> Model context protocol (MCP) allows servers to list and offer their capabilities (prompts, resources, tools, and completions), while Agent2Agent (A2A) handles agent authentication, skills advertisement via AgentCards, direct messaging, and complete task-lifecycle orchestration. However, these agent communication protocols don't inherently cover agent discovery and trust.</p> To foster an open, cross-organizational agent economy, we need mechanisms for discovering and trusting agents in untrusted settings. This ERC addresses this need through three lightweight registries, which can be deployed on any L2 or on Mainnet as per-chain singletons:</p> Identity Registry</strong> - A minimal on-chain handle based on ERC-721</a> with URIStorage extension that resolves to an agent's registration file, providing every agent with a portable, censorship-resistant identifier.</p> Reputation Registry</strong> - A standard interface for posting and fetching feedback signals. Scoring and aggregation occur both on-chain (for composability) and off-chain (for sophisticated algorithms), enabling an ecosystem of specialized services for agent scoring, auditor networks, and insurance pools.</p> Validation Registry</strong> - Generic hooks for requesting and recording independent validators checks (e.g. stakers re-running the job, zkML verifiers, TEE oracles, trusted judges).</p> Payments are orthogonal to this protocol and not covered here. However, examples are provided showing how x402 payments</strong> can enrich feedback signals.</p> Specification</h2> 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</a> and RFC 8174</a>.</p> Identity Registry</h3> The Identity Registry uses ERC-721 with the URIStorage extension for agent registration, making all agents immediately browsable and transferable with NFTs-compliant apps</strong>. Each agent is uniquely identified globally by:</p> agentRegistry</em>: A colon-separated string {namespace}:{chainId}:{identityRegistry}</code> (e.g., eip155:1:0x742...</code>) where: namespace</em>: The chain family identifier (eip155</code> for EVM chains)</li> chainId</em>: The blockchain network identifier</li> identityRegistry</em>: The address where the ERC-721 registry contract is deployed</li> </ul> </li> agentId</em>: The ERC-721 tokenId assigned incrementally by the registry</li> </ul> Throughout this document, tokenId</em> in ERC-721 is referred to as agentId</em> and tokenURI</em> in ERC-721 is referred to as agentURI</em>. The owner of the ERC-721 token is the owner of the agent and can transfer ownership or delegate management (e.g., updating the registration file) to operators, as supported by ERC721URIStorage</code>.</p> Agent URI and Agent Registration File</h4> The agentURI</em> MUST resolve to the agent registration file. It MAY use any URI scheme such as ipfs://</code> (e.g., ipfs://cid</code>), https://</code> (e.g., https://example.com/agent3.json</code>), or a base64-encoded data:</code> URI (e.g., data:application/json;base64,eyJ0eXBlIjoi...</code>) for fully on-chain metadata. When the registration uri changes, it can be updated with setAgentURI()</em>.</p> The registration file MUST have the following structure:</p> {</span></span> "</span>type</span>"</span>:</span> "</span>https://eips.ethereum.org/EIPS/eip-8004#registration-v1</span>"</span>,</span></span> "</span>name</span>"</span>:</span> "</span>myAgentName</span>"</span>,</span></span> "</span>description</span>"</span>:</span> "</span>A natural language description of the Agent, which MAY include what it does, how it works, pricing, and interaction methods</span>"</span>,</span></span> "</span>image</span>"</span>:</span> "</span>https://example.com/agentimage.png</span>"</span>,</span></span> "</span>services</span>"</span>:</span> [</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>web</span>"</span>,</span></span> "</span>endpoint</span>"</span>:</span> "</span>https://web.agentxyz.com/</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>A2A</span>"</span>,</span></span> "</span>endpoint</span>"</span>:</span> "</span>https://agent.example/.well-known/agent-card.json</span>"</span>,</span></span> "</span>version</span>"</span>:</span> "</span>0.3.0</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>MCP</span>"</span>,</span></span> "</span>endpoint</span>"</span>:</span> "</span>https://mcp.agent.eth/</span>"</span>,</span></span> "</span>version</span>"</span>:</span> "</span>2025-06-18</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>OASF</span>"</span>,</span></span> "</span>endpoint</span>"</span>:</span> "</span>ipfs://{cid}</span>"</span>,</span></span> "</span>version</span>"</span>:</span> "</span>0.8</span>"</span>,</span> //</span> https://github.com/agntcy/oasf/tree/v0.8.0</span></span> "</span>skills</span>"</span>:</span> [</span>]</span>,</span> //</span> OPTIONAL</span></span> "</span>domains</span>"</span>:</span> [</span>]</span> //</span> OPTIONAL</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>ENS</span>"</span>,</span></span> "</span>endpoint</span>"</span>:</span> "</span>vitalik.eth</span>"</span>,</span></span> "</span>version</span>"</span>:</span> "</span>v1</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>DID</span>"</span>,</span></span> "</span>endpoint</span>"</span>:</span> "</span>did:method:foobar</span>"</span>,</span></span> "</span>version</span>"</span>:</span> "</span>v1</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>email</span>"</span>,</span></span> "</span>endpoint</span>"</span>:</span> "</span>mail@myagent.com</span>"</span></span> }</span></span> ]</span>,</span></span> "</span>x402Support</span>"</span>:</span> false</span>,</span></span> "</span>active</span>"</span>:</span> true</span>,</span></span> "</span>registrations</span>"</span>:</span> [</span></span> {</span></span> "</span>agentId</span>"</span>:</span> 22</span>,</span></span> "</span>agentRegistry</span>"</span>:</span> "</span>{namespace}:{chainId}:{identityRegistry}</span>"</span> //</span> e.g. eip155:1:0x742...</span></span> }</span></span> ]</span>,</span></span> "</span>supportedTrust</span>"</span>:</span> [</span></span> "</span>reputation</span>"</span>,</span></span> "</span>crypto-economic</span>"</span>,</span></span> "</span>tee-attestation</span>"</span></span> ]</span></span> }</span></span></code></pre> The type</em>, name</em>, description</em>, and image</em> fields at the top SHOULD ensure compatibility with ERC-721 apps. The number and type of endpoints</em> are fully customizable, allowing developers to add as many as they wish. The version</em> field in endpoints is a SHOULD, not a MUST.</p> Agents MAY advertise their endpoints, which point to an A2A agent card, an MCP endpoint, an ENS agent name, DIDs, or the agent's wallets on any chain (even chains where the agent is not registered).</p> Endpoint Domain Verification (Optional)</h4> Since endpoints can point to domains not controlled by the agent owner, an agent MAY optionally prove control of an HTTPS endpoint-domain by publishing https://{endpoint-domain}/.well-known/agent-registration.json</code> containing at least a registrations</code> list (or the full agent registration file). Users MAY treat the endpoint-domain as verified if the file is reachable over HTTPS and includes a registrations</code> entry whose agentRegistry</code> and agentId</code> match the on-chain agent; if the endpoint-domain is the same domain that serves the agent’s primary registration file referenced by agentURI</code>, this additional check is not needed because domain control is already demonstrated there.</p> Agents SHOULD have at least one registration (multiple are possible), and all fields in the registration are mandatory. The supportedTrust</em> field is OPTIONAL. If absent or empty, this ERC is used only for discovery, not for trust.</p> On-chain metadata</h4> The registry extends ERC-721 by adding getMetadata(uint256 agentId, string metadataKey)</code> and setMetadata(uint256 agentId, string metadataKey, bytes metadataValue)</code> functions for optional extra on-chain agent metadata:</p> function</span> getMetadata</span>(</span>uint256</span> agentId</span>,</span> string</span> memory</span> metadataKey</span>)</span> external</span> view</span> returns</span> (</span>bytes</span> memory</span>)</span></span> function</span> setMetadata</span>(</span>uint256</span> agentId</span>,</span> string</span> memory</span> metadataKey</span>,</span> bytes</span> memory</span> metadataValue</span>)</span> external</span></span></code></pre> When metadata is set, the following event is emitted:</p> event</span> MetadataSet</span>(</span>uint256</span> indexed</span> agentId</span>, </span>string</span> indexed</span> indexedMetadataKey</span>, </span>string</span> metadataKey</span>, </span>bytes</span> metadataValue</span>)</span></span></code></pre> The key agentWallet</code> is reserved and cannot be set via setMetadata()</code> or during register()</code> (including the metadata array overload). It represents the address where the agent receives payments and is initially set to the owner's address. To change it, the agent owner must prove control of the new wallet by providing a valid EIP-712</a> signature for EOAs or ERC-1271</a> for smart contract wallets—by calling:</p> function</span> setAgentWallet</span>(</span>uint256</span> agentId</span>,</span> address</span> newWallet</span>,</span> uint256</span> deadline</span>,</span> bytes</span> calldata</span> signature</span>)</span> external</span></span></code></pre> To read and clear the currently set wallet, the following functions are exposed:</p> function</span> getAgentWallet</span>(</span>uint256</span> agentId</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span></span> function</span> unsetAgentWallet</span>(</span>uint256</span> agentId</span>)</span> external</span></span></code></pre> When the agent is transferred, agentWallet</code> is automatically cleared (effectively resetting it to the zero address) and must be re-verified by the new owner.</p> Registration</h4> New agents can be minted by calling one of these functions:</p> struct</span> MetadataEntry</span> {</span></span> string</span> metadataKey</span>;</span></span> bytes</span> metadataValue</span>;</span></span> }</span></span> </span> function</span> register</span>(</span>string</span> agentURI</span>,</span> MetadataEntry</span>[</span>]</span> calldata</span> metadata</span>)</span> external</span> returns</span> (</span>uint256</span> agentId</span>)</span></span> </span> function</span> register</span>(</span>string</span> agentURI</span>)</span> external</span> returns</span> (</span>uint256</span> agentId</span>)</span></span> </span> // </span>agentURI</span> is</span> added</span> later</span> with</span> setAgentURI</span>(</span>)</span></span> function</span> register</span>(</span>)</span> external</span> returns</span> (</span>uint256</span> agentId</span>)</span></span></code></pre> This emits one Transfer event, one MetadataSet event for the reserved agentWallet</code> key, one MetadataSet event for each additional metadata entry (if any), and</p> event</span> Registered</span>(</span>uint256</span> indexed</span> agentId</span>, </span>string</span> agentURI</span>, </span>address</span> indexed</span> owner</span>)</span></span></code></pre>Update agentURI</h4> The agentURI can be updated by calling the following function, which emits a URIUpdated event:</p> </span> function</span> setAgentURI</span>(</span>uint256</span> agentId</span>,</span> string</span> calldata</span> newURI</span>)</span> external</span></span> </span> event</span> URIUpdated</span>(</span>uint256</span> indexed</span> agentId</span>,</span> string</span> newURI</span>,</span> address</span> indexed</span> updatedBy</span>)</span></span> </span></code></pre> If the owner wants to store the entire registration file on-chain, the agentURI</em> SHOULD use a base64-encoded data URI rather than a serialized JSON string:</p> data:application/json;base64,eyJ0eXBlIjoi...</span></span></code></pre>Reputation Registry</h3> When the Reputation Registry is deployed, the identityRegistry</em> address is set via initialize(address identityRegistry_)</code> and publicly visible by calling:</p> function</span> getIdentityRegistry</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span> identityRegistry</span>)</span></span></code></pre> The feedback given by a clientAddress</em> to an agent consists of a signed fixed-point value</em> (int128</code>) and its valueDecimals</em> (uint8</code>, 0-18), plus optional tag1</em> and tag2</em> (left to developers' discretion to provide maximum on-chain composability and filtering), an endpoint</em> URI, a file URI pointing to an off-chain JSON containing additional information, and its KECCAK-256 file hash to guarantee integrity. We suggest using IPFS or equivalent services to make feedback easily indexed by subgraphs or similar technologies. For IPFS URIs, the hash is not required. All fields except value</em> and valueDecimals</em> are OPTIONAL, so the off-chain file is not required and can be omitted.</p> Giving Feedback</h4> New feedback can be added by any clientAddress</em> calling:</p> function</span> giveFeedback</span>(</span>uint256</span> agentId</span>,</span> int128</span> value</span>,</span> uint8</span> valueDecimals</span>,</span> string</span> calldata</span> tag1</span>,</span> string</span> calldata</span> tag2</span>,</span> string</span> calldata</span> endpoint</span>,</span> string</span> calldata</span> feedbackURI</span>,</span> bytes32</span> feedbackHash</span>)</span> external</span></span></code></pre> The agentId</em> must be a validly registered agent. The valueDecimals</em> MUST be between 0 and 18. The feedback submitter MUST NOT be the agent owner or an approved operator for agentId</em>. tag1</em>, tag2</em>, endpoint</em>, feedbackURI</em>, and feedbackHash</em> are OPTIONAL.</p> Where provided, feedbackHash</em> is the KECCAK-256 hash (keccak256</code>) of the content referenced by feedbackURI</em>, enabling verifiable integrity for non-content-addressed URIs. For IPFS (or other content-addressed URIs), feedbackHash</em> is OPTIONAL and can be omitted (e.g., set to bytes32(0)</code>).</p> If the procedure succeeds, an event is emitted:</p> event</span> NewFeedback</span>(</span>uint256</span> indexed</span> agentId</span>, </span>address</span> indexed</span> clientAddress</span>, </span>uint64</span> feedbackIndex</span>, </span>int128</span> value</span>, </span>uint8</span> valueDecimals</span>, </span>string</span> indexed</span> indexedTag1</span>, </span>string</span> tag1</span>, </span>string</span> tag2</span>, </span>string</span> endpoint</span>, </span>string</span> feedbackURI</span>, </span>bytes32</span> feedbackHash</span>)</span></span></code></pre> The feedback fields value</em>, valueDecimals</em>, tag1</em>, tag2</em>, and isRevoked</em> are stored in the contract storage along with the feedbackIndex (a 1-indexed counter of feedback submissions that clientAddress</em> has given to agentId</em>). The fields endpoint</em>, feedbackURI</em>, and feedbackHash</em> are emitted but are not stored. This exposes reputation signals to any smart contract, enabling on-chain composability.</p> When the feedback is given by an agent (i.e., the client is an agent), the agent SHOULD use the address set in the on-chain optional agentWallet</code> metadata as the clientAddress, to facilitate reputation aggregation.</p> Examples of value</code> / valueDecimals</code></h4> tag1</th> What it measures</th> Example human value</th> value</code></th> valueDecimals</code></th></tr></thead> starred</code></td> Quality rating (0-100)</td> 87/100</code></td> 87</code></td> 0</code></td></tr> reachable</code></td> Endpoint reachable (binary)</td> true</code></td> 1</code></td> 0</code></td></tr> ownerVerified</code></td> Endpoint owned by agent owner (binary)</td> true</code></td> 1</code></td> 0</code></td></tr> uptime</code></td> Endpoint uptime (%)</td> 99.77%</code></td> 9977</code></td> 2</code></td></tr> successRate</code></td> Endpoint success rate (%)</td> 89%</code></td> 89</code></td> 0</code></td></tr> responseTime</code></td> Response time (ms)</td> 560ms</code></td> 560</code></td> 0</code></td></tr> blocktimeFreshness</code></td> Avg block delay (blocks)</td> 4 blocks</code></td> 4</code></td> 0</code></td></tr> revenues</code></td> Cumulative revenues (e.g., USD)</td> $560</code></td> 560</code></td> 0</code></td></tr> tradingYield</code> (tag2</code> = day, week, month, year</code>)</td> Yield</td> -3,2%</code></td> -32</code></td> 1</code></td></tr> </tbody></table> Off-Chain Feedback File Structure</h4> The OPTIONAL file at the URI could look like:</p> {</span></span> //</span> MUST FIELDS</span></span> "</span>agentRegistry</span>"</span>:</span> "</span>eip155:1:{identityRegistry}</span>"</span>,</span></span> "</span>agentId</span>"</span>:</span> 22</span>,</span></span> "</span>clientAddress</span>"</span>:</span> "</span>eip155:1:{clientAddress}</span>"</span>,</span></span> "</span>createdAt</span>"</span>:</span> "</span>2025-09-23T12:00:00Z</span>"</span>,</span></span> "</span>value</span>"</span>:</span> 100</span>,</span></span> "</span>valueDecimals</span>"</span>:</span> 0</span>,</span></span> </span> //</span> ALL OPTIONAL FIELDS</span></span> "</span>tag1</span>"</span>:</span> "</span>foo</span>"</span>,</span></span> "</span>tag2</span>"</span>:</span> "</span>bar</span>"</span>,</span></span> "</span>endpoint</span>"</span>:</span> "</span>https://agent.example.com/GetPrice</span>"</span>,</span></span> </span> "</span>mcp</span>"</span>:</span> {</span> "</span>tool</span>"</span>:</span> "</span>ToolName</span>"</span> }</span>,</span> //</span> or: { "prompt": "PromptName" } / { "resource": "ResourceName" }</span></span> </span> //</span> A2A: see "Context Identifier Semantics" and Task model in the A2A specification.</span></span> "</span>a2a</span>"</span>:</span> {</span></span> "</span>skills</span>"</span>:</span> [</span>"</span>as-defined-by-A2A</span>"</span>]</span>,</span> //</span> e.g., AgentSkill identifiers</span></span> "</span>contextId</span>"</span>:</span> "</span>as-defined-by-A2A</span>"</span>,</span></span> "</span>taskId</span>"</span>:</span> "</span>as-defined-by-A2A</span>"</span></span> }</span>,</span></span> </span> "</span>oasf</span>"</span>:</span> {</span></span> "</span>skills</span>"</span>:</span> [</span>"</span>as-defined-by-OASF</span>"</span>]</span>,</span></span> "</span>domains</span>"</span>:</span> [</span>"</span>as-defined-by-OASF</span>"</span>]</span></span> }</span>,</span></span> </span></span> "</span>proofOfPayment</span>"</span>:</span> {</span> //</span> this can be used for x402 proof of payment</span></span> "</span>fromAddress</span>"</span>:</span> "</span>0x00...</span>"</span>,</span></span> "</span>toAddress</span>"</span>:</span> "</span>0x00...</span>"</span>,</span></span> "</span>chainId</span>"</span>:</span> "</span>1</span>"</span>,</span></span> "</span>txHash</span>"</span>:</span> "</span>0x00...</span>"</span></span> }</span>,</span></span> </span> //</span> Other fields</span></span> "</span> ... </span>"</span>:</span> {</span> "</span> ... </span>"</span> }</span> //</span> MAY</span></span> }</span></span></code></pre>Revoking Feedback</h4> clientAddress</em> can revoke feedback by calling:</p> function</span> revokeFeedback</span>(</span>uint256</span> agentId</span>,</span> uint64</span> feedbackIndex</span>)</span> external</span></span></code></pre> This emits:</p> event</span> FeedbackRevoked</span>(</span>uint256</span> indexed</span> agentId</span>, </span>address</span> indexed</span> clientAddress</span>, </span>uint64</span> indexed</span> feedbackIndex</span>)</span></span></code></pre>Appending Responses</h4> Anyone (e.g., the agentId</em> showing a refund, any off-chain data intelligence aggregator tagging feedback as spam) can call:</p> function</span> appendResponse</span>(</span>uint256</span> agentId</span>,</span> address</span> clientAddress</span>,</span> uint64</span> feedbackIndex</span>,</span> string</span> calldata</span> responseURI</span>,</span> bytes32</span> responseHash</span>)</span> external</span></span></code></pre> Where responseHash</em> is the KECCAK-256 file hash of the responseURI</em> file content to guarantee integrity. This field is not required for IPFS URIs.</p> This emits:</p> event</span> ResponseAppended</span>(</span>uint256</span> indexed</span> agentId</span>, </span>address</span> indexed</span> clientAddress</span>, </span>uint64</span> feedbackIndex</span>, </span>address</span> indexed</span> responder</span>, </span>string</span> responseURI</span>, </span>bytes32</span> responseHash</span>)</span></span></code></pre>Read Functions</h4> function</span> getSummary</span>(</span>uint256</span> agentId</span>,</span> address</span>[</span>]</span> calldata</span> clientAddresses</span>,</span> string</span> tag1</span>,</span> string</span> tag2</span>)</span> external</span> view</span> returns</span> (</span>uint64</span> count</span>,</span> int128</span> summaryValue</span>,</span> uint8</span> summaryValueDecimals</span>)</span></span> // </span>agentId</span> and</span> clientAddresses</span> are</span> mandatory</span>;</span> tag1 and tag2 are optional filters</span>.</span></span> //</span> clientAddresses MUST be provided (non-empty); results without filtering by clientAddresses are subject to Sybil/spam attacks. See Security Considerations for details</span></span> </span> function</span> readFeedback</span>(</span>uint256</span> agentId</span>,</span> address</span> clientAddress</span>,</span> uint64</span> feedbackIndex</span>)</span> external</span> view</span> returns</span> (</span>int128</span> value</span>,</span> uint8</span> valueDecimals</span>,</span> string</span> tag1</span>,</span> string</span> tag2</span>,</span> bool</span> isRevoked</span>)</span></span> </span> function</span> readAllFeedback</span>(</span>uint256</span> agentId</span>,</span> address</span>[</span>]</span> calldata</span> clientAddresses</span>,</span> string</span> tag1</span>,</span> string</span> tag2</span>,</span> bool</span> includeRevoked</span>)</span> external</span> view</span> returns</span> (</span>address</span>[</span>]</span> memory</span> clients</span>,</span> uint64</span>[</span>]</span> memory</span> feedbackIndexes</span>,</span> int128</span>[</span>]</span> memory</span> values</span>,</span> uint8</span>[</span>]</span> memory</span> valueDecimals</span>,</span> string</span>[</span>]</span> memory</span> tag1s</span>,</span> string</span>[</span>]</span> memory</span> tag2s</span>,</span> bool</span>[</span>]</span> memory</span> revokedStatuses</span>)</span></span> // </span>agentId</span> is</span> the</span> only</span> mandatory</span> parameter</span>;</span> others are optional filters</span>.</span> Revoked feedback are omitted by default</span>.</span></span> </span> function</span> getResponseCount</span>(</span>uint256</span> agentId</span>,</span> address</span> clientAddress</span>,</span> uint64</span> feedbackIndex</span>,</span> address</span>[</span>]</span> responders</span>)</span> external</span> view</span> returns</span> (</span>uint64</span> count</span>)</span></span> // </span>agentId</span> is</span> the</span> only</span> mandatory</span> parameter</span>;</span> others are optional filters</span>.</span></span> </span> function</span> getClients</span>(</span>uint256</span> agentId</span>)</span> external</span> view</span> returns</span> (</span>address</span>[</span>]</span> memory</span>)</span></span> </span> function</span> getLastIndex</span>(</span>uint256</span> agentId</span>,</span> address</span> clientAddress</span>)</span> external</span> view</span> returns</span> (</span>uint64</span>)</span></span></code></pre> We expect reputation systems around reviewers/clientAddresses to emerge. While simple filtering by reviewer (useful to mitigate spam) and by tag are enabled on-chain, more complex reputation aggregation will happen off-chain</strong>.</p> Validation Registry</h3> This registry enables agents to request verification of their work and allows validator smart contracts to provide responses that can be tracked on-chain</strong>. Validator smart contracts could use, for example, stake-secured inference re-execution, zkML verifiers or TEE oracles to validate or reject requests.</p> When the Validation Registry is deployed, the identityRegistry</em> address is set via initialize(address identityRegistry_)</code> and is visible by calling getIdentityRegistry()</code>, as described above.</p> Validation Request</h4> Agents request validation by calling:</p> function</span> validationRequest</span>(</span>address</span> validatorAddress</span>,</span> uint256</span> agentId</span>,</span> string</span> requestURI</span>,</span> bytes32</span> requestHash</span>)</span> external</span></span></code></pre> This function MUST be called by the owner or operator of agentId</em>. The requestURI</em> points to off-chain data containing all information needed for the validator to validate, including inputs and outputs needed for the verification. The requestHash</em> is a commitment to this data (keccak256</code> of the request payload) and identifies the request. All other fields are mandatory.</p> A ValidationRequest event is emitted:</p> event</span> ValidationRequest</span>(</span>address</span> indexed</span> validatorAddress</span>, </span>uint256</span> indexed</span> agentId</span>, </span>string</span> requestURI</span>, </span>bytes32</span> indexed</span> requestHash</span>)</span></span></code></pre>Validation Response</h4> Validators respond by calling:</p> function</span> validationResponse</span>(</span>bytes32</span> requestHash</span>,</span> uint8</span> response</span>,</span> string</span> responseURI</span>,</span> bytes32</span> responseHash</span>,</span> string</span> tag</span>)</span> external</span></span></code></pre> Only requestHash</em> and response</em> are mandatory; responseURI</em>, responseHash</em> and tag</em> are optional. This function MUST be called by the validatorAddress</em> specified in the original request. The response</em> is a value between 0 and 100, which can be used as binary (0 for failed, 100 for passed) or with intermediate values for validations with a spectrum of outcomes. The optional responseURI</em> points to off-chain evidence or audit of the validation, responseHash</em> is its commitment (in case the resource is not on IPFS), while tag</em> allows for custom categorization or additional data.</p> validationResponse() can be called multiple times for the same requestHash</em>, enabling use cases like progressive validation states (e.g., “soft finality” and “hard finality” using tag</em>) or updates to validation status.</p> Upon successful execution, a ValidationResponse</em> event is emitted with all function parameters:</p> event</span> ValidationResponse</span>(</span>address</span> indexed</span> validatorAddress</span>, </span>uint256</span> indexed</span> agentId</span>, </span>bytes32</span> indexed</span> requestHash</span>, </span>uint8</span> response</span>, </span>string</span> responseURI</span>, </span>bytes32</span> responseHash</span>, </span>string</span> tag</span>)</span></span></code></pre> The contract stores requestHash</em>, validatorAddress</em>, agentId</em>, response</em>, responseHash</em>, lastUpdate</em>, and tag</em> for on-chain querying and composability.</p> Read Functions</h4> function</span> getValidationStatus</span>(</span>bytes32</span> requestHash</span>)</span> external</span> view</span> returns</span> (</span>address</span> validatorAddress</span>,</span> uint256</span> agentId</span>,</span> uint8</span> response</span>,</span> bytes32</span> responseHash</span>,</span> string</span> tag</span>,</span> uint256</span> lastUpdate</span>)</span></span> </span> //</span>Returns</span> aggregated</span> validation</span> statistics</span> for</span> an</span> agent</span>.</span> agentId</span> is</span> the</span> only</span> mandatory</span> parameter</span>;</span> validatorAddresses and tag are optional filters</span></span> function</span> getSummary</span>(</span>uint256</span> agentId</span>,</span> address</span>[</span>]</span> calldata</span> validatorAddresses</span>,</span> string</span> tag</span>)</span> external</span> view</span> returns</span> (</span>uint64</span> count</span>,</span> uint8</span> averageResponse</span>)</span></span> </span> function</span> getAgentValidations</span>(</span>uint256</span> agentId</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>[</span>]</span> memory</span> requestHashes</span>)</span></span> </span> function</span> getValidatorRequests</span>(</span>address</span> validatorAddress</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>[</span>]</span> memory</span> requestHashes</span>)</span></span></code></pre> Incentives and slashing related to validation are managed by the specific validation protocol and are outside the scope of this registry.</p> Rationale</h2> Agent communication protocols</strong>: MCP and A2A are popular, and other protocols could emerge. For this reason, this protocol links from the blockchain to a flexible registration file including a list where endpoints can be added at will, combining AI primitives (MCP, A2A) and Web3 primitives such as wallet addresses, DIDs, and ENS names.</li> Feedback</strong>: The protocol combines the leverage of nomenclature already established by A2A (such as tasks and skills) and MCP (such as tools and prompts) with complete flexibility in the feedback signal structure.</li> Gas Sponsorship</strong>: Since clients don't need to be registered anymore, any application can implement frictionless feedback leveraging EIP-7702</a>.</li> Indexing</strong>: Since feedback data is saved on-chain and we suggest using IPFS for full data, it's easy to leverage subgraphs to create indexers and improve UX.</li> Deployment</strong>: We expect the registries to be deployed with singletons per chain. Note that an agent registered and receiving feedback on chain A can still operate and transact on other chains. Agents can also be registered on multiple chains if desired.</li> </ul> Security Considerations</h2> Sybil attacks are possible, inflating the reputation of fake agents. The protocol's contribution is to make signals public and use the same schema. We expect many players to build reputation systems, for example, trusting or giving reputation to reviewers (and therefore filtering by reviewer, as the protocol already enables).</li> On-chain pointers and hashes cannot be deleted, ensuring audit trail integrity</li> Validator incentives and slashing are managed by specific validation protocols</li> While this ERC cryptographically ensures the registration file corresponds to the on-chain agent, it cannot cryptographically guarantee that advertised capabilities are functional and non-malicious. The three trust models (reputation, validation, and TEE attestation) are designed to support this verification need</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Simplified Payment Verification Gateway 2025-08-07T00:00:00+00:00 Abstract</h2> Introduce a singleton contract for on-chain verification of transactions that happened on Bitcoin. The contract is available at "0xTODO" , acting as a trustless Simplified Payment Verification (SPV) gateway where anyone can submit Bitcoin block headers. The gateway maintains the mainchain of blocks and allows the existence of Bitcoin transactions to be verified via Merkle proofs.</p> Motivation</h2> Ethereum's long-term mission has always been to revolutionize the financial world through decentralization, trustlessness, and programmable value enabled by smart contracts. Many great use cases have been discovered so far, including the renaissance of Decentralized Finance (DeFi), emergence of Real-World Assets (RWA), and rise of privacy-preserving protocols.</p> However, one gem has been unreachable to date -- Bitcoin. Due to its extremely constrained programmability, one can only hold and transfer bitcoins in a trustless manner. This EIP tries to expand its capabilities by laying a solid foundation for bitcoins to be also used in various EVM-based DeFi protocols, unlocking a whole new trillion-dollar market.</p> The singleton SPV gateway contract defined in this proposal acts as a trustless one-way bridge between Bitcoin and Ethereum, already enabling use cases such as using native</em> BTC as a lending collateral for stablecoin loans. Moreover, with the recent breakthroughs in the BitVM technology, the full-fledged, ownerless two-way bridge may soon become a reality, powering the permissionless and wrapless issuance of BTC on Ethereum.</p> Specification</h2> 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.</p> General</h3> Bitcoin Block Header Structure</h4> In Bitcoin, each block contains a header, which has a fixed size of 80 bytes and follows the following structure:</p> Field</th> Size</th> Format</th> Description</th></tr></thead> Version</td> 4 bytes</td> little-endian</td> The version number of the block.</td></tr> Previous Block</td> 32 bytes</td> natural byte order</td> The block hash of a previous block this block is building on top of.</td></tr> Merkle Root</td> 32 bytes</td> natural byte order</td> A fingerprint for all of the transactions included in the block.</td></tr> Time</td> 4 bytes</td> little-endian</td> The current time as a Unix timestamp.</td></tr> Bits</td> 4 bytes</td> little-endian</td> A compact representation of the current target (difficulty).</td></tr> Nonce</td> 4 bytes</td> little-endian</td> A 32-bit number which miners compute to find a valid block hash.</td></tr> </tbody></table> The fields within the block header are sequentially ordered as presented in the table above.</p> Difficulty Adjustment Mechanism</h4> Bitcoin's Proof-of-Work (PoW) consensus mechanism has a probabilistic finality, thus relying on a dynamic difficulty target</strong> adjustments. The target's initial value is set to 0x00000000ffff0000000000000000000000000000000000000000000000000000</code>, which also serves as the minimum difficulty threshold.</p> The target</code> is recalculated every 2016 blocks (approximately every two weeks), a period commonly referred to as a difficulty adjustment period</strong>.</p> The expected duration for each adjustment period is 1,209,600 seconds (2016 blocks * 10 minutes/block). The new target</code> value is derived by multiplying the current target</code> by the ratio of the actual time taken to mine the preceding 2016 blocks to this expected duration.</p> To prevent drastic difficulty fluctuations, the adjustment multiplier is capped at 4x</code> and 1/4x</code> respectively.</p> Block Header Validation Rules</h4> For a Bitcoin block header to be considered valid and accepted into the chain, it MUST adhere to the following consensus rules:</p> Chain Cohesion</strong>: The Previous Block</code> hash field MUST reference the hash of a valid block that is present in the set of existing block headers.</p> </li> Timestamp Rules</strong>:</p> The Time</code> field MUST be strictly greater than the Median Time Past (MTP)</strong> of the previous 11 blocks.</li> The Time</code> field MUST NOT be more than 2 hours in the future relative to the validating node's network-adjusted time.</li> </ul> </li> PoW Constraint</strong>: When the block header is hashed twice using SHA256</code>, the resulting hash MUST be less than or equal to the current target</code> value, as derived from the difficulty adjustment mechanism.</p> </li> </ol> Transaction Inclusion Structure</h4> Every Bitcoin block header has a field Merkle Root</code> that corresponds to a Merkle root of the transactions tree included in this block.</p> The transactions Merkle tree is built recursively performing double SHA256</code> hash on each pair of sibling nodes, where the tree leaves are the double SHA256</code> hash of the raw transaction bytes. In case the node has no siblings, the hashing is done over the node with itself.</p> To verify the transaction inclusion into the block, one SHOULD build the Merkle root from the ground up and compare it with the Merkle Root</code> stored in the selected block header. The corresponding Merkle path and hashing direction bits can be obtained and processed by querying a Bitcoin full node.</p> Mainchain Definition</h4> Bitcoin's mainchain</strong> is determined not just by its length, but by the greatest cumulative PoW</strong> among all valid competing chains. This cumulative work represents the total computational effort expended to mine all blocks within a specific chain.</p> The work contributed by a single block is inversely proportional to its target</code> value. Specifically, the work of a block can be calculated as (2256 - 1) / (target + 1)</code>. The target</code> value for a block is derived from its Bits</code> field, where the first byte encodes the required left hand bit shift, and the other three bytes the actual target value.</p> The total cumulative work of a chain is the sum of the work values of all blocks within that chain. A block is considered part of the mainchain if it extends the chain with the greatest cumulative PoW.</p> SPV Gateway</h3> The SPVGateway</code> contract MUST provide a permissionless mechanism for its initialization. This mechanism MUST allow for the submission of a valid Bitcoin block header, its corresponding block height, and the cumulative PoW up to that block, without requiring special permissions.</p> The SPVGateway</code> MUST implement the following interface:</p> pragma</span> solidity</span> ^0.8.0</span>;</span></span> </span> /</span></span> * </span>@notice</span> Interface for a Simplified Payment Verification Gateway contract.</span></span> /</span></span> interface</span> ISPVGateway</span> {</span></span> /</span></span> </span>@notice</span> Represents the essential data contained within a Bitcoin block header</span></span> * </span>@param</span> prevBlockHash</span> The hash of the previous block</span></span> * </span>@param</span> merkleRoot</span> The Merkle root of the transactions in the block</span></span> * </span>@param</span> version</span> The block version number</span></span> * </span>@param</span> time</span> The block's timestamp</span></span> * </span>@param</span> nonce</span> The nonce used for mining</span></span> * </span>@param</span> bits</span> The encoded difficulty target for the block</span></span> /</span></span> struct</span> BlockHeaderData</span> {</span></span> bytes32</span> prevBlockHash</span>;</span></span> bytes32</span> merkleRoot</span>;</span></span> uint32</span> version</span>;</span></span> uint32</span> time</span>;</span></span> uint32</span> nonce</span>;</span></span> bytes4</span> bits</span>;</span></span> }</span></span> </span> /</span></span> MUST be emitted whenever the mainchain head </span>changed</span> (e.g. in the `addBlockHeader`, `addBlockHeaderBatch` functions)</span></span> /</span></span> event</span> MainchainHeadUpdated</span>(</span></span> uint64</span> indexed</span> newMainchainHeight</span>,</span></span> bytes32</span> indexed</span> newMainchainHead</span></span> )</span>;</span></span> </span> /</span></span> MUST be emitted whenever the new block header added to the SPV contract state</span></span> * (e.g. in the `addBlockHeader`, `addBlockHeaderBatch` functions)</span></span> /</span></span> event</span> BlockHeaderAdded</span>(</span>uint64</span> indexed</span> blockHeight</span>, </span>bytes32</span> indexed</span> blockHash</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> Adds a single raw block header to the contract.</span></span> * The block header is validated before being added</span></span> * </span>@param</span> blockHeaderRaw</span> The raw block header bytes</span></span> /</span></span> function</span> addBlockHeader</span>(</span>bytes</span> calldata</span> blockHeaderRaw</span>)</span> external</span>;</span></span> </span> /</span></span> </span>@notice</span> OPTIONAL Function that adds a batch of the block headers to the contract.</span></span> * Each block header is validated and added sequentially</span></span> * </span>@param</span> blockHeaderRawArray</span> An array of raw block header bytes</span></span> /</span></span> function</span> addBlockHeaderBatch</span>(</span>bytes</span>[</span>]</span> calldata</span> blockHeaderRawArray</span>)</span> external</span>;</span></span> </span> /</span></span> </span>@notice</span> Checks that given txId is included in the specified block with a minimum number of confirmations.</span></span> * </span>@param</span> merkleProof</span> The array of hashes used to build the Merkle root</span></span> * </span>@param</span> blockHash</span> The hash of the block in which to verify the transaction</span></span> * </span>@param</span> txId</span> The transaction id to verify</span></span> * </span>@param</span> txIndex</span> The index of the transaction in the block's Merkle tree</span></span> * </span>@param</span> minConfirmationsCount</span> The minimum number of confirmations required for the block</span></span> * </span>@return</span> True</span> if the txId is present in the block's Merkle tree and the block has at least minConfirmationsCount confirmations, false otherwise</span></span> /</span></span> function</span> checkTxInclusion</span>(</span></span> bytes32</span>[</span>]</span> memory</span> merkleProof</span>,</span></span> bytes32</span> blockHash</span>,</span></span> bytes32</span> txId</span>,</span></span> uint256</span> txIndex</span>,</span></span> uint256</span> minConfirmationsCount</span></span> )</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> Returns the hash of the current mainchain head.</span></span> * This represents the highest block on the most accumulated work chain</span></span> * </span>@return</span> The</span> hash of the mainchain head</span></span> /</span></span> function</span> getMainchainHead</span>(</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> Returns the height of the current mainchain head.</span></span> * This represents the highest block number on the most accumulated work chain</span></span> * </span>@return</span> The</span> height of the mainchain head</span></span> /</span></span> function</span> getMainchainHeight</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint64</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> Returns the block header data for a given block hash.</span></span> * </span>@param</span> blockHash</span> The hash of the block</span></span> * </span>@return</span> The</span> block header data</span></span> /</span></span> function</span> getBlockHeader</span>(</span>bytes32</span> blockHash</span>)</span> external</span> view</span> returns</span> (</span>BlockHeaderData</span> memory</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> Returns the current status of a given block</span></span> * </span>@param</span> blockHash</span> The hash of the block to check</span></span> * </span>@return</span> isInMainchain</span> True if the block is in the mainchain, false otherwise</span></span> * </span>@return</span> confirmationsCount</span> The number of blocks that have been mined on top of </span></span> * the given block if the block is in the mainchain</span></span> /</span></span> function</span> getBlockStatus</span>(</span>bytes32</span> blockHash</span>)</span> external</span> view</span> returns</span> (</span>bool</span>,</span> uint64</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> Returns the Merkle root of a given block hash.</span></span> * This function retrieves the Merkle root from the stored block header data</span></span> * </span>@param</span> blockHash</span> The hash of the block</span></span> * </span>@return</span> The</span> Merkle root of the block</span></span> /</span></span> function</span> getBlockMerkleRoot</span>(</span>bytes32</span> blockHash</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> Returns the block height for a given block hash</span></span> * This function retrieves the height at which the block exists in the chain</span></span> * </span>@param</span> blockHash</span> The hash of the block</span></span> * </span>@return</span> The</span> height of the block</span></span> /</span></span> function</span> getBlockHeight</span>(</span>bytes32</span> blockHash</span>)</span> external</span> view</span> returns</span> (</span>uint64</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> Returns the block hash for a given block height.</span></span> * This function retrieves the hash of the block from the mainchain at the specified height</span></span> * </span>@param</span> blockHeight</span> The height of the block</span></span> * </span>@return</span> The</span> hash of the block</span></span> /</span></span> function</span> getBlockHash</span>(</span>uint64</span> blockHeight</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> Checks if a block exists in the contract's storage.</span></span> * This function verifies the presence of a block by its hash</span></span> * </span>@param</span> blockHash</span> The hash of the block to check</span></span> * </span>@return</span> True</span> if the block exists, false otherwise</span></span> /</span></span> function</span> blockExists</span>(</span>bytes32</span> blockHash</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> }</span></span></code></pre> All fields within the BlockHeaderData</code> struct MUST be converted to big-endian byte order for internal representation and processing within the smart contract.</p> The addBlockHeader</code> function MUST perform the following checks:</p> Validate that the submitted raw block header has a fixed size of 80 bytes.</li> Enforce all block header validation rules as specified in the "Block Header Validation Rules" section.</li> Integrate the new block header into the known chain by calculating its cumulative PoW and managing potential chain reorganizations as defined in the "Mainchain Definition" section.</li> Emit a BlockHeaderAdded</code> event upon successful addition of the block header.</li> Emit a MainchainHeadUpdated</code> event if the mainchain was updated.</li> </ul> The checkTxInclusion</code> function MUST perform the following steps:</p> Check whether the provided blockHash</code> is part of the mainchain and ensure its number of confirmations is at least equal to the minConfirmationsCount</code> parameter. If any of these checks fail, the function MUST return false</code>.</li> Using the provided merkleProof</code>, txId</code>, and txIndex</code>, the function MUST compute the Merkle root.</li> The computed Merkle root MUST be compared against the Merkle Root</code> field stored within the block header identified by blockHash</code>.</li> If the computed Merkle root matches the stored Merkle Root</code>, the function MUST return true</code>. Otherwise, it MUST return false</code>.</li> </ul> Rationale</h2> During the design process of the SPVGateway</code> contract, several decisions have been made that require clarification. The following initialization options of the smart contract were considered:</p> Hardcoding the Bitcoin genesis block:</strong> This approach is the simplest for contract deployment as it embeds the initial state directly in the code. While offering absolute trustlessness of the starting point, it limits availability, as the full sync of the gateway would cost around ~100 ETH at the gas price of 1 gwei.</li> Initialization from an arbitrary block height by trusting provided cumulative work and height:</strong> Currently, the gateway adopts this method as its initialization mechanism. While implying trust in the initial submitted values, it's a common practice for bootstrapping light clients and can be secured via off-chain mechanisms for initial validation (e.g., community-verified checkpoints).</li> Initialization with Zero-Knowledge Proof (ZKP) for historical correctness:</strong> This advanced method involves proving the entire history of Bitcoin up to a specific block using ZKP.</li> </ol> Upon submitting the raw block header, the gateway expects the BlockHeaderData</code> fields to be converted to big-endian byte order. This is required to maintain EVM's efficiency, which is contrary to Bitcoin's native little-endian integer serialization.</p> There are no "finality" rules in the SPVGateway</code> contract. The determination of such is left to consuming protocols, allowing individual definition to meet required security thresholds.</p> The inclusion of an OPTIONAL addBlockHeaderBatch</code> function offers significant gas optimizations. For batches exceeding 11 blocks, MTP can be calculated using timestamps from calldata</code>, substantially reducing storage reads and transaction costs.</p> Backwards Compatibility</h2> This EIP is fully backwards compatible.</p> Deployment Method</h3> TBD</p> Test Cases</h2> TBD</p> Reference Implementation</h2> A reference implementation of the SPVGateway</code> contract can be found here</a>.</p> TargetsHelper</code></a> is a supporting library that provides utility functions for working with Bitcoin's difficulty targets. It includes methods to convert the Bits</code> field from a block header to the corresponding target</code> value and vice versa, as well as functions to calculate the new difficulty target during adjustment periods.</p> Please note that the reference implementation depends on the @openzeppelin/contracts v5.2.0</code>, @solarity/solidity-lib v3.2.0</code> and solady v0.1.23</code>.</p> </blockquote> Security Considerations</h2> Among potential security issues, the following can be noted:</p> The security of the SPVGateway</code> is directly dependent on the security of Bitcoin's underlying PoW consensus. A successful 51% attack on the Bitcoin network would allow an attacker to submit fraudulent block headers that would be accepted by the contract, compromising its state.</p> The block header validation rules require a Bitcoin node to check that the newly created block is not more than 2 hours ahead of the node's network-adjusted time. This check is impossible to implement on the SPVGateway</code> smart contract, hence it is omitted.</p> Unlike other blockchain systems with deterministic finality, Bitcoin's consensus is probabilistic. The SPVGateway</code> contract SHOULD be designed to handle chain reorganizations of arbitrary depth, but it cannot prevent them. As a result, transactions included in a block may not be permanently final. All dApps and protocols relying on this contract MUST implement their own security policies to determine a sufficient number of block confirmations before a transaction is considered "final" for their specific use case.</p> While the addBlockHeader</code> function is permissionless and validates each new header cryptographically, the contract's initial state (its starting block header, height, and cumulative PoW) is a point of trust. The integrity of the entire chain history within the contract is built upon the correctness of this initial data. Although the EIP's design allows for flexible bootstrapping, the responsibility for verifying the initial state falls on the community and the dApps that choose to use a specific deployment of the SPVGateway</code>.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Agent Coordination Framework 2025-08-02T00:00:00+00:00 Abstract</h2> ERC-8001</a> defines a minimal, single-chain primitive for multi-party agent coordination</strong>. An initiator posts an intent and each participant provides a verifiable acceptance attestation. Once the required set of acceptances is present and fresh, the intent is executable. The standard specifies typed data, lifecycle, mandatory events, and verification rules compatible with EIP-712</a>, ERC-1271</a>, EIP-2098</a>, and EIP-5267</a>.</p> ERC-8001</a> omits privacy, reputation, threshold policies, bonding, and cross-chain semantics. Those are expected as optional modules that reference this specification.</p> Motivation</h2> Agents in DeFi/MEV/Web3 Gaming and Agentic Commerce often need to act together without a trusted coordinator. Existing intent standards (e.g., ERC-7521</a>, ERC-7683</a>) define single-initiator flows and do not specify multi-party agreement.</p> ERC-8001</a> specifies the smallest on-chain primitive for that gap: an initiator's EIP-712</a> intent plus per-participant EIP-712</a>/EIP-1271</a> acceptances. The intent becomes executable only when the required set of acceptances is present and unexpired. Canonical (sorted-unique) participant lists and standard typed data provide replay safety and wallet compatibility. Privacy, thresholds, bonding, and cross-chain are left to modules.</p> Specification</h2> The keywords “MUST”, “SHOULD”, and “MAY” are to be interpreted as described in RFC 2119 and RFC 8174.</p> Implementations MUST expose the following canonical status codes for getCoordinationStatus</code>:</p> Status Codes</h3> Implementations MUST use the canonical enum defined below:</p> enum</span> Status</span> {</span> None</span>,</span> Proposed</span>,</span> Ready</span>,</span> Executed</span>,</span> Cancelled</span>,</span> Expired</span> }</span></span></code></pre> None</code> = default zero state (intent not found)</p> </li> Proposed</code> = intent proposed, not all acceptances yet</p> </li> Ready</code> = all participants have accepted, intent executable</p> </li> Executed</code> = intent successfully executed</p> </li> Cancelled</code> = intent explicitly cancelled</p> </li> Expired</code> = intent expired before execution</p> </li> </ul> Overview</h3> This ERC specifies:</p> A canonicalised EIP-712 domain for agent coordination,</li> Typed data structures (AgentIntent</code>, CoordinationPayload</code>, AcceptanceAttestation</code>),</li> Deterministic hashing rules,</li> A standard interface (IAgentCoordination</code>),</li> Lifecycle semantics (propose → accept → execute/cancel),</li> Error surface and status codes.</li> </ul> EIP-712 Domain</h3> Implementations MUST use the following EIP-712 domain:</p> {name: "ERC-8001", version: "1", chainId, verifyingContract}</span></span></code></pre> Implementations SHOULD expose the domain via ERC-5267</a>.</p> Primary Types</h3> struct</span> AgentIntent</span> {</span></span> bytes32</span> payloadHash</span>;</span> //</span> keccak256(CoordinationPayload)</span></span> uint64</span> expiry</span>;</span> //</span> unix seconds; MUST be > block.timestamp at propose</span></span> uint64</span> nonce</span>;</span> //</span> per-agent nonce; MUST be > agentNonces[agentId]</span></span> address</span> agentId</span>;</span> //</span> initiator and signer of the intent</span></span> bytes32</span> coordinationType</span>;</span> //</span> domain-specific type id, e.g. keccak256("MEV_SANDWICH_COORD_V1")</span></span> uint256</span> coordinationValue</span>;</span> //</span> informational in Core; modules MAY bind value</span></span> address</span>[</span>]</span> participants</span>;</span> //</span> unique, ascending; MUST include agentId</span></span> }</span></span> </span> struct</span> CoordinationPayload</span> {</span></span> bytes32</span> version</span>;</span> //</span> payload format id</span></span> bytes32</span> coordinationType</span>;</span> //</span> MUST equal AgentIntent.coordinationType</span></span> bytes</span> coordinationData</span>;</span> //</span> opaque to Core</span></span> bytes32</span> conditionsHash</span>;</span> //</span> domain-specific</span></span> uint256</span> timestamp</span>;</span> //</span> creation time (informational)</span></span> bytes</span> metadata</span>;</span> //</span> optional</span></span> }</span></span> </span> struct</span> AcceptanceAttestation</span> {</span></span> bytes32</span> intentHash</span>;</span> //</span> getIntentHash(intent)</span></span> address</span> participant</span>;</span> //</span> signer</span></span> uint64</span> nonce</span>;</span> //</span> optional in Core; see Nonces</span></span> uint64</span> expiry</span>;</span> //</span> acceptance validity; MUST be > now at accept and execute</span></span> bytes32</span> conditionsHash</span>;</span> //</span> participant constraints</span></span> bytes</span> signature</span>;</span> //</span> ECDSA (65 or 64 bytes) or ERC-1271</span></span> }</span></span></code></pre>Typed Data Hashes</h3> </span> bytes32</span> constant</span> AGENT_INTENT_TYPEHASH </span>=</span> keccak256</span>(</span></span> "AgentIntent(bytes32 payloadHash,uint64 expiry,uint64 nonce,address agentId,bytes32 coordinationType,uint256 coordinationValue,address[] participants)"</span></span> )</span>;</span></span> </span> bytes32</span> constant</span> ACCEPTANCE_TYPEHASH </span>=</span> keccak256</span>(</span></span> //</span> Field names MUST exactly match the Solidity struct.</span></span> "AcceptanceAttestation(bytes32 intentHash,address participant,uint64 nonce,uint64 expiry,bytes32 conditionsHash)"</span></span> )</span>;</span></span> </span> //</span> participants MUST be unique and strictly ascending by uint160(address).</span></span> function</span> _participantsHash</span>(</span>address</span>[</span>]</span> memory</span> ps</span>)</span> internal</span> pure</span> returns</span> (</span>bytes32</span>)</span> {</span></span> return</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>ps</span>)</span>)</span>;</span></span> }</span></span> </span> function</span> _agentIntentStructHash</span>(</span>AgentIntent</span> calldata</span> i</span>)</span> internal</span> pure</span> returns</span> (</span>bytes32</span>)</span> {</span></span> return</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span> AGENT_INTENT_TYPEHASH</span>,</span></span> i</span>.</span>payloadHash</span>,</span></span> i</span>.</span>expiry</span>,</span></span> i</span>.</span>nonce</span>,</span></span> i</span>.</span>agentId</span>,</span></span> i</span>.</span>coordinationType</span>,</span></span> i</span>.</span>coordinationValue</span>,</span></span> _participantsHash</span>(</span>i</span>.</span>participants</span>)</span></span> )</span>)</span>;</span></span> }</span></span> </span> //</span> Full EIP-712 digest for the initiator’s signature.</span></span> function</span> _agentIntentDigest</span>(</span>bytes32</span> domainSeparator</span>,</span> AgentIntent</span> calldata</span> i</span>)</span> internal</span> pure</span> returns</span> (</span>bytes32</span>)</span> {</span></span> return</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>"\x19\x01"</span>,</span> domainSeparator</span>,</span> _agentIntentStructHash</span>(</span>i</span>)</span>)</span>)</span>;</span></span> }</span></span> </span> function</span> _acceptanceStructHash</span>(</span>AcceptanceAttestation</span> calldata</span> a</span>)</span> internal</span> pure</span> returns</span> (</span>bytes32</span>)</span> {</span></span> //</span> a.intentHash MUST be the AgentIntent struct hash, not the digest.</span></span> return</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span> ACCEPTANCE_TYPEHASH</span>,</span></span> a</span>.</span>intentHash</span>,</span></span> a</span>.</span>participant</span>,</span></span> a</span>.</span>nonce</span>,</span></span> a</span>.</span>expiry</span>,</span></span> a</span>.</span>conditionsHash</span></span> )</span>)</span>;</span></span> }</span></span> </span> function</span> _acceptanceDigest</span>(</span>bytes32</span> domainSeparator</span>,</span> AcceptanceAttestation</span> calldata</span> a</span>)</span> internal</span> pure</span> returns</span> (</span>bytes32</span>)</span> {</span></span> return</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>"\x19\x01"</span>,</span> domainSeparator</span>,</span> _acceptanceStructHash</span>(</span>a</span>)</span>)</span>)</span>;</span></span> }</span></span> </span></code></pre> Computation (normative):</p> participantsHash </span>=</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>participants</span>)</span>)</span>;</span> //</span> sorted unique</span></span> intentStructHash </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span> AGENT_INTENT_TYPEHASH</span>,</span></span> payloadHash</span>,</span> expiry</span>,</span> nonce</span>,</span> agentId</span>,</span> coordinationType</span>,</span> coordinationValue</span>,</span> participantsHash</span></span> )</span>)</span>;</span></span> intentDigest </span>=</span> keccak256</span>(</span>"\x19\x01"</span> \|\|</span> domainSeparator </span>\|\|</span> intentStructHash</span>)</span>;</span></span> </span></code></pre> Clarifications (normative):</p> getIntentHash(intent)</code> MUST return intentStructHash</code> (struct hash), not the full digest.</li> AcceptanceAttestation.intentHash</code> MUST be that struct hash.</li> Each acceptance is signed over its own EIP-712 digest that includes this field.</li> participants</code> MUST be strictly ascending by uint160(address)</code> and deduplicated.</li> </ul> Interface</h3> Implementations MUST</strong> expose the following interface and events.</p> interface</span> IAgentCoordination</span> {</span></span> event</span> CoordinationProposed</span>(</span>bytes32</span> indexed</span> intentHash</span>, </span>address</span> indexed</span> proposer</span>, </span>bytes32</span> coordinationType</span>, </span>uint256</span> participantCount</span>, </span>uint256</span> coordinationValue</span>)</span>;</span></span> event</span> CoordinationAccepted</span>(</span>bytes32</span> indexed</span> intentHash</span>, </span>address</span> indexed</span> participant</span>, </span>bytes32</span> acceptanceHash</span>, </span>uint256</span> acceptedCount</span>, </span>uint256</span> requiredCount</span>)</span>;</span></span> event</span> CoordinationExecuted</span>(</span>bytes32</span> indexed</span> intentHash</span>, </span>address</span> indexed</span> executor</span>, </span>bool</span> success</span>, </span>uint256</span> gasUsed</span>, </span>bytes</span> result</span>)</span>;</span></span> event</span> CoordinationCancelled</span>(</span>bytes32</span> indexed</span> intentHash</span>, </span>address</span> indexed</span> canceller</span>, </span>string</span> reason</span>, </span>uint8</span> finalStatus</span>)</span>;</span></span> </span> function</span> proposeCoordination</span>(</span>AgentIntent</span> calldata</span> intent</span>,</span> bytes</span> calldata</span> signature</span>,</span> CoordinationPayload</span> calldata</span> payload</span>)</span> external</span> returns</span> (</span>bytes32</span> intentHash</span>)</span>;</span></span> function</span> acceptCoordination</span>(</span>bytes32</span> intentHash</span>,</span> AcceptanceAttestation</span> calldata</span> attestation</span>)</span> external</span> returns</span> (</span>bool</span> allAccepted</span>)</span>;</span></span> function</span> executeCoordination</span>(</span>bytes32</span> intentHash</span>,</span> CoordinationPayload</span> calldata</span> payload</span>,</span> bytes</span> calldata</span> executionData</span>)</span> external</span> returns</span> (</span>bool</span> success</span>,</span> bytes</span> memory</span> result</span>)</span>;</span></span> function</span> cancelCoordination</span>(</span>bytes32</span> intentHash</span>,</span> string</span> calldata</span> reason</span>)</span> external</span>;</span></span> </span> function</span> getCoordinationStatus</span>(</span>bytes32</span> intentHash</span>)</span> external</span> view</span> returns</span> (</span>Status</span> status</span>,</span> address</span> proposer</span>,</span> address</span>[</span>]</span> memory</span> participants</span>,</span> address</span>[</span>]</span> memory</span> acceptedBy</span>,</span> uint256</span> expiry</span>)</span>;</span></span> function</span> getRequiredAcceptances</span>(</span>bytes32</span> intentHash</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> function</span> getAgentNonce</span>(</span>address</span> agent</span>)</span> external</span> view</span> returns</span> (</span>uint64</span>)</span>;</span></span> }</span></span></code></pre>Semantics</h3> The functions defined in this specification MUST exhibit the following externally observable behaviours. This standard does NOT prescribe storage layout, execution model, or internal mechanisms.</p> proposeCoordination</code></h4> proposeCoordination</code> MUST revert if:</p> the signature does not validate the supplied AgentIntent</code> under the ERC-8001 EIP-712 domain;</li> intent.expiry <= block.timestamp</code>;</li> intent.nonce</code> is not strictly greater than getAgentNonce(intent.agentId)</code>;</li> participants</code> is not strictly ascending and unique;</li> intent.agentId</code> is not included in the participants list.</li> </ul> If valid:</p> CoordinationProposed</code> MUST be emitted;</li> getCoordinationStatus</code> MUST report Proposed</code>;</li> getAgentNonce(intent.agentId)</code> MUST equal the supplied nonce;</li> getRequiredAcceptances(intentHash)</code> MUST equal the number of participants.</li> </ul> acceptCoordination</code></h4> acceptCoordination</code> MUST revert if:</p> the intent does not exist or has expired;</li> the caller is not listed as a participant;</li> the participant has already accepted;</li> the attestation signature does not validate under the ERC-8001 domain;</li> attestation.expiry <= block.timestamp</code>.</li> </ul> If valid:</p> CoordinationAccepted</code> MUST be emitted;</li> the participant MUST appear in the acceptedBy</code> list returned by getCoordinationStatus</code>;</li> if all participants have accepted: the function MUST return true</code>;</li> status MUST be Ready</code>.</li> </ul> </li> </ul> Otherwise the function MUST return false</code>.</p> executeCoordination</code></h4> executeCoordination</code> MUST revert if:</p> the intent is not in Ready</code> state;</li> intent.expiry <= block.timestamp</code>;</li> any acceptance has expired;</li> the supplied payload does not hash to payloadHash</code>.</li> </ul> If valid:</p> the implementation MUST attempt execution of the behaviour represented by executionData</code>;</li> the function MUST return (success, result)</code>;</li> CoordinationExecuted</code> MUST be emitted;</li> getCoordinationStatus</code> MUST report Executed</code>.</li> </ul> cancelCoordination</code></h4> If the intent has not expired, only the proposer MUST be permitted to cancel.</li> After expiry, any caller MUST be permitted to cancel.</li> </ul> On success:</p> CoordinationCancelled</code> MUST be emitted;</li> status MUST be Cancelled</code>.</li> </ul> getCoordinationStatus</code></h4> getCoordinationStatus(intentHash)</code> MUST return:</p> None</code> if the intent does not exist;</li> Proposed</code> if not all participants have accepted and the intent has not expired;</li> Ready</code> if all participants have accepted and expiries have not elapsed;</li> Executed</code> if execution has occurred;</li> Cancelled</code> if cancellation has occurred;</li> Expired</code> if the intent has expired and was not executed or cancelled.</li> </ul> Nonces</h4> getAgentNonce(agent)</code> MUST increase for every valid new intent.</li> proposeCoordination</code> MUST reject nonces not strictly greater than the stored nonce.</li> Acceptance-level nonces MAY be implemented; if so, they MUST be strictly monotonic per participant.</li> </ul> Errors</h3> Implementations SHOULD revert with descriptive custom errors (or equivalent revert strings) for the following baseline conditions, and MAY define additional errors for domain-specific modules (e.g. slashing, reputation, or privacy conditions):</p> Expired intent</li> Bad signature</li> Non-participant</li> Duplicate acceptance</li> Acceptance expired at execute</li> Payload hash mismatch</li> </ul> error</span> ERC8001_NotProposer</span>(</span>)</span>;</span></span> error</span> ERC8001_ExpiredIntent</span>(</span>)</span>;</span></span> error</span> ERC8001_ExpiredAcceptance</span>(</span>address</span> participant</span>)</span>;</span></span> error</span> ERC8001_BadSignature</span>(</span>)</span>;</span></span> error</span> ERC8001_NotParticipant</span>(</span>)</span>;</span></span> error</span> ERC8001_DuplicateAcceptance</span>(</span>)</span>;</span></span> error</span> ERC8001_ParticipantsNotCanonical</span>(</span>)</span>;</span></span> error</span> ERC8001_NonceTooLow</span>(</span>)</span>;</span></span> error</span> ERC8001_PayloadHashMismatch</span>(</span>)</span>;</span></span> error</span> ERC8001_NotReady</span>(</span>)</span>;</span></span></code></pre>Rationale</h2> Sorted participant lists remove hash malleability and allow off-chain deduplication.</li> Separation of intent and acceptance allows off-chain collation and a single on-chain check.</li> Keeping ERC-8001</a> single-chain avoids coupling to bridge semantics and keeps the primitive audit-friendly.</li> Wallet friendliness: EIP-712 arrays let signers see actual participant addresses.</li> </ul> Backwards Compatibility</h2> ERC-8001</a> introduces a new interface. It is compatible with EOA and contract wallets via ECDSA and ERC-1271. It does not modify existing standards.</p> Reference Implementation</h2> A permissive reference implementation is provided in contracts/AgentCoordination.sol</code></a>. It uses a minimal ECDSA helper and supports ERC-1271 signers. It enforces participant canonicalisation, intent nonces, acceptance freshness, and all-participants policy.</p> Security Considerations</h2> Replay</strong>: EIP-712 domain binding and monotonic nonces prevent cross-contract replay.</li> Malleability</strong>: Low-s enforcement and 64/65-byte signature support are required.</li> Equivocation</strong>: A participant can sign conflicting intents. Mitigate with module-level slashing or reputation.</li> Liveness</strong>: Enforce TTL on both intent and acceptances. Executors should ensure enough time remains.</li> MEV</strong>: If coordinationData</code> reveals strategy, use a Privacy module with commit-reveal or encryption.</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Purpose-Bound ERC-20 with Conditional Unlock 2025-07-29T00:00:00+00:00 Abstract</h2> This ERC extends the concept introduced in ERC-7291</a> by enabling ERC-20</a>-compatible tokens to carry multi-condition unlocking constraints, combining temporal, identity, and usage restrictions into a programmable structure. It aims to support controlled disbursement of tokens where funds are only accessible under predefined, auditable, and verifiable conditions.</p> Motivation</h2> ERC-7291 introduced purpose-bound money by restricting how and where tokens can be spent. However, many real-world applications require multiple conditions to be satisfied simultaneously before tokens can be used. Examples include:</p> Scholarships requiring the recipient to be KYC-verified, under 25 years of age, and registered at a university.</li> NGO aid to be used only for food and medicine, after a specific unlock date.</li> Payroll tokens that unlock monthly and only for whitelisted vendors (e.g., banks, healthcare providers).</li> </ul> This proposal generalizes and formalizes such use cases by layering unlocking conditions on top of the ERC-20 standard.</p> Specification</h2> 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.</p> Interface</h3> The IPurposeBoundERC20</code> interface defines the standard for programmable token transfers that are conditional. Each transfer, referred to as a purpose binding</em>, includes:</p> A recipient</code> and amount</code>.</li> A set of UnlockCondition</code> objects, each consisting of a conditionType</code> (like "TIME"</code>, "KYC"</code>, or "WHITELIST"</code>) and conditionData</code> used to evaluate the condition.</li> An optional expiry</code> timestamp after which the transfer can no longer be claimed.</li> </ul> The interface provides the following functions:</p> bindPurpose(...)</code>: Locks a specified amount of tokens to a recipient with defined conditions.</li> claim(...)</code>: Allows the recipient to claim the tokens once all conditions are fulfilled.</li> isUnlocked(...)</code>: Returns whether all associated conditions have been satisfied.</li> </ul> This enables flexible, composable transfer mechanisms for various use cases including compliance, grants, payroll, and more.</p> pragma</span> solidity</span> 0.8.23</span>;</span></span> </span> interface</span> IPurposeBoundERC20</span> {</span></span> struct</span> UnlockCondition</span> {</span></span> bytes32</span> conditionType</span>;</span> //</span> e.g., "TIME", "KYC", "WHITELIST"</span></span> bytes</span> conditionData</span>;</span> //</span> e.g., timestamp, Merkle root, etc.</span></span> }</span></span> </span> function</span> bindPurpose</span>(</span></span> address</span> recipient</span>,</span></span> uint256</span> amount</span>,</span></span> UnlockCondition</span>[</span>]</span> calldata</span> conditions</span>,</span></span> uint256</span> expiry</span></span> )</span> external</span> returns</span> (</span>bytes32</span> bindingId</span>)</span>;</span></span> </span> function</span> claim</span>(</span>bytes32</span> bindingId</span>)</span> external</span>;</span></span> </span> function</span> isUnlocked</span>(</span>bytes32</span> bindingId</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> }</span></span></code></pre>Rationale</h2> Flexibility: Conditions are modular and extensible.</p> Composability: Can be integrated into DAOs, payroll, education, and compliance tokens.</p> Security: Off-chain verification (e.g., KYC) backed by on-chain proofs (e.g., Merkle roots).</p> Reference Implementation</h2> pragma</span> solidity</span> 0.8.23</span>;</span></span> </span> ///</span> @title</span> Reference Implementation - Purpose-Bound ERC20 with Multi-Condition Unlocking</span></span> ///</span> @notice</span> Implements IPurposeBoundERC20 with conditionType mapping to on-chain checkers.</span></span> </span> import</span> "@openzeppelin/contracts/token/ERC20/ERC20.sol"</span>;</span></span> import</span> "./IPurposeBoundERC20.sol"</span>;</span></span> </span> ///</span> @dev</span> Interface for pluggable condition checker contracts</span></span> interface</span> IConditionChecker</span> {</span></span> function</span> isConditionMet</span>(</span>address</span> recipient</span>,</span> bytes</span> calldata</span> conditionData</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> }</span></span> </span> ///</span> @title</span> PurposeBoundERC20 Implementation</span></span> contract</span> PurposeBoundERC20</span> is</span> ERC20</span>, </span>IPurposeBoundERC20</span> {</span></span> struct</span> StoredBinding</span> {</span></span> address</span> recipient</span>;</span></span> uint256</span> amount</span>;</span></span> UnlockCondition</span>[</span>]</span> conditions</span>;</span></span> bool</span> claimed</span>;</span></span> uint256</span> expiry</span>;</span></span> }</span></span> </span> ///</span> @dev</span> Maps conditionType → on-chain checker contract</span></span> mapping</span>(</span>bytes32</span> =></span> address</span>)</span> public</span> conditionResolvers</span>;</span></span> </span> ///</span> @dev</span> Maps bindingId → locked transfer</span></span> mapping</span>(</span>bytes32</span> =></span> StoredBinding</span>)</span> public</span> boundTransfers</span>;</span></span> </span> event</span> PurposeBound</span>(</span>bytes32</span> indexed</span> bindingId</span>, </span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> amount</span>)</span>;</span></span> event</span> Claimed</span>(</span>bytes32</span> indexed</span> bindingId</span>, </span>address</span> indexed</span> recipient</span>)</span>;</span></span> </span> constructor</span>(</span>string</span> memory</span> name_</span>,</span> string</span> memory</span> symbol_</span>)</span> ERC20</span>(</span>name_, symbol_) </span>{</span></span> _mint</span>(</span>msg.sender</span>,</span> 1_000_000</span> ether</span>)</span>;</span> //</span> for demo purposes</span></span> }</span></span> </span> ///</span> @notice</span> Admin can register or update condition checkers for condition types</span></span> function</span> setConditionResolver</span>(</span>bytes32</span> conditionType</span>,</span> address</span> checker</span>)</span> external</span> {</span></span> //</span> For demo purposes: public function. In production: onlyOwner or AccessControl.</span></span> conditionResolvers</span>[</span>conditionType</span>]</span> =</span> checker</span>;</span></span> }</span></span> </span> ///</span> @inheritdoc</span> IPurposeBoundERC20</span></span> function</span> bindPurpose</span>(</span></span> address</span> recipient</span>,</span></span> uint256</span> amount</span>,</span></span> UnlockCondition</span>[</span>]</span> calldata</span> conditions</span>,</span></span> uint256</span> expiry</span></span> )</span> external</span> override</span> returns</span> (</span>bytes32</span> bindingId</span>)</span> {</span></span> require</span>(</span>recipient </span>!=</span> address</span>(</span>0</span>)</span>,</span> "Invalid recipient"</span>)</span>;</span></span> require</span>(</span>amount </span>></span> 0</span>,</span> "Invalid amount"</span>)</span>;</span></span> </span> bindingId </span>=</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>msg.sender</span>,</span> recipient</span>,</span> amount</span>,</span> conditions</span>,</span> expiry</span>,</span> block</span>.</span>timestamp</span>)</span>)</span>;</span></span> StoredBinding </span>storage</span> stored </span>=</span> boundTransfers</span>[</span>bindingId</span>]</span>;</span></span> require</span>(</span>stored</span>.</span>amount </span>==</span> 0</span>,</span> "Binding exists"</span>)</span>;</span></span> </span> _transfer</span>(</span>msg.sender</span>,</span> address</span>(</span>this</span>)</span>,</span> amount</span>)</span>;</span></span> </span> for</span> (</span>uint</span> i </span>=</span> 0</span>;</span> i </span><</span> conditions</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span> stored</span>.</span>conditions</span>.</span>push</span>(</span>conditions</span>[</span>i</span>]</span>)</span>;</span></span> }</span></span> </span> stored</span>.</span>recipient </span>=</span> recipient</span>;</span></span> stored</span>.</span>amount </span>=</span> amount</span>;</span></span> stored</span>.</span>expiry </span>=</span> expiry</span>;</span></span> </span> emit</span> PurposeBound</span>(</span>bindingId</span>,</span> msg.sender</span>,</span> recipient</span>,</span> amount</span>)</span>;</span></span> }</span></span> </span> ///</span> @inheritdoc</span> IPurposeBoundERC20</span></span> function</span> isUnlocked</span>(</span>bytes32</span> bindingId</span>)</span> public</span> view</span> override</span> returns</span> (</span>bool</span>)</span> {</span></span> StoredBinding </span>storage</span> binding </span>=</span> boundTransfers</span>[</span>bindingId</span>]</span>;</span></span> if</span> (</span>binding</span>.</span>claimed</span>)</span> return</span> false</span>;</span></span> if</span> (</span>binding</span>.</span>expiry </span>></span> 0</span> &&</span> block</span>.</span>timestamp </span>></span> binding</span>.</span>expiry</span>)</span> return</span> false</span>;</span></span> </span> for</span> (</span>uint</span> i </span>=</span> 0</span>;</span> i </span><</span> binding</span>.</span>conditions</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span> UnlockCondition </span>storage</span> cond </span>=</span> binding</span>.</span>conditions</span>[</span>i</span>]</span>;</span></span> address</span> checker </span>=</span> conditionResolvers</span>[</span>cond</span>.</span>conditionType</span>]</span>;</span></span> require</span>(</span>checker </span>!=</span> address</span>(</span>0</span>)</span>,</span> "Checker not set"</span>)</span>;</span></span> if</span> (</span>!</span>IConditionChecker</span>(</span>checker</span>)</span>.</span>isConditionMet</span>(</span>binding</span>.</span>recipient</span>,</span> cond</span>.</span>conditionData</span>)</span>)</span> {</span></span> return</span> false</span>;</span></span> }</span></span> }</span></span> </span> return</span> true</span>;</span></span> }</span></span> </span> ///</span> @inheritdoc</span> IPurposeBoundERC20</span></span> function</span> claim</span>(</span>bytes32</span> bindingId</span>)</span> external</span> override</span> {</span></span> StoredBinding </span>storage</span> binding </span>=</span> boundTransfers</span>[</span>bindingId</span>]</span>;</span></span> require</span>(</span>msg.sender</span> ==</span> binding</span>.</span>recipient</span>,</span> "Not recipient"</span>)</span>;</span></span> require</span>(</span>!</span>binding</span>.</span>claimed</span>,</span> "Already claimed"</span>)</span>;</span></span> require</span>(</span>isUnlocked</span>(</span>bindingId</span>)</span>,</span> "Conditions not met"</span>)</span>;</span></span> </span> binding</span>.</span>claimed </span>=</span> true</span>;</span></span> _transfer</span>(</span>address</span>(</span>this</span>)</span>,</span> binding</span>.</span>recipient</span>,</span> binding</span>.</span>amount</span>)</span>;</span></span> </span> emit</span> Claimed</span>(</span>bindingId</span>,</span> binding</span>.</span>recipient</span>)</span>;</span></span> }</span></span> }</span></span> </span> ///</span> @dev</span> Example of Time-Based Condition Checker</span></span> contract</span> TimeConditionChecker</span> is</span> IConditionChecker</span> {</span></span> function</span> isConditionMet</span>(</span>address</span>,</span> bytes</span> calldata</span> conditionData</span>)</span> external</span> view</span> override</span> returns</span> (</span>bool</span>)</span> {</span></span> uint256</span> unlockTime </span>=</span> abi</span>.</span>decode</span>(</span>conditionData</span>,</span> (</span>uint256</span>)</span>)</span>;</span></span> return</span> block</span>.</span>timestamp </span>></span>=</span> unlockTime</span>;</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> Condition-checking mechanisms (e.g., Merkle roots, timestamps) must be secure against tampering.</p> The claim()</code> function must ensure atomic verification of all conditions.</p> Replay attacks must be mitigated using unique binding IDs and expiration fields.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Verifiable ML Model Inference (ZKML) 2025-07-23T00:00:00+00:00 Abstract</h2> This ERC standardizes how smart contracts reference machine-learning (ML) models and accept zero-knowledge attestations of their inferences. It defines a registry that issues a modelId</code> for a ModelCommitment</code>, hashes of the model’s weights/architecture, proving circuit/AIR, and verifying key, along with a proofSystemId</code> for the proving system, and exposes discoverability via ERC-165</a>. A verifier interface provides verifyInference(modelId, inputCommitment, output, proof)</code>: it retrieves the model commitment, dispatches verification to the declared proof system, and reverts on any mismatch or invalid proof; success implies validity and emits InferenceVerified</code>. Inputs are bound by domain-separated commitments (nonceable for replay protection), outputs are ABI-encoded bytes whose schema can be application-defined or additionally committed on-chain, and proof systems (e.g., Groth16/Plonk/STARK) are pluggable without ABI changes. An optional extension persists verified inference records to enable auditability and deterministic settlement.</p> Motivation</h2> Smart contracts can’t run large ML models, and they can’t trust an oracle’s claim about a model’s output. Today, projects either (1) trust a centralized server, (2) cripple models to fit on-chain, or (3) rely on social committees. None provide cryptographic assurance.</p> Zero-knowledge ML (ZKML) fixes the trust gap by letting a prover show—succinctly and privately—that a specific model, with specific inputs, produced a specific output. But without a shared interface, every dApp/verifier pair is bespoke: different ABIs, different registry schemas, poor composability.</p> This ERC standardizes that on-chain boundary:</p> Registry: publish immutable commitments to model weights/architecture/circuits so callers know exactly which model they’re referencing.</li> Verifier: a uniform function to validate inference proofs, independent of proof system (Groth16, Plonk, STARKs, …).</li> </ul> Benefits include:</p> Trustless, composable “AI oracles” for DeFi risk, prediction markets, insurance, etc.</li> Protection of proprietary models and private inputs while still guaranteeing correctness.</li> Deterministic, dispute-free settlement for complex computations.</li> Lower integration and audit overhead via consistent events, structs, and revert semantics.</li> Future-proofing as proving systems evolve—only implementations change, not integrators.</li> Clear security expectations (e.g., nonce usage to prevent replays) baked into the spec.</li> </ul> In short, this ERC turns verifiable ML inference into a reusable primitive—doing for AI outputs what ERC-20</a>/ERC-721</a> did for assets.</p> Specification</h2> 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</a> and RFC 8174</a>.</p> Terminology & IDs</h3> Model Commitment: A bundle of hashes that ties together the model’s weights, architecture, proving circuit/Algebraic intermediate representation (AIR), and verifying key.</li> modelId</code> (uint256</code>): A unique identifier returned by the registry upon model registration.</li> inputCommitment</code> (bytes32</code>): A hash commitment to all private inputs (and any declared public inputs) for an inference. Implementations MUST domain-separate and SHOULD include a nonce/salt when single-use or non-deterministic behavior is possible.</li> output</code> (bytes</code>): ABI-encoded public outputs of the inference. Consumers MUST agree on its schema and MAY validate it via an outputCommitment (not included in the minimal interface).</li> proof</code> (bytes</code>): The ZK proof blob.</li> proofSystemId</code> (bytes4</code>): Identifier of the proving system + curve + version used by the circuit.</li> </ul> proofSystemId</code> MUST equal the first four bytes of:</p> bytes4(keccak256(abi.encodePacked(<canonical-proof-system-name-and-version>)))</code></p> Where <canonical-proof-system-name-and-version></code> is a lowercase, hyphen-separated string, e.g.:</p> "groth16-bn254-v1"</li> "plonk-bn254-v2"</li> "stark-airfoo-v1"</li> </ul> This method ensures deterministic, collision-resistant identifiers across implementations.</p> Interfaces</h3> ZKML Registry</h4> //</span> SPDX-License-Identifier: CC0-1.0</span></span> pragma</span> solidity</span> ^0.8.20</span>;</span></span> </span> interface</span> IERCZKMLRegistry</span> /</span> is IERC165 </span>/</span> {</span></span> struct</span> ModelCommitment</span> {</span></span> bytes32</span> modelHash</span>;</span> //</span> weights + architecture hash</span></span> bytes32</span> circuitHash</span>;</span> //</span> arithmetic circuit / AIR hash</span></span> bytes32</span> vkHash</span>;</span> //</span> verifying key hash</span></span> bytes4</span> proofSystemId</span>;</span> //</span> keccak-based identifier</span></span> string</span> uri</span>;</span> //</span> optional off-chain metadata (IPFS/HTTP)</span></span> }</span></span> </span> event</span> ModelRegistered</span>(</span></span> uint256</span> indexed</span> modelId</span>,</span></span> address</span> indexed</span> owner</span>,</span></span> ModelCommitment</span> commitment</span></span> )</span>;</span></span> </span> event</span> ModelUpdated</span>(</span></span> uint256</span> indexed</span> modelId</span>,</span></span> ModelCommitment</span> oldCommitment</span>,</span></span> ModelCommitment</span> newCommitment</span></span> )</span>;</span></span> </span> event</span> ModelDeprecated</span>(</span>uint256</span> indexed</span> modelId</span>)</span>;</span></span> </span> error</span> ModelNotFound</span>(</span>uint256</span> modelId</span>)</span>;</span></span> error</span> NotModelOwner</span>(</span>uint256</span> modelId</span>,</span> address</span> caller</span>)</span>;</span></span> error</span> ModelDeprecated</span>(</span>uint256</span> modelId</span>)</span>;</span></span> </span> function</span> registerModel</span>(</span>ModelCommitment</span> calldata</span> commitment</span>)</span></span> external</span></span> returns</span> (</span>uint256</span> modelId</span>)</span>;</span></span> </span> function</span> updateModel</span>(</span>uint256</span> modelId</span>,</span> ModelCommitment</span> calldata</span> newCommitment</span>)</span></span> external</span>;</span></span> </span> function</span> deprecateModel</span>(</span>uint256</span> modelId</span>)</span> external</span>;</span></span> </span> function</span> getModel</span>(</span>uint256</span> modelId</span>)</span></span> external</span></span> view</span></span> returns</span> (</span>ModelCommitment</span> memory</span> commitment</span>,</span> bool</span> deprecated</span>,</span> address</span> owner</span>)</span>;</span></span> }</span></span></code></pre> registerModel</code> MUST return a unique modelId</code>.</li> updateModel</code> and deprecateModel</code> MUST only be callable by the model owner</code>.</li> getModel</code> MUST return the current commitment</code>, deprecation status, and owner</code> address.</li> Implementations MAY allow versioning under one modelId</code> or require a new modelId</code> per change. The chosen policy MUST be documented.</li> </ul> ZKML Verifier</h4> //</span> SPDX-License-Identifier: CC0-1.0</span></span> pragma</span> solidity</span> ^0.8.20</span>;</span></span> </span> interface</span> IERCZKMLVerifier</span> /</span> is IERC165 </span>/</span> {</span></span> event</span> InferenceVerified</span>(</span></span> uint256</span> indexed</span> modelId</span>,</span></span> bytes32</span> indexed</span> inputCommitment</span>,</span></span> bytes</span> output</span>,</span></span> address</span> indexed</span> caller</span></span> )</span>;</span></span> </span> error</span> InvalidProof</span>(</span>)</span>;</span></span> error</span> ModelMismatch</span>(</span>)</span>;</span> //</span> proof verifies but not tied to given modelId</span></span> error</span> InputCommitmentMismatch</span>(</span>)</span>;</span></span> error</span> OutputMismatch</span>(</span>)</span>;</span> //</span> if verifier checks output commitment/schema</span></span> error</span> UnsupportedProofSystem</span>(</span>bytes4</span> proofSystemId</span>)</span>;</span></span> error</span> VerificationRefused_ModelDeprecated</span>(</span>uint256</span> modelId</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> Verifies a ZK proof for an inference.</span></span> * </span>@dev</span> MUST revert on any failure path. Successful execution implies validity.</span></span> * </span>@param</span> modelId</span> Registry model identifier</span></span> * </span>@param</span> inputCommitment</span> Commitment to private inputs</span></span> * </span>@param</span> output</span> ABI-encoded public outputs</span></span> * </span>@param</span> proof</span> ZK proof bytes</span></span> /</span></span> function</span> verifyInference</span>(</span></span> uint256</span> modelId</span>,</span></span> bytes32</span> inputCommitment</span>,</span></span> bytes</span> calldata</span> output</span>,</span></span> bytes</span> calldata</span> proof</span></span> )</span> external</span>;</span></span> </span> ///</span> Optional helper views:</span></span> function</span> proofSystemOf</span>(</span>uint256</span> modelId</span>)</span> external</span> view</span> returns</span> (</span>bytes4</span>)</span>;</span></span> function</span> registry</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span> registryAddress</span>)</span>;</span></span> }</span></span></code></pre> The verifyInference</code>:</p> MUST fetch the model commitment</code> from the registry and validate the proof</code> against it.</li> MUST revert on any failure (invalid proof, mismatched commitments, unsupported proof system, deprecated model, etc.).</li> SHOULD emit InferenceVerified</code> on success.</li> SHOULD remain stateless except for emitting events. Statefulness MAY be introduced by extensions.</li> </ul> Optional Storage Extension</h4> //</span> SPDX-License-Identifier: CC0-1.0</span></span> pragma</span> solidity</span> ^0.8.20</span>;</span></span> </span> interface</span> IERCZKMLStorageExtension</span> {</span></span> event</span> InferenceStored</span>(</span>bytes32</span> indexed</span> inferenceId</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> Verify and store an inference record.</span></span> * </span>@dev</span> MUST revert on invalid proof.</span></span> * </span>@return</span> inferenceId</span> keccak256(abi.encodePacked(modelId, inputCommitment, output))</span></span> /</span></span> function</span> verifyAndStoreInference</span>(</span></span> uint256</span> modelId</span>,</span></span> bytes32</span> inputCommitment</span>,</span></span> bytes</span> calldata</span> output</span>,</span></span> bytes</span> calldata</span> proof</span></span> )</span> external</span> returns</span> (</span>bytes32</span> inferenceId</span>)</span>;</span></span> </span> function</span> getInference</span>(</span>bytes32</span> inferenceId</span>)</span></span> external</span></span> view</span></span> returns</span> (</span>uint256</span> modelId</span>,</span> bytes32</span> inputCommitment</span>,</span> bytes</span> memory</span> output</span>)</span>;</span></span> }</span></span></code></pre> Replay Protection Note: Implementations that rely on inferenceId = keccak256(modelId, inputCommitment, output)</code> MUST ensure that inputCommitment</code> embeds a nonce/salt</code> or other uniqueness source if replays are a concern (e.g., non-deterministic models or single-use inferences).</p> The registry interface exposes an owner</code> per modelId</code>. Implementations MUST include some ownership/access-control mechanism (e.g., simple owner storage, ERC-173</a>, ERC-721</a> representation, or role-based control). The returned owner</code> address SHOULD be treated as the canonical authority to mutate or deprecate that model.</p> Rationale</h2> Void Return on verifyInference</code>: Reverting on failure and returning nothing on success removes redundant gas-expensive booleans and matches modern Solidity patterns (e.g., OpenZeppelin’s SafeERC20</code>).</li> Separated Registry & Verifier: Encourages modularity—teams can upgrade verifiers or registries independently.</li> Opaque bytes for Proof/Output: Avoids lock-in to a specific proof system or output schema.</li> Deterministic proofSystemId</code>: Prevents collisions and ambiguity; enables predictable dispatch in mixed-system verifiers.</li> Nonce in inputCommitment</code>: Explicitly mitigates replay attacks when inference uniqueness matters.</li> </ul> Backwards Compatibility</h2> Fully backwards compatible:</p> Uses ERC-165</a> like popular ERC-721</a> or ERC-1155</a> for discoverability.</li> No dependency on token ownership standards; minimal collision with existing protocols.</li> </ul> Reference Implementation</h2> //</span> SPDX-License-Identifier: CC0-1.0</span></span> pragma</span> solidity</span> ^0.8.20</span>;</span></span> </span> import</span> "./IERCZKMLRegistry.sol"</span>;</span></span> import</span> "./IERCZKMLVerifier.sol"</span>;</span></span> </span> contract</span> ZKMLVerifier</span> is</span> IERCZKMLVerifier</span> {</span></span> IERCZKMLRegistry </span>public</span> immutable</span> override</span> registry</span>;</span></span> </span> constructor</span>(</span>IERCZKMLRegistry</span> _registry</span>)</span> {</span></span> registry </span>=</span> _registry</span>;</span></span> }</span></span> </span> function</span> verifyInference</span>(</span></span> uint256</span> modelId</span>,</span></span> bytes32</span> inputCommitment</span>,</span></span> bytes</span> calldata</span> output</span>,</span></span> bytes</span> calldata</span> proof</span></span> )</span> external</span> override</span> {</span></span> (</span>IERCZKMLRegistry</span>.</span>ModelCommitment </span>memory</span> cm</span>,</span> bool</span> deprecated</span>,</span>)</span> =</span></span> registry</span>.</span>getModel</span>(</span>modelId</span>)</span>;</span></span> </span> if</span> (</span>deprecated</span>)</span> revert</span> ModelDeprecated</span>(</span>modelId</span>)</span>;</span></span> </span> //</span> Dispatch based on proofSystemId. Example only.</span></span> //</span> bool ok = VerifierLib.verify(proof, cm.vkHash, inputCommitment, output);</span></span> bool</span> ok </span>=</span> _dummyVerify</span>(</span>proof</span>,</span> cm</span>.</span>vkHash</span>,</span> inputCommitment</span>,</span> output</span>)</span>;</span></span> if</span> (</span>!</span>ok</span>)</span> revert</span> InvalidProof</span>(</span>)</span>;</span></span> </span> emit</span> InferenceVerified</span>(</span>modelId</span>,</span> inputCommitment</span>,</span> output</span>,</span> msg.sender</span>)</span>;</span></span> }</span></span> </span> function</span> proofSystemOf</span>(</span>uint256</span> modelId</span>)</span> external</span> view</span> override</span> returns</span> (</span>bytes4</span>)</span> {</span></span> (</span>IERCZKMLRegistry</span>.</span>ModelCommitment </span>memory</span> cm</span>,</span>,</span>)</span> =</span> registry</span>.</span>getModel</span>(</span>modelId</span>)</span>;</span></span> return</span> cm</span>.</span>proofSystemId</span>;</span></span> }</span></span> </span> function</span> _dummyVerify</span>(</span></span> bytes</span> calldata</span>,</span></span> bytes32</span>,</span></span> bytes32</span>,</span></span> bytes</span> calldata</span></span> )</span> private</span> pure</span> returns</span> (</span>bool</span>)</span> {</span></span> return</span> true</span>;</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> Security</h3> Replay Attacks: Inputs must embed a nonce/salt where uniqueness matters. Contracts may also track consumed inferenceIds</code>.</li> Model Commitment Drift: Updating commitments can invalidate proofs; consumers should pin specific modelId</code> + commitment</code> hashes or check deprecated.</li> Hash Domain Separation: Use distinct prefixes (e.g., "ZKML_MODEL_V1") to avoid collisions across contexts.</li> Output Ambiguity: Contracts must validate or commit to output schemas to avoid maliciously crafted bytes.</li> DoS via Heavy Verification: Consider off-chain verification with on-chain succinct attestations, or batching/aggregation.</li> </ul> Gas</h3> Proof verification can dominate gas costs; splitting verification-only calls from storage writes lets integrators choose.</li> Events are cheaper than persistent storage for audit trails.</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Minimal Avatar Smart Wallet (MASW) 2025-07-08T00:00:00+00:00 Abstract</h2> Minimal Avatar Smart Wallet (MASW) is an immutable delegate‑wallet that any EOA can designate via EIP‑7702</a> (txType 0x04</code>). Once designated, the wallet's code remains active for every subsequent transaction until the owner sends a new 0x04</code> to clear or replace it. During each delegated call the EOA is the avatar and MASW's code executes as the delegate at the same address, enabling atomic batched calls (EIP‑712</a> signed) and optional sponsor gas reimbursement in ETH or ERC‑20</a>.</p> The contract offers one primary function, executeBatch</code>, plus two plug‑in hooks: a Policy Module for pre/post guards and a Recovery Module for alternate signature validation. Replay attacks are prevented by a global metaNonce, an expiry, and a chain‑bound EIP‑712</code> domain separator. Standardising this seven‑parameter ABI removes wallet fragmentation while still allowing custom logic through modules.</p> Motivation</h2> A single‑transaction code‑injection model (EIP‑7702) grants EOAs full implementation freedom, but unconstrained diversity would impose high coordination costs:</p> Interoperability</strong> – Divergent ABIs and fee‑settlement conventions force dApps and relayers to maintain per‑wallet adapters, increasing integration complexity and failure modes.</li> Economic alignment</strong> – Gas‑sponsorship relies on deterministic fee‑reimbursement paths; heterogeneity erodes relayer incentives and throttles sponsored‑transaction volume.</li> Tooling precision</strong> – Indexers, debuggers, and static‑analysis frameworks achieve optimal decoding and gas estimation when targeting a single, fixed byte‑code and seven‑field call schema.</li> Extensibility focus</strong> – Constraining variability to two module boundaries (Policy, Recovery) localizes complexity, allowing research and hardening efforts to concentrate on higher‑level security primitives rather than re‑engineering core wallet logic.</li> </ul> By standardising the immutable byte‑code, signature domain, and minimal ABI while exposing clearly defined extension hooks, MASW minimizes fragmentation and maximizes composability across the Ethereum tooling stack.</p> Specification</h2> 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.</p> Overview of Delegation Flow</h3> Deploy</strong> MASW</code> with constructor argument _owner = EOA</code>.</li> The owner sends an EIP‑7702 transaction (txType 0x04</code>) referencing the contract's byte‑code hash.</li> After that transaction the EOA acts as the avatar wallet</strong> while the MASW logic executes as the delegate wallet</strong> at the same</em> address.</li> </ol> Public Interface</h3> function</span> executeBatch</span>(</span></span> address</span>[</span>]</span> calldata</span> targets</span>,</span></span> uint256</span>[</span>]</span> calldata</span> values</span>,</span></span> bytes</span>[</span>]</span> calldata</span> calldatas</span>,</span></span> address</span> token</span>,</span></span> uint256</span> fee</span>,</span></span> uint256</span> expiry</span>,</span></span> bytes</span> calldata</span> signature</span></span> )</span> external</span>;</span></span> </span> function</span> setPolicyModule</span>(</span>address</span> newModule</span>)</span> external</span>;</span></span> function</span> setRecoveryModule</span>(</span>address</span> newModule</span>)</span> external</span>;</span></span> </span> event</span> BatchExecuted</span>(</span>bytes32</span> indexed</span> structHash</span>)</span>;</span></span> event</span> ModuleChanged</span>(</span>bytes32</span> indexed</span> kind</span>, </span>address</span> oldModule</span>, </span>address</span> newModule</span>)</span>;</span></span></code></pre>Transaction Type Hash</h3> bytes32</span> constant</span> BATCH_TYPEHASH </span>=</span> keccak256</span>(</span></span> "Batch(address[] targets,uint256[] values,bytes[] calldatas,address token,uint256 fee,uint256 exp,uint256 metaNonce)"</span></span> )</span>;</span></span></code></pre>Storage Layout</h3> Slot</th> Name</th> Type</th> Description</th></tr></thead> 0</td> metaNonce</code></td> uint256</td> Monotonically increasing meta‑nonce</td></tr> 1</td> _entered</code></td> uint256</td> Re‑entrancy guard flag</td></tr> 2</td> policyModule</code></td> address</td> Optional IPolicyModule</code> (zero = none)</td></tr> 3</td> recoveryModule</code></td> address</td> Optional IRecoveryModule</code> (zero = none)</td></tr> </tbody></table> owner</code> and DOMAIN_SEPARATOR</code> are immutable</code> and occupy no storage slots.</p> Domain Separator Construction</h3> DOMAIN_SEPARATOR </span>=</span> keccak256</span>(</span></span> abi</span>.</span>encode</span>(</span></span> keccak256</span>(</span>"EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"</span>)</span>,</span></span> keccak256</span>(</span>"MASW"</span>)</span>,</span></span> keccak256</span>(</span>"1"</span>)</span>,</span></span> block</span>.</span>chainid</span>,</span> //</span> MUST be the live chain‑ID; using 0 is disallowed</span></span> _owner </span>//</span> keeps separator stable before & after delegation</span></span> )</span></span> )</span>;</span></span></code></pre>Batch Execution (executeBatch</code>)</h3> Stage</th> Behaviour</th></tr></thead> Validation</strong></td> ‑ targets.length == values.length == calldatas.length > 0</code> ‑ block.timestamp ≤ expiry</code> ‑ metaNonce</code> matches then increments ‑ EIP712</code> digest recovers owner</code> or</strong> is approved by recoveryModule</code></td></tr> Policy pre‑hook</strong></td> If policyModule != address(0)</code>, preCheck</code> MUST</strong> return true</code>; a revert or false</code> vetoes the batch</td></tr> Calls</strong></td> For each index i</em>: targets[i].call{value:values[i]}(calldatas[i])</code>; revert on first failure</td></tr> Policy post‑hook</strong></td> Same semantics as pre‑hook</td></tr> Fee reimbursement</strong></td> If fee > 0</code>: native transfer (token == address(0)</code>) or ERC20</code> transfer</code> with OpenZeppelin‑style return‑value check </td></tr> Emit</strong></td> BatchExecuted(structHash)</code></td></tr> </tbody></table> Gas Sponsorship</h4> The relayer and owner agree off‑chain on (token, fee)</code> prior to submission. Because the fee is part of the signed batch, a relayer cannot unilaterally raise it. If a rival relayer broadcasts the same signed batch first, they earn the fee and the original relayer's transaction reverts—aligning incentives naturally. Relayers MUST</strong> confirm the avatar's balance up‑front; insufficient funds render the transaction invalid in the mem‑pool.</p> Modules</h3> Policy Module</h4> interface</span> IPolicyModule</span> {</span></span> function</span> preCheck</span> (</span>address</span> sender</span>,</span> bytes</span> calldata</span> rawData</span>,</span> uint256</span> value</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> function</span> postCheck</span>(</span>address</span> sender</span>,</span> bytes</span> calldata</span> rawData</span>,</span> uint256</span> value</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> }</span></span></code></pre> A module MAY</strong> veto by reverting or</em> by returning false</code>.</li> The value</code> parameter represents the total ETH sent with the transaction (msg.value</code>), allowing the policy module to validate this against the batch requirements contained in rawData</code>.</li> Aggregator designs are encouraged: forward to child policies and stop on first failure (revert or return false</code>).</li> </ul> Recovery Module</h4> interface</span> IRecoveryModule</span> {</span></span> function</span> isValidSignature</span>(</span>bytes32</span> hash</span>,</span> bytes</span> calldata</span> sig</span>)</span> external</span> view</span> returns</span> (</span>bytes4</span>)</span>;</span></span> }</span></span></code></pre> Must return 0x1626ba7e</code>.</p> Nonce‑Race Consideration</h3> A single global metaNonce</code> is used. Two relayers submitting the same nonce concurrently results in one success and one revert. The expiry</code> field (wallets typically set ≤ 30 s) makes such races low‑impact, but UIs should surface the failure.</p> Rationale</h2> Immutable logic</strong> minimizes upgrade risk; a new version requires an explicit 7702 0x04</code> call.</li> A two‑module</strong> boundary captures common customizations without growing byte‑code.</li> No hard maxTargets</code>; advanced users can bundle many calls, while conservative users install a size‑capping Policy module.</li> Domain separator binds the real chainId</code> to mitigate cross‑chain replays.</li> </ul> Reference Implementation</h2> Reference implementation can be found here MASW.sol</code></a>.</p> Security Considerations</h2> Threat</th> Mitigation</th></tr></thead> Same‑chain replay</td> Global metaNonce</code></td></tr> Cross‑chain replay</td> Chain‑bound domain separator</td></tr> Fee grief / over‑charge</td> Fee is part of signed data; front‑running risk sits with relayer</td></tr> Batch gas grief</td> Optional Policy can reject oversized batches</td></tr> ERC20</code> non‑standard returns</td> OpenZeppelin SafeERC20</code> transfer check</td></tr> Re‑entrancy</td> nonReentrant</code> guard; state mutated only before external calls (nonce++) and after (fee transfer)</td></tr> Malicious Module</td> Core logic immutable; swapping modules needs an owner‑signed tx</td></tr> </tbody></table> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Contract Feature Detection 2025-07-07T00:00:00+00:00 Abstract</h2> Creates a standard method supportsFeature(bytes4)</code> in the same spirit as supportsInterface(bytes4)</code> to publish and detect what features a smart contract implements that lack a derivable ERC-165</a> interface.</p> Motivation</h2> Ethereum Name Service (ENS) has maintained backwards compatibility with contracts created in 2016 through extensive use of ERC-165. Unfortunately, not all contract capabilities can be expressed through an unique interface.</p> Features allow expression of contract capabilities that preserve existing interfaces. This proposal standardizes the concept of features and standardizes the identification (naming) of features.</p> Defining a new standard avoids unnecessary pollution of the ERC-165 selector namespace with synthetic interfaces representing features.</p> Specification</h2> 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</a> and RFC 8174</a>.</p> How Features are Identified</h3> For this standard, a feature</em> is any property of a contract that cannot be expressed via ERC-165.</p> A feature name SHOULD be a reverse domain name that uniquely defines its implication, eg. eth.ens.resolver.extended.multicall</code> is the multicall feature for an extended ENS resolver contract.</p> A feature identifier is defined as the first four-bytes of the keccak256-hash of its name, eg. bytes4(keccak256("eth.ens.resolver.extended.multicall")) = 0x96b62db8</code>.</p> How a Contract will Publish the Features it Implements</h3> A contract that is compliant with this specification SHALL implement the following interface:</p> interface</span> IERC7996</span> {</span></span> ///</span> @notice</span> Check if a feature is supported.</span></span> ///</span> @param</span> featureId</span> The feature identifier.</span></span> ///</span> @return</span> `true` if the feature is supported by the contract.</span></span> function</span> supportsFeature</span>(</span>bytes4</span> featureId</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> }</span></span></code></pre> The ERC-165 interface identifier for this interface is 0x582de3e7</code>.</p> How to Detect if a Contract Implements Features</h3> Check if the contract supports the interface above according to ERC-165</a>.</li> </ol> How to Detect if a Contract Implements any Given Feature</h3> If you are not sure if the contract implements features, use the above procedure to confirm.</li> If it implements features, then call supportsFeature(featureId)</code> to determine if it implements the desired feature.</li> </ol> Note: a contract that implements features MAY implement no features.</p> Rationale</h2> Since feature names cannot be derived from a contract interface, they are derived from a reverse domain name to reduce collisions and permit a human-readable representention that briefly describes its implication.</p> Backwards Compatibility</h2> Callers unaware of features or any specific feature experience no change in behavior.</p> ENS already implements this ERC.</p> Security Considerations</h2> As with ERC-165, declaring support for a feature does not guarantee that the contract implements it.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Confidential Fungible Token 2025-07-03T00:00:00+00:00 Abstract</h2> The following standard describes confidential fungible tokens via pointers. All amounts in this standard are represented by confidential pointers; therefore, balances and transfer amounts are confidential. Pointers refer to data stored elsewhere--onchain or offchain. The logistics of pointer resolution, operation, and location are implementation specific. The interface defines functions to transfer tokens with pointers, as well as approve operators, allowing the token to be transferred by a third party.</p> Motivation</h2> Confidential tokens enable private value transfer which is vital for many usecases such as payroll, confidential DeFi, institutional settlement, and more. A standard interface allows pointer based confidential tokens on Ethereum to be reused by other applications: from privacy-focused wallets to decentralized exchanges, while keeping transaction amounts private from public view.</p> Specification</h2> 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</a> and RFC 8174</a>.</p> Nomenclature</h3> All amounts in this ERC are pointer based amounts represented by bytes32</code> pointers unless otherwise specified. The resolution and manipulation of these pointers is implementation specific.</p> Token</h3> Compliant tokens MUST implement ERC-165</a>. The supportsInterface</code> function MUST return true</code> if 0x4958f2a4</code> is passed through the interfaceID</code> argument.</p> Methods</h3> Compliant tokens MUST implement the following methods, unless otherwise specified:</p> name()</code></h4> Returns the name of the token - e.g. "MyConfidentialToken"</code>.</p> function</span> name</span>(</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span></span></code></pre></li> symbol()</code></h4> Returns the symbol of the token - e.g. "MCT"</code>.</p> function</span> symbol</span>(</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span></span></code></pre></li> decimals()</code></h4> Returns the number of decimals the token uses (e.g. 6</code>) as a plaintext uint8</code>.</p> function</span> decimals</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint8</span>)</span></span></code></pre></li> contractURI()</code></h4> Returns the metadata URI for the token. SHOULD follow the schema defined in ERC-7572</a>.</p> function</span> contractURI</span>(</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span></span></code></pre></li> confidentialTotalSupply()</code></h4> Returns the total token supply.</p> function</span> confidentialTotalSupply</span>(</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li> confidentialBalanceOf(address)</code></h4> Returns the balance of account</code>.</p> function</span> confidentialBalanceOf</span>(</span>address</span> account</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li> isOperator(address,address)</code></h4> Returns true</code> if spender</code> is currently authorized to transfer tokens on behalf of holder</code>.</p> function</span> isOperator</span>(</span>address</span> holder</span>,</span> address</span> spender</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span></span></code></pre></li> setOperator(address,uint48)</code></h4> Authorizes operator</code> to transfer tokens on behalf of the caller until timestamp until</code>--passed as a plaintext uint48</code>. An operator may transfer any amount of tokens on behalf of a holder while approved. Accounts may have multiple simultaneous operators.</p> MUST emit the OperatorSet</code> event.</p> function</span> setOperator</span>(</span>address</span> operator</span>,</span> uint48</span> until</span>)</span> external</span></span></code></pre></li> confidentialTransfer(address,bytes32)</code></h4> Transfers amount</code> of tokens to address to</code>. The function MAY revert if the caller's balance does not have enough tokens to spend.</p> Returns the actual amount that was transferred.</p> MUST emit the ConfidentialTransfer</code> event.</p> function</span> confidentialTransfer</span>(</span>address</span> to</span>,</span> bytes32</span> amount</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li> confidentialTransfer(address,bytes32,bytes)</code></h4> Transfers amount</code> of tokens to address to</code>. The function MAY revert if the caller's balance does not have enough tokens to spend.</p> The data</code> parameter contains implementation-specific information such as cryptographic proofs.</p> Returns the actual amount that was transferred.</p> MUST emit the ConfidentialTransfer</code> event.</p> function</span> confidentialTransfer</span>(</span>address</span> to</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li> confidentialTransferFrom(address,address,bytes32)</code></h4> Transfers amount</code> of tokens from address from</code> to address to</code>. The function MAY revert if the from</code>'s account balance does not have enough tokens to spend.</p> Returns the actual amount that was transferred.</p> MUST revert if the caller is not an operator for from</code>.</p> MUST emit the ConfidentialTransfer</code> event.</p> function</span> confidentialTransferFrom</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li> confidentialTransferFrom(address,address,bytes32,bytes)</code></h4> Transfers amount</code> of tokens from address from</code> to address to</code>. The function MAY revert if the from</code>'s account balance does not have enough tokens to spend.</p> The data</code> parameter contains implementation-specific information such as cryptographic proofs.</p> Returns the actual amount that was transferred.</p> MUST revert if the caller is not an operator for from</code>.</p> MUST emit the ConfidentialTransfer</code> event.</p> function</span> confidentialTransferFrom</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li> confidentialTransferAndCall(address,bytes32,bytes)</code></h4> Transfers amount</code> of tokens to address to</code>. The function MAY revert if the caller's balance does not have enough tokens to spend.</p> The data</code> parameter contains implementation-specific information such as cryptographic proofs.</p> See Callback Details</a> below for details on the callback flow.</p> Returns the actual amount that was transferred.</p> MUST emit the ConfidentialTransfer</code> event.</p> function</span> confidentialTransferAndCall</span>(</span>address</span> to</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> callData</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li> confidentialTransferAndCall(address,bytes32,bytes,bytes)</code></h4> Transfers amount</code> of tokens to address to</code>. The function MAY revert if the caller's balance does not have enough tokens to spend.</p> The data</code> parameter contains implementation-specific information such as cryptographic proofs.</p> See Callback Details</a> below for details on the callback flow.</p> Returns the actual amount that was transferred.</p> MUST emit the ConfidentialTransfer</code> event.</p> function</span> confidentialTransferAndCall</span>(</span>address</span> to</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> data</span>,</span> bytes</span> calldata</span> callData</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li> confidentialTransferFromAndCall(address,address,bytes32,bytes)</code></h4> Transfers amount</code> of tokens from address from</code> to address to</code>. The function MAY revert if the from</code>'s account balance does not have enough tokens to spend.</p> See Callback Details</a> below for details on the callback flow.</p> Returns the actual amount that was transferred.</p> MUST revert if the caller is not an operator for from</code>.</p> MUST emit the ConfidentialTransfer</code> event.</p> function</span> confidentialTransferFromAndCall</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> callData</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li> confidentialTransferFromAndCall(address,address,bytes32,bytes,bytes)</code></h4> Transfers amount</code> of tokens from address from</code> to address to</code>. The function MAY revert if the from</code>'s account balance does not have enough tokens to spend.</p> The data</code> parameter contains implementation-specific information such as cryptographic proofs.</p> See Callback Details</a> below for details on the callback flow.</p> Returns the actual amount that was transferred.</p> MUST revert if the caller is not an operator for from</code>.</p> MUST emit the ConfidentialTransfer</code> event.</p> function</span> confidentialTransferFromAndCall</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> data</span>,</span> bytes</span> calldata</span> callData</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li> </ul> Events</h3> ConfidentialTransfer</h4> MUST trigger when confidential tokens are transferred, including zero value transfers.</p> A token contract which creates new tokens SHOULD trigger a ConfidentialTransfer event with the from</code> address set to 0x0</code> when tokens are created.</p> event</span> ConfidentialTransfer</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>bytes32</span> indexed</span> amount</span>)</span></span></code></pre></li> OperatorSet</h4> MUST trigger on any successful call to setOperator</code>.</p> event</span> OperatorSet</span>(</span>address</span> indexed</span> holder</span>, </span>address</span> indexed</span> operator</span>, </span>uint48</span> until</span>)</span></span></code></pre></li> AmountDisclosed</h4> SHOULD trigger when a pointer amount is publicly disclosed through implementation-specific mechanisms.</p> event</span> AmountDisclosed</span>(</span>bytes32</span> indexed</span> handle</span>, </span>uint256</span> amount</span>)</span></span></code></pre></li> </ul> Callback Details</h3> Transfer functions suffixed with andCall</code> execute a callback to the to</code> address AFTER all transfer logic is completed. The callback calls the onConfidentialTransferReceived</code> function with the transfer initiator (operator), from address, actual amount sent, and given callData</code> bytes (the last parameter for andCall</code> functions). The callback flow is as follows:</p> If address(to).code.length == 0</code> the callback is a no-op and returns successfully.</li> Call onConfidentialTransferReceived(address, address, bytes32, bytes)</code></a> on to</code>.</li> If the function call reverts, revert.</li> If the function call returns the false boolean, attempt to transfer back the tokens to the original holder and return.</li> </ul> Contract Receivers</h3> For a contract to receive a transfer with a callback, it MUST implement the onConfidentialTransferReceived</code> function:</p> onConfidentialTransferReceived</h4> If the callback is unsuccessful, the function SHOULD revert or return a pointer to the false boolean.</p> The token will attempt to return tokens from the receiver to the sender if false is returned. Note that this reversal may fail if the receiver spends tokens as part of the callback.</p> function</span> onConfidentialTransferReceived</span>(</span>address</span> operator</span>,</span> address</span> from</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> returns</span> (</span>bytes32</span> success</span>)</span>;</span></span></code></pre>Rationale</h2> Technology Agnostic Design</h3> Using bytes32</code> allows implementations using pointer based systems and privacy mechanisms including FHE systems, zero-knowledge proofs, secure enclaves, or future technologies to be compliant.</p> Operator Model</h3> Time-limited operators provide granular control while enabling DeFi protocol integration and natural permission expiration. This approach reduces the load on the external system by removing the need to track approval amounts.</p> Data Parameter</h3> The bytes calldata data</code> parameter in transfer functions allows implementations to include cryptographic proofs, access permissions, or other privacy-mechanism-specific information.</p> Security Considerations</h2> Security depends on the underlying pointer based mechanism. Implementations must guard against side-channel attacks and ensure proper key management for offchain operations.</p> Token callbacks are associated with inherent security risks, including reentrancy and gas griefing. When utilizing callbacks, consider using reentrancy protection and setting a gas limit.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Operator contract for non delegated EOAs 2025-07-02T00:00:00+00:00 Abstract</h2> This standard defines a contract interface that enables externally owned accounts (EOAs) to perform batch call executions via a standard Operator contract, without requiring them to delegate control or convert into smart contract accounts.</p> Motivation</h2> The ERC-7702</a> allows EOAs to become powerful smart contract accounts (SCA), which solves many UX issues, like the double approve</code> + transferFrom</code> transactions. While this new technology is still reaching wider adoption over time, we need a way to improve UX for the users that decide to not have code attached to their EOAs. This proposal introduces a lightweight, backward-compatible mechanism to enhance UX for such users. By leveraging a standardized Operator contract, EOAs can batch multiple contract calls into a single transaction—assuming the target contracts are compatible (i.e., implement the Operated pattern).</p> Specification</h2> 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</a> and RFC 8174</a>.</p> Definitions</h3> Operator: The contract that executes calls on the sender's behalf.</li> Operated: The contract that supports calls through the Operator.</li> </ul> It's OPTIONAL but HIGHLY RECOMMENDED to have the Operator</code> contract as a singleton.</p> Operator</h3> pragma</span> solidity</span> ^0.8.29</span>;</span></span> </span> interface</span> IOperator</span> {</span></span> struct</span> Call</span> {</span></span> address</span> target</span>;</span></span> uint256</span> value</span>;</span></span> bytes</span> callData</span>;</span></span> }</span></span> </span> ///</span> @notice</span> Execute calls</span></span> ///</span> @param</span> calls</span> An array of Call structs</span></span> ///</span> @return</span> returnData</span> An array of bytes containing the responses</span></span> function</span> execute</span>(</span>Call</span>[</span>]</span> calldata</span> calls</span>)</span> external</span> payable</span> returns</span> (</span>bytes</span>[</span>]</span> memory</span> returnData</span>)</span>;</span></span> </span> ///</span> @notice</span> The address which initiated the executions</span></span> ///</span> @return</span> sender</span> The actual sender of the calls</span></span> function</span> onBehalfOf</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span> sender</span>)</span>;</span></span> }</span></span></code></pre>Methods</h3> execute</code> Execute the calls sent by the actual sender.</p> MUST revert if any of the calls fail. MUST return data from the calls.</p> onBehalfOf</code> Used by the target contract to get the actual caller.</p> MUST return the actual msg.sender</code> when called in the context of a call. MUST revert when called outside of the context of a call.</p> Operated</h3> pragma</span> solidity</span> ^0.8.29</span>;</span></span> </span> import</span> { </span>Context</span> }</span> from</span> "@openzeppelin/contracts/utils/Context.sol"</span>;</span></span> import</span> { </span>IOperator</span> }</span> from</span> "./interfaces/IOperator.sol"</span>;</span></span> </span> ///</span> @title</span> Operated contract</span></span> ///</span> @dev</span> Supports calls through the Operator</span></span> abstract</span> contract</span> Operated</span> is</span> Context</span> {</span></span> IOperator </span>public</span> immutable</span> operator</span>;</span></span> </span> constructor</span>(</span>address</span> operator_</span>)</span> {</span></span> operator </span>=</span> IOperator</span>(</span>operator_</span>)</span>;</span></span> }</span></span> </span> ///</span> @inheritdoc</span> Context</span></span> function</span> _msgSender</span>(</span>)</span> internal</span> view</span> virtual</span> override</span> returns</span> (</span>address</span>)</span> {</span></span> if</span> (</span>msg.sender</span> ==</span> address</span>(</span>operator</span>)</span>)</span> {</span></span> return</span> operator</span>.</span>onBehalfOf</span>(</span>)</span>;</span></span> }</span></span> </span> return</span> msg.sender</span>;</span></span> }</span></span> }</span></span></code></pre> Any contract can become compatible to execute the batch call by EOA using operator if it extends the Operated</code> contract. The Operated</code> contract overrides _msgSender()</code> to return operator.onBehalfOf()</code> when the call originates from the Operator. This ensures that the target contract recognizes the EOA initiating the batch execution, preserving correct sender context.</p> This behavior fits well with the usage of the _msgSender() function from ERC-2771</a>.</p> Methods</h3> _msgSender</code> Returns msg.sender</code> or operator.onBehalfOf()</code></p> Rationale</h2> By having a trusted contract (Operator</code>) that may act on behalf of the EOA wallet, this ERC provides batch call capabilities and keeps the EOA as the caller of the target contracts.</p> Backwards Compatibility</h2> The main limitation of this ERC is that only contracts that implements the Operated</code> logic will be able to receive calls through the Operator</code>.</p> Reference Implementation</h2> Operator</h3> pragma</span> solidity</span> ^0.8.29</span>;</span></span> </span> import</span> {</span>TransientSlot</span>}</span> from</span> "@openzeppelin/contracts/utils/TransientSlot.sol"</span>;</span></span> import</span> {</span>Address</span>}</span> from</span> "@openzeppelin/contracts/utils/Address.sol"</span>;</span></span> import</span> {</span>ReentrancyGuardTransient</span>}</span> from</span> "@openzeppelin/contracts/utils/ReentrancyGuardTransient.sol"</span>;</span></span> import</span> {</span>IOperator</span>}</span> from</span> "./interfaces/IOperator.sol"</span>;</span></span> </span> ///</span> @title</span> Operator contract</span></span> ///</span> @dev</span> Allows standard EOAs to perform batch calls</span></span> contract</span> Operator</span> is</span> IOperator</span>, </span>ReentrancyGuardTransient</span> {</span></span> using</span> TransientSlot </span>for</span> </span>;</span></span> using</span> Address</span> for</span> address</span>;</span></span> </span> //</span> keccak256(abi.encode(uint256(keccak256("operator.actual.sender")) - 1)) & ~bytes32(uint256(0xff))</span></span> bytes32</span> private</span> constant</span> MSG_SENDER_STORAGE </span>=</span> 0x0de195ebe01a7763c35bcc87968c4e65e5a5ea50f2d7c33bed46c98755a66000</span>;</span></span> </span> modifier</span> setMsgSender</span>(</span>)</span> {</span></span> MSG_SENDER_STORAGE</span>.</span>asAddress</span>(</span>)</span>.</span>tstore</span>(</span>msg.sender</span>)</span>;</span></span> _</span>;</span></span> MSG_SENDER_STORAGE</span>.</span>asAddress</span>(</span>)</span>.</span>tstore</span>(</span>address</span>(</span>0</span>)</span>)</span>;</span></span> }</span></span> </span> ///</span> @inheritdoc</span> IOperator</span></span> function</span> onBehalfOf</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span> _actualMsgSender</span>)</span> {</span></span> _actualMsgSender </span>=</span> MSG_SENDER_STORAGE</span>.</span>asAddress</span>(</span>)</span>.</span>tload</span>(</span>)</span>;</span></span> require</span>(</span>_actualMsgSender </span>!=</span> address</span>(</span>0</span>)</span>,</span> "outside-call-context"</span>)</span>;</span></span> }</span></span> </span> ///</span> @inheritdoc</span> IOperator</span></span> function</span> execute</span>(</span></span> Call</span>[</span>]</span> calldata</span> calls_</span></span> )</span> external</span> payable</span> override</span> nonReentrant</span> setMsgSender</span> returns</span> (</span>bytes</span>[</span>]</span> memory</span> _returnData</span>)</span> {</span></span> uint256</span> _length </span>=</span> calls_</span>.</span>length</span>;</span></span> _returnData </span>=</span> new</span> bytes</span>[](</span>_length</span>)</span>;</span></span> </span> uint256</span> _sumOfValues</span>;</span></span> Call </span>calldata</span> _call</span>;</span></span> for</span> (</span>uint256</span> i</span>;</span> i </span><</span> _length</span>;</span> )</span> {</span></span> _call </span>=</span> calls_</span>[</span>i</span>]</span>;</span></span> uint256</span> _value </span>=</span> _call</span>.</span>value</span>;</span></span> unchecked</span> {</span></span> _sumOfValues </span>+</span>=</span> _value</span>;</span></span> }</span></span> _returnData</span>[</span>i</span>]</span> =</span> _call</span>.</span>target</span>.</span>functionCallWithValue</span>(</span>_call</span>.</span>callData</span>,</span> _value</span>)</span>;</span></span> unchecked</span> {</span></span> +</span>+</span>i</span>;</span></span> }</span></span> }</span></span> </span> require</span>(</span>msg</span>.</span>value </span>==</span> _sumOfValues</span>,</span> "value-mismatch"</span>)</span>;</span></span> }</span></span> }</span></span></code></pre> Worth noting that the usage of transient storage (EIP-1153</a>) for storing the msg.sender</code> is highly RECOMMENDED.</p> Operated</h3> pragma</span> solidity</span> ^0.8.29</span>;</span></span> </span> import</span> {</span>Context</span>}</span> from</span> "@openzeppelin/contracts/utils/Context.sol"</span>;</span></span> import</span> {</span>IERC20</span>}</span> from</span> "@openzeppelin/contracts/token/ERC20/IERC20.sol"</span>;</span></span> import</span> {</span>IOperator</span>}</span> from</span> "./interfaces/IOperator.sol"</span>;</span></span> import</span> {</span>Operated</span>}</span> from</span> "./Operated.sol"</span>;</span></span> </span> ///</span> @title</span> Operated contract</span></span> ///</span> @dev</span> Supports calls through the Operator</span></span> contract</span> OperatorCompatible</span> is</span> Operated</span> {</span></span> error</span> InsufficientBalance</span>(</span>)</span>;</span></span> </span> mapping</span>(</span>address</span> =></span> mapping</span>(</span>address</span> =></span> uint256</span>)</span>)</span> public</span> balance</span>;</span></span> </span> constructor</span>(</span>address</span> operator_</span>)</span> Operated</span>(</span>operator_) </span>{</span>}</span></span> </span> function</span> deposit</span>(</span>address</span> token_</span>,</span> uint256</span> amount_</span>)</span> public</span> payable</span> {</span></span> if</span> (</span>token_ </span>==</span> address</span>(</span>0</span>)</span>)</span> revert</span> InvalidToken</span>(</span>)</span>;</span></span> address</span> _sender </span>=</span> _msgSender</span>(</span>)</span>;</span></span> IERC20</span>(</span>token_</span>)</span>.</span>transferFrom</span>(</span>_sender</span>,</span> address</span>(</span>this</span>)</span>,</span> amount_</span>)</span>;</span></span> balance</span>[</span>token_</span>]</span>[</span>_sender</span>]</span> +</span>=</span> amount_</span>;</span></span> }</span></span> </span> function</span> withdraw</span>(</span>address</span> token_</span>,</span> uint256</span> amount_</span>)</span> public</span> {</span></span> if</span> (</span>token_ </span>==</span> address</span>(</span>0</span>)</span>)</span> revert</span> InvalidToken</span>(</span>)</span>;</span></span> address</span> _sender </span>=</span> _msgSender</span>(</span>)</span>;</span></span> if</span> (</span>balance</span>[</span>token_</span>]</span>[</span>_sender</span>]</span> <</span> amount_</span>)</span> revert</span> InsufficientBalance</span>(</span>)</span>;</span></span> balance</span>[</span>token_</span>]</span>[</span>_sender</span>]</span> -</span>=</span> amount_</span>;</span></span> IERC20</span>(</span>token_</span>)</span>.</span>transfer</span>(</span>_sender</span>,</span> amount_</span>)</span>;</span></span> }</span></span> }</span></span> </span></code></pre>Security Considerations</h2> The execute</code> function MUST implement reentracy control to avoid having a callback call overriding the sender's storage.</li> The Operated</code> contract MUST interact with a trusted Operator</code> contract.</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Owner-Authorized Token Transfer Protocol 2025-06-11T00:00:00+00:00 Abstract</h2> This proposal introduces an innovative token transfer processing model designed for third parties, enabling seamless use of Ethereum-based tokens (e.g., ERC-20</a>) by non-crypto-native actors. The concept allows a third-party payment processor to initiate token transfers on behalf of another party and to cover the associated transaction (gas) fees. The main party (user) always remains the explicit owner of the tokens, which are securely held and referenced under their ownership in the smart contract.</p> The transfer process is two-phased:</p> Initiation:</strong> The payment processor proposes a token transfer via the smart contract. This proposal is emitted as an on-chain event, including all relevant transfer details and a unique hash of the transaction (“proposal hash”).</li> Approval:</strong> The authorized party (owner) reviews the proposal off-chain and, if in agreement, signs the proposal hash with their private key. This signature is sent to the payment processor, who then submits it to the smart contract. There, the contract verifies the signature and, upon approval, carries out the token transfer in the owner’s name.</li> </ol> To increase security and usability, each proposal includes an explicit expiration time. If the signature is not submitted and verified within the defined validity period, the proposal becomes void and the transfer cannot be executed.</p> To further enhance user safety, the owner is provided with a function that allows transferring all token balances directly to their own address in case the payment processor becomes unresponsive, acts improperly, or if external conditions such as transaction costs change unfavorably.</p> This model empowers entities to integrate blockchain-based payments into their workflows without directly holding or managing cryptocurrencies. All token movements require explicit owner approval, ensuring security and retaining full user control. The payment processor is compensated “off-chain” (e.g., in fiat currency) and is responsible for gas costs.</p> By removing the technical and operational burdens of crypto management from the end user, this approach facilitates broader adoption of tokenized business cases and simplifies enterprise integration.</p> Motivation</h2> Adoption of blockchain-based payments and tokenized assets in enterprise and conventional business contexts is still often hindered by the need for end-users or business partners to directly manage cryptocurrencies, wallets, and on-chain transactions. For many organizations, the technical, regulatory, and operational burdens associated with self-custody and on-chain fee management present significant entry barriers.</p> This proposal aims to lower these barriers by introducing a model in which a trusted third-party payment processor can manage all blockchain transactions on behalf of a token owner, including paying transaction fees. The owner maintains full control and explicit on-chain ownership of the assets, and must approve all outgoing transfers cryptographically. Payment for the processor's services (including gas reimbursement) can take place off-chain and in fiat currency, which aligns with existing financial workflows and compliance expectations.</p> With an explicit fallback function, owners are further protected, ensuring they can always reclaim direct control over their assets if the processor becomes unresponsive or external conditions change.</p> In summary, this standard facilitates broader and more secure adoption of token-based processes by offloading complexity from end-users, while preserving security, transparency, and user sovereignty.</p> Specification</h2> Methods</h3> Smart Contract that holds the assets (ITokenStorage.sol</code>)</h4> Transfer proposal: proposeTransaction</code></h5> function</span> proposeTransaction</span>(</span>address</span> tokenAddress</span>,</span> uint256</span> amountToSent</span>,</span> address</span> destinationAddress</span>)</span> external</span>;</span></span></code></pre> Called from the paymentProcessor/transactionProvider of the storage to initiate a token transfer. Emits a TransactionProposed</code> event. The parameter tokenAddress</code> is the address of the token which should be transferred. The parameter amountToSent</code> is the amount which should be transferred to the desired destination address. The parameter destinationAddress</code> defines the receiver of the defined token. The proposal is stored in the contract and a unique (uint256) hash is generated for it, which is used for the approval process.</p> Transfer completion: completeTransaction</code></h5> function</span> completeTransaction</span>(</span>uint256</span> hash</span>,</span> bytes</span> memory</span> signature</span>)</span> external</span>;</span></span></code></pre> Called from the paymentProcessor/transactionProvider of the storage to perform a token transfer. Emits a TransactionCompleted</code> event. The parameter hash</code> is unique identifier of the transaction. The parameter signature</code> is a signed message which only includes the hash. This message is signed by the credentials of the owner, which are used to verify that the owner has approved the transaction. This function includes a verification step to ensure that the signature is valid and corresponds to the owner of the tokens. If the signature is valid, the contract executes the transfer of tokens from the smart contract to the destinationAddress</code> specified in the proposal.</p> Fallback function: sendFundsToOwner</code></h5> function</span> sendFundsToOwner</span>(</span>address</span> tokenAddress</span>)</span> external</span>;</span></span></code></pre> This function allows the owner to transfer all tokens held in the contract back to his/her own address. This is a safety measure to ensure that the owner can reclaim their assets if the payment processor becomes unresponsive or if external conditions change unfavorably. Emits a FallbackScenarioExecuted</code> event. The parameter tokenAddress</code> is the address of the token which should be transferred to the owner. In case this method is called, the contract will transfer all tokens of the given type to the owner address.</p> Verification of the signature: 'verifySignature'</h4> function</span> verifySignature</span>(</span></span> address</span> _signer</span>,</span></span> address</span> tokenAddress</span>,</span></span> uint256</span> amountToSent</span>,</span></span> address</span> destinationAddress</span>,</span></span> bytes</span> memory</span> signature</span></span> )</span> public</span> pure</span> returns</span> (</span>bool</span>)</span>;</span></span></code></pre> This function is used to verify the signature of the owner. It checks if the signature corresponds to the provided parameters and the owner's address. The parameter _signer</code> is the address of the owner who signed the proposal. The parameter tokenAddress</code> is the address of the token which should be transferred. The parameter amountToSent</code> is the amount which should be transferred to the desired destination address. The parameter destinationAddress</code> defines the receiver of the defined token. The parameter signature</code> is the signed message which only includes the hash of the proposal.</p> This function can be called by the owner to verify the signature before forwarding it to the paymentProcessor / transactionProvider. Also this function should be called within the completeTransaction</code> function to ensure that the signature is valid before executing the transfer.</p> Summary</h5> The interface ITokenStorage.sol</code>:</p> interface</span> ITokenStorage</span> {</span></span> event</span> TransactionProposed</span>(</span>uint256</span> hash</span>)</span>;</span></span> event</span> TransactionCompleted</span>(</span>uint256</span> hash</span>)</span>;</span></span> event</span> FallbackScenarioExecuted</span>(</span>address</span> tokenAddress</span>)</span>;</span></span> </span> function</span> proposeTransaction</span>(</span>address</span> tokenAddress</span>,</span> uint256</span> amountToSent</span>,</span> address</span> destinationAddress</span>)</span> external</span>;</span></span> function</span> completeTransaction</span>(</span>uint256</span> hash</span>,</span> bytes</span> memory</span> signature</span>)</span> external</span>;</span></span> function</span> sendFundsToOwner</span>(</span>address</span> tokenAddress</span>)</span> external</span>;</span></span> }</span></span></code></pre>Rationale</h2> tbd </p> Backwards Compatibility</h2> No backward compatibility issues found.</p> Security Considerations</h2> Needs discussion. </p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> DomainKeys Identified Mail (DKIM) Registry 2025-06-11T00:00:00+00:00 Abstract</h2> This EIP proposes a standard interface for registering and validating DomainKeys Identified Mail (DKIM) public key hashes on the Ethereum blockchain. The interface allows domain owners to register their DKIM public key hashes and enables third parties to verify the validity of these hashes.</p> The registry operates by storing hashes of both domain names and DKIM public keys, creating a mapping that enables on-chain verification of DKIM signatures. Domain owners register their DKIM public key hashes by extracting the public key from their DNS TXT records (as specified in RFC 6376</a>), computing the hash, and submitting it to the registry. DKIM clients can then query the registry to verify that a given public key hash is authorized for a specific domain, enabling trustless email ownership verification for applications such as account abstraction and social recovery mechanisms.</p> Motivation</h2> With the growing adoption of Account Abstraction ERC-4337</a> and the emergence of ZK Email Technology, there is a need for a standardized way to verify email ownership on-chain. This EIP provides a crucial building block for these technologies by enabling the verification of DKIM signatures through on-chain registries.</p> This standard enables several important use cases:</p> Account Abstraction</strong>: When combined with zkEmail, this registry enables email-based account abstraction. Users can prove ownership of their email address through DKIM signatures, allowing them to: Create and manage smart contract wallets</li> Sign transactions using their email credentials</li> Implement social recovery mechanisms</li> </ul> </li> Account Recovery</strong>: The registry facilitates secure account recovery mechanisms: Users can recover their wallet access by on-chain proving email ownership</li> The process is trustless and secure due to the cryptographic nature of DKIM</li> </ul> </li> </ol> Specification</h2> 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.</p> Interface</h3> pragma</span> solidity</span> ^0.8.25</span>;</span></span> ///</span> @title</span> ERC-</span>XXX</span> DKIM Registry Interface</span></span> ///</span> @dev</span> See https://eips.ethereum.org/EIPS/eip-</span>xxx</span></span> ///</span> Note</span>: the ERC-165 identifier for this interface is 0xdee3d600.</span></span> interface</span> IDKIMRegistry</span> {</span></span> event</span> KeyHashRegistered</span>(</span>bytes32</span> domainHash</span>, </span>bytes32</span> keyHash</span>)</span>;</span></span> event</span> KeyHashRevoked</span>(</span>bytes32</span> domainHash</span>)</span>;</span></span> function</span> isKeyHashValid</span>(</span></span> bytes32</span> domainHash</span>,</span></span> bytes32</span> keyHash</span></span> )</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> }</span></span></code></pre>Domain Hash</h3> The domainHash</code> parameter MUST be the hash of the lowercase domain name or subdomain name. For example:</p> For the domain "example.com" using keccak256:</li> </ul> domainHash </span>=</span> keccak256</span>(</span>bytes</span>(</span>"example.com"</span>)</span>)</span></span></code></pre> For the subdomain "mail.example.com" using keccak256:</li> </ul> domainHash </span>=</span> keccak256</span>(</span>bytes</span>(</span>"mail.example.com"</span>)</span>)</span></span></code></pre> The registry MUST treat each domain and subdomain as a distinct entity. This means that:</p> A key hash registered for "example.com" does not automatically apply to its subdomains</li> Each subdomain can have its own independent DKIM key hash registration</li> The full domain name (including subdomain if present) must be hashed as a single string</li> </ol> Key Hash</h3> The keyHash</code> parameter MUST be a cryptographic hash of the DKIM public key. The public key should be in the standard DKIM format as specified in RFC 6376</a>.</p> Implementations MAY choose any cryptographically secure hash function for computing the key hash. Common choices include keccak256, Poseidon (for zk-friendly applications) or other hash functions.</p> DKIM Public Key Specification</h3> The DKIM public key MUST follow the format specified in RFC 6376. Here are the key requirements:</p> Key Format</strong>:</p> The public key MUST be in the format specified in the DKIM DNS record (p=PUBLIC_KEY)</li> The key MUST be base64 encoded</li> The key MUST NOT include the PEM headers or any other formatting</li> The key MUST be the raw public key data as specified in the DKIM DNS record</li> </ul> </li> Key Requirements</strong>:</p> The key MUST be a valid RSA public key</li> The key MUST be in the format as published in the domain's DNS TXT record</li> The key MUST be the exact value from the p= parameter in the DKIM DNS record</li> The key MUST NOT include any whitespace or line breaks</li> </ul> </li> Key Registration Process</strong>:</p> Obtain the DKIM public key from the domain's DNS TXT record</li> Extract the value from the p= parameter</li> Calculate the hash of the raw public key using the implementation's chosen hash function</li> Register the hash in the DKIM registry</li> </ol> </li> Key Validation</strong>:</p> The registry MUST verify that the provided key hash corresponds to a valid DKIM public key</li> The key MUST be in the correct format as specified in RFC 6376</li> The key MUST be the exact value as published in the domain's DNS record</li> </ul> </li> Example with keccak256</strong>:</p> Given the following DKIM DNS record from RFC 6376:</p> $ORIGIN _domainkey.example.org.</span></span> brisbane IN TXT ("v=DKIM1; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQ"</span></span> "KBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYt"</span></span> "IxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v"</span></span> "/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhi"</span></span> "tdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB")</span></span> ```</span></span></code></pre> The process to register this key would be:</p> Extract the public key value from the p= parameter:</li> </ol> MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB</span></span></code></pre></li> Calculate the keccak256 hash of the public key:</p> bytes32</span> keyHash </span>=</span> keccak256</span>(</span>bytes</span>(</span>"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB"</span>)</span>)</span>;</span></span></code></pre> Calculate the domain hash:</li> </ol> bytes32</span> domainHash </span>=</span> keccak256</span>(</span>bytes</span>(</span>"example.org"</span>)</span>)</span>;</span></span></code></pre> Register the key hash in the registry:</li> </ol> registry</span>.</span>setKeyHash</span>(</span>domainHash</span>,</span> keyHash</span>)</span>;</span></span></code></pre></li> </ol> Events</h3> KeyHashRegistered</h4> This event MUST be emitted when a new DKIM public key hash is registered for a domain.</p> event</span> KeyHashRegistered</span>(</span>bytes32</span> domainHash</span>, </span>bytes32</span> keyHash</span>)</span></span></code></pre>KeyHashRevoked</h4> This event MUST be emitted when a DKIM public key hash is revoked for a domain.</p> event</span> KeyHashRevoked</span>(</span>bytes32</span> domainHash</span>)</span></span></code></pre>Functions</h3> isKeyHashValid</h4> This function MUST return true</code> if the provided key hash is valid for the given domain hash, and false</code> otherwise.</p> function</span> isKeyHashValid</span>(</span></span> bytes32</span> domainHash</span>,</span></span> bytes32</span> keyHash</span></span> )</span> external</span> view</span> returns</span> (</span>bool</span>)</span></span></code></pre>Rationale</h2> The interface is designed to be simple and focused on the core functionality of DKIM public key hash registration and validation. The use of keccak256 hashing for both domain names and public keys ensures consistent and secure handling of the data.</p> The events allow for efficient tracking of key registrations and revocations, which is important for maintaining the integrity of the registry.</p> Backwards Compatibility</h2> This EIP introduces a new interface and does not affect existing contracts or standards.</p> Reference Implementation</h2> pragma</span> solidity</span> ^0.8.0</span>;</span></span> import</span> "@openzeppelin/contracts/access/Ownable.sol"</span>;</span></span> import</span> "./interfaces/IDKIMRegistry.sol"</span>;</span></span> contract</span> DKIMRegistry</span> is</span> IDKIMRegistry</span>, </span>Ownable</span> {</span></span> constructor</span>(</span>address</span> _owner</span>)</span> Ownable</span>(</span>_owner) </span>{</span> }</span></span> //</span> Mapping from hashed domain name to DKIM public key hash to enabled</span></span> mapping</span>(</span>bytes32</span> =></span> mapping</span>(</span>bytes32</span> =></span> bool</span>)</span>)</span> private</span> _keyHashes</span>;</span></span> /*</span></span> </span>@notice</span> Checks if a DKIM key hash is valid for a given domain</span></span> * </span>@param</span> domainHash</span> The hash of the domain name</span></span> * </span>@param</span> keyHash</span> The hash of the DKIM public key</span></span> * </span>@return</span> bool</span> True if the key hash is valid for the domain, false otherwise</span></span> /</span></span> function</span> isKeyHashValid</span>(</span></span> bytes32</span> domainHash</span>,</span></span> bytes32</span> keyHash</span></span> )</span> public</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span> return</span> _keyHashes</span>[</span>domainHash</span>]</span>[</span>keyHash</span>]</span>;</span></span> }</span></span> /</span></span> </span>@notice</span> Sets a DKIM key hash for a domain</span></span> * </span>@param</span> domainHash</span> The hash of the domain name</span></span> * </span>@param</span> keyHash</span> The hash of the DKIM public key to register</span></span> * </span>@dev</span> Only callable by the contract owner</span></span> * </span>@dev</span> Cannot set zero hash as a valid key hash</span></span> /</span></span> function</span> setKeyHash</span>(</span></span> bytes32</span> domainHash</span>,</span></span> bytes32</span> keyHash</span></span> )</span> public</span> onlyOwner</span> {</span></span> require</span>(</span>keyHash </span>!=</span> bytes32</span>(</span>0</span>)</span>,</span> "cannot set zero hash"</span>)</span>;</span></span> _keyHashes</span>[</span>domainHash</span>]</span>[</span>keyHash</span>]</span> =</span> true</span>;</span></span> emit</span> KeyHashRegistered</span>(</span>domainHash</span>,</span> keyHash</span>)</span>;</span></span> }</span></span> /</span></span> </span>@notice</span> Sets multiple DKIM key hashes for a domain in a single transaction</span></span> * </span>@param</span> domainHash</span> The hash of the domain name</span></span> * </span>@param</span> keyHashes</span> Array of DKIM public key hashes to register</span></span> * </span>@dev</span> Only callable by the contract owner</span></span> * </span>@dev</span> Array must not be empty</span></span> * </span>@dev</span> Each key hash must not be zero</span></span> /</span></span> function</span> setKeyHashes</span>(</span></span> bytes32</span> domainHash</span>,</span></span> bytes32</span>[</span>]</span> memory</span> keyHashes</span></span> )</span> public</span> onlyOwner</span> {</span></span> require</span>(</span>keyHashes</span>.</span>length </span>></span> 0</span>,</span> "empty array"</span>)</span>;</span></span> for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> keyHashes</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span> setKeyHash</span>(</span>domainHash</span>,</span> keyHashes</span>[</span>i</span>]</span>)</span>;</span></span> }</span></span> }</span></span> /</span></span> </span>@notice</span> Revokes a DKIM key hash for a domain</span></span> * </span>@param</span> domainHash</span> The hash of the domain name</span></span> * </span>@param</span> keyHash</span> The hash of the DKIM public key to revoke</span></span> * </span>@dev</span> Only callable by the contract owner</span></span> * </span>@dev</span> Sets the key hash mapping to false, effectively revoking it</span></span> /</span></span> function</span> revokeKeyHash</span>(</span>bytes32</span> domainHash</span>,</span> bytes32</span> keyHash</span>)</span> public</span> onlyOwner</span> {</span></span> delete</span> _keyHashes</span>[</span>domainHash</span>]</span>[</span>keyHash</span>]</span>;</span></span> emit</span> KeyHashRevoked</span>(</span>domainHash</span>)</span>;</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> Domain owners must ensure they have control over their private keys and domain names.</li> The registry implementation should include proper access control mechanisms to prevent unauthorized registrations.</li> The registry should implement a mechanism to handle key rotation and revocation.</li> Implementations should consider rate limiting to prevent spam registrations.</li> Registries should select the domainHash</code> and keyHash</code> algorithms carefully. Upgrading the hash function must be thoughtfully planned.</li> </ol> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> uRWA - Universal Real World Asset Interface 2025-06-10T00:00:00+00:00 Abstract</h2> This EIP proposes the Universal RWA (uRWA) standard, a set of interfaces for tokenized Real World Assets (RWAs) such as securities, real estate, commodities, or other physical/financial assets on the blockchain.</p> Real World Assets often require regulatory compliance features not found in standard tokens, including the ability to freeze assets, perform enforcement transfers for legal compliance, and restrict transfers to authorized users. The uRWA standard extends common token standards like ERC-20</a>, ERC-721</a> or ERC-1155</a> by introducing essential compliance functions while remaining minimal and not opinionated about specific implementation details.</p> This enables DeFi protocols and applications to interact with tokenized real-world assets in a standardized way, knowing they can check transfer permissions, whether users are allowed to interact, handle frozen assets appropriately, and integrate with compliant RWA tokens regardless of the underlying asset type or internal compliance logic. It also adopts ERC-165</a> for introspection.</p> Motivation</h2> Real World Assets (RWAs) represent a significant opportunity to bridge traditional finance and decentralized finance (DeFi). By tokenizing assets like real estate, corporate bonds, commodities, art, or securities, we can unlock benefits such as fractional ownership, programmable compliance, enhanced liquidity through secondary markets for traditionally illiquid assets and integration with decentralized protocols.</p> However, tokenizing real world assets introduces regulatory requirements often absent in purely digital assets, such as allowlists for users, transfer restrictions, asset freezing, or law enforcement rules. Existing token standards like ERC-20</a>, ERC-721</a> and ERC-1155</a> lack the inherent structure to address these compliance needs directly within the standard itself.</p> Attempts at defining universal RWA standards historically imposed unnecessary complexity and gas overhead for simpler use cases that do not require the full spectrum of features like granular role-based access control, mandatory on-chain whitelisting, specific on-chain identity solutions, or metadata handling solutions mandated by the standard.</p> Additionally, the broad spectrum of RWA classes inherently suggests the need to move away from a one-size-fits-all solution. This means a minimalistic approach, unopinionated features list, and maximally compatible design have been kept in mind as design goals.</p> The uRWA standard seeks a more refined balance by defining an essential interface, establishing a common ground for interaction regarding compliance and control, without dictating the underlying implementation mechanisms. This allows core token implementations to remain lean while providing standard functions for RWA-specific interactions.</p> The final goal is to build composable DeFi around RWAs, providing the same interface when dealing with compliance and regulation.</p> Specification</h2> The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", and "MAY" in this document are to be interpreted as described in RFC 2119 and RFC 8174.</p> The following defines the standard interfaces for an ERC-7943</a> token contract, which MUST extend from one base token interface such as ERC-20</a>, ERC-721</a> or ERC-1155</a>:</p> ///</span> @notice</span> Interface for ERC-20 based implementations.</span></span> interface</span> IERC7943Fungible</span> is</span> IERC165</span> {</span></span> ///</span> @notice</span> Emitted when tokens are taken from one address and transferred to another.</span></span> ///</span> @param</span> from</span> The address from which tokens were taken.</span></span> ///</span> @param</span> to</span> The address to which seized tokens were transferred.</span></span> ///</span> @param</span> amount</span> The amount seized.</span></span> event</span> ForcedTransfer</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> amount</span>)</span>;</span></span> </span> ///</span> @notice</span> Emitted when `setFrozenTokens` is called, changing the frozen `amount` of tokens for `account`.</span></span> ///</span> @param</span> account</span> The address of the account whose tokens are being frozen.</span></span> ///</span> @param</span> amount</span> The amount of tokens frozen after the change.</span></span> event</span> Frozen</span>(</span>address</span> indexed</span> account</span>, </span>uint256</span> amount</span>)</span>;</span></span> </span> ///</span> @notice</span> Error reverted when an account is not allowed to transact. </span></span> ///</span> @param</span> account</span> The address of the account which is not allowed for transfers.</span></span> error</span> ERC7943CannotTransact</span>(</span>address</span> account</span>)</span>;</span></span> </span> ///</span> @notice</span> Error reverted when a transfer is not allowed according to internal rules. </span></span> ///</span> @param</span> from</span> The address from which tokens are being sent.</span></span> ///</span> @param</span> to</span> The address to which tokens are being sent.</span></span> ///</span> @param</span> amount</span> The amount sent.</span></span> error</span> ERC7943CannotTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> amount</span>)</span>;</span></span> </span> ///</span> @notice</span> Error reverted when a transfer is attempted from `account` with an `amount` less than or equal to its balance, but greater than its unfrozen balance.</span></span> ///</span> @param</span> account</span> The address holding the tokens.</span></span> ///</span> @param</span> amount</span> The amount being transferred.</span></span> ///</span> @param</span> unfrozen</span> The amount of tokens that are unfrozen and available to transfer.</span></span> error</span> ERC7943InsufficientUnfrozenBalance</span>(</span>address</span> account</span>,</span> uint256</span> amount</span>,</span> uint256</span> unfrozen</span>)</span>;</span></span> </span> ///</span> @notice</span> Takes tokens from one address and transfers them to another.</span></span> ///</span> @dev</span> Requires specific authorization. Used for regulatory compliance or recovery scenarios.</span></span> ///</span> @param</span> from</span> The address from which `amount` is taken.</span></span> ///</span> @param</span> to</span> The address that receives `amount`.</span></span> ///</span> @param</span> amount</span> The amount to force transfer.</span></span> ///</span> @return</span> result</span> True if the transfer executed correctly. Reverts on failure.</span></span> function</span> forcedTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> amount</span>)</span> external</span> returns</span>(</span>bool</span> result</span>)</span>;</span></span> </span> ///</span> @notice</span> Changes the frozen status of `amount` tokens belonging to `account`.</span></span> ///</span> This overwrites the current value, similar to an `approve` function.</span></span> ///</span> @dev</span> Requires specific authorization. Frozen tokens cannot be transferred by the account.</span></span> ///</span> @param</span> account</span> The address of the account whose tokens are to be frozen.</span></span> ///</span> @param</span> amount</span> The amount of tokens to freeze. It can be greater than account balance.</span></span> ///</span> @return</span> result</span> True if the freezing executed correctly. Reverts on failure.</span></span> function</span> setFrozenTokens</span>(</span>address</span> account</span>,</span> uint256</span> amount</span>)</span> external</span> returns</span>(</span>bool</span> result</span>)</span>;</span></span> </span> ///</span> @notice</span> Checks if a specific account is allowed to transact according to token rules.</span></span> ///</span> @dev</span> This is often used for allowlist/KYC/KYB/AML checks.</span></span> ///</span> @param</span> account</span> The address to check.</span></span> ///</span> @return</span> allowed</span> True if the account is allowed, false otherwise.</span></span> function</span> canTransact</span>(</span>address</span> account</span>)</span> external</span> view</span> returns</span> (</span>bool</span> allowed</span>)</span>;</span></span> </span> ///</span> @notice</span> Checks the frozen status/amount.</span></span> ///</span> @param</span> account</span> The address of the account.</span></span> ///</span> @dev</span> It could return an amount higher than the account's balance.</span></span> ///</span> @return</span> amount</span> The amount of tokens currently frozen for `account`.</span></span> function</span> getFrozenTokens</span>(</span>address</span> account</span>)</span> external</span> view</span> returns</span> (</span>uint256</span> amount</span>)</span>;</span></span> </span> ///</span> @notice</span> Checks if a transfer is currently possible according to token rules. It enforces validations on the frozen tokens.</span></span> ///</span> @dev</span> This can involve checks like allowlists, blocklists, transfer limits and other policy-defined restrictions.</span></span> ///</span> @param</span> from</span> The address sending tokens.</span></span> ///</span> @param</span> to</span> The address receiving tokens. </span></span> ///</span> @param</span> amount</span> The amount being transferred.</span></span> ///</span> @return</span> allowed</span> True if the transfer is allowed, false otherwise.</span></span> function</span> canTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> amount</span>)</span> external</span> view</span> returns</span> (</span>bool</span> allowed</span>)</span>;</span></span> }</span></span> </span> ///</span> @notice</span> Interface for ERC-721 based implementations.</span></span> interface</span> IERC7943NonFungible</span> is</span> IERC165</span> {</span></span> ///</span> @notice</span> Emitted when `tokenId` is taken from one address and transferred to another.</span></span> ///</span> @param</span> from</span> The address from which `tokenId` is taken.</span></span> ///</span> @param</span> to</span> The address to which seized `tokenId` is transferred.</span></span> ///</span> @param</span> tokenId</span> The ID of the token being transferred.</span></span> event</span> ForcedTransfer</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> tokenId</span>)</span>;</span></span> </span> ///</span> @notice</span> Emitted when `setFrozenTokens` is called, changing the frozen status of `tokenId` for `account`.</span></span> ///</span> @param</span> account</span> The address of the account whose `tokenId` is subjected to freeze/unfreeze.</span></span> ///</span> @param</span> tokenId</span> The ID of the token subjected to freeze/unfreeze.</span></span> ///</span> @param</span> frozenStatus</span> Whether `tokenId` has been frozen or unfrozen.</span></span> event</span> Frozen</span>(</span>address</span> indexed</span> account</span>, </span>uint256</span> indexed</span> tokenId</span>, </span>bool</span> indexed</span> frozenStatus</span>)</span>;</span></span> </span> ///</span> @notice</span> Error reverted when an account is not allowed to transact. </span></span> ///</span> @param</span> account</span> The address of the account which is not allowed for transfers.</span></span> error</span> ERC7943CannotTransact</span>(</span>address</span> account</span>)</span>;</span></span> </span> ///</span> @notice</span> Error reverted when a transfer is not allowed according to internal rules. </span></span> ///</span> @param</span> from</span> The address from which tokens are being sent.</span></span> ///</span> @param</span> to</span> The address to which tokens are being sent.</span></span> ///</span> @param</span> tokenId</span> The id of the token being sent.</span></span> error</span> ERC7943CannotTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> tokenId</span>)</span>;</span></span> </span> ///</span> @notice</span> Error reverted when a transfer is attempted from `account` with a `tokenId` which has been previously frozen.</span></span> ///</span> @param</span> account</span> The address holding the token with `tokenId`.</span></span> ///</span> @param</span> tokenId</span> The ID of the token being frozen and unavailable to be transferred. </span></span> error</span> ERC7943InsufficientUnfrozenBalance</span>(</span>address</span> account</span>,</span> uint256</span> tokenId</span>)</span>;</span></span> </span> ///</span> @notice</span> Takes `tokenId` from one address and transfers it to another.</span></span> ///</span> @dev</span> Requires specific authorization. Used for regulatory compliance or recovery scenarios.</span></span> ///</span> @param</span> from</span> The address from which `tokenId` is taken.</span></span> ///</span> @param</span> to</span> The address that receives `tokenId`.</span></span> ///</span> @param</span> tokenId</span> The ID of the token being transferred.</span></span> ///</span> @return</span> result</span> True if the transfer executed correctly. Reverts on failure.</span></span> function</span> forcedTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> tokenId</span>)</span> external</span> returns</span>(</span>bool</span> result</span>)</span>;</span></span> </span> ///</span> @notice</span> Changes the frozen status of `tokenId` belonging to an `account`.</span></span> ///</span> This overwrites the current value, similar to an `approve` function.</span></span> ///</span> @dev</span> Requires specific authorization. Frozen tokens cannot be transferred by the account.</span></span> ///</span> @param</span> account</span> The address of the account whose tokens are to be frozen.</span></span> ///</span> @param</span> tokenId</span> The ID of the token to freeze.</span></span> ///</span> @param</span> frozenStatus</span> Whether `tokenId` is being frozen or not. </span></span> ///</span> @return</span> result</span> True if the freezing executed correctly. Reverts on failure.</span></span> function</span> setFrozenTokens</span>(</span>address</span> account</span>,</span> uint256</span> tokenId</span>,</span> bool</span> frozenStatus</span>)</span> external</span> returns</span>(</span>bool</span> result</span>)</span>;</span></span> </span> ///</span> @notice</span> Checks if a specific account is allowed to transact according to token rules.</span></span> ///</span> @dev</span> This is often used for allowlist/KYC/KYB/AML checks.</span></span> ///</span> @param</span> account</span> The address to check.</span></span> ///</span> @return</span> allowed</span> True if the account is allowed, false otherwise.</span></span> function</span> canTransact</span>(</span>address</span> account</span>)</span> external</span> view</span> returns</span> (</span>bool</span> allowed</span>)</span>;</span></span> </span> ///</span> @notice</span> Checks the frozen status of a specific `tokenId`.</span></span> ///</span> @dev</span> It could return true even if account does not hold the token.</span></span> ///</span> @param</span> account</span> The address of the account.</span></span> ///</span> @param</span> tokenId</span> The ID of the token.</span></span> ///</span> @return</span> frozenStatus</span> Whether `tokenId` is currently frozen for `account`.</span></span> function</span> getFrozenTokens</span>(</span>address</span> account</span>,</span> uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>bool</span> frozenStatus</span>)</span>;</span></span> </span> ///</span> @notice</span> Checks if a transfer is currently possible according to token rules. It enforces validations on the frozen tokens.</span></span> ///</span> @dev</span> This can involve checks like allowlists, blocklists, transfer limits and other policy-defined restrictions.</span></span> ///</span> @param</span> from</span> The address sending tokens.</span></span> ///</span> @param</span> to</span> The address receiving tokens. </span></span> ///</span> @param</span> tokenId</span> The ID of the token being transferred.</span></span> ///</span> @return</span> allowed</span> True if the transfer is allowed, false otherwise.</span></span> function</span> canTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>bool</span> allowed</span>)</span>;</span></span> }</span></span> </span> ///</span> @notice</span> Interface for ERC-1155 based implementations.</span></span> interface</span> IERC7943MultiToken</span> is</span> IERC165</span> {</span></span> ///</span> @notice</span> Emitted when tokens are taken from one address and transferred to another.</span></span> ///</span> @param</span> from</span> The address from which tokens were taken.</span></span> ///</span> @param</span> to</span> The address to which seized tokens were transferred.</span></span> ///</span> @param</span> tokenId</span> The ID of the token being transferred.</span></span> ///</span> @param</span> amount</span> The amount seized.</span></span> event</span> ForcedTransfer</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> tokenId</span>, </span>uint256</span> amount</span>)</span>;</span></span> </span> ///</span> @notice</span> Emitted when `setFrozenTokens` is called, changing the frozen `amount` of `tokenId` tokens for `account`.</span></span> ///</span> @param</span> account</span> The address of the account whose tokens are being frozen.</span></span> ///</span> @param</span> tokenId</span> The ID of the token being frozen.</span></span> ///</span> @param</span> amount</span> The amount of tokens frozen after the change.</span></span> event</span> Frozen</span>(</span>address</span> indexed</span> account</span>, </span>uint256</span> indexed</span> tokenId</span>, </span>uint256</span> amount</span>)</span>;</span></span> </span> ///</span> @notice</span> Error reverted when an account is not allowed to transact. </span></span> ///</span> @param</span> account</span> The address of the account which is not allowed for transfers.</span></span> error</span> ERC7943CannotTransact</span>(</span>address</span> account</span>)</span>;</span></span> </span> ///</span> @notice</span> Error reverted when a transfer is not allowed according to internal rules. </span></span> ///</span> @param</span> from</span> The address from which tokens are being sent.</span></span> ///</span> @param</span> to</span> The address to which tokens are being sent.</span></span> ///</span> @param</span> tokenId</span> The id of the token being sent.</span></span> ///</span> @param</span> amount</span> The amount sent.</span></span> error</span> ERC7943CannotTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> tokenId</span>,</span> uint256</span> amount</span>)</span>;</span></span> </span> ///</span> @notice</span> Error reverted when a transfer is attempted from `account` with an `amount` of `tokenId` less than or equal to its balance, but greater than its unfrozen balance.</span></span> ///</span> @param</span> account</span> The address holding the `amount` of `tokenId` tokens.</span></span> ///</span> @param</span> tokenId</span> The ID of the token being transferred. </span></span> ///</span> @param</span> amount</span> The amount of `tokenId` tokens being transferred.</span></span> ///</span> @param</span> unfrozen</span> The amount of tokens that are unfrozen and available to transfer.</span></span> error</span> ERC7943InsufficientUnfrozenBalance</span>(</span>address</span> account</span>,</span> uint256</span> tokenId</span>,</span> uint256</span> amount</span>,</span> uint256</span> unfrozen</span>)</span>;</span></span> </span> ///</span> @notice</span> Takes tokens from one address and transfers them to another.</span></span> ///</span> @dev</span> Requires specific authorization. Used for regulatory compliance or recovery scenarios.</span></span> ///</span> @param</span> from</span> The address from which `amount` is taken.</span></span> ///</span> @param</span> to</span> The address that receives `amount`.</span></span> ///</span> @param</span> tokenId</span> The ID of the token being transferred.</span></span> ///</span> @param</span> amount</span> The amount to force transfer.</span></span> ///</span> @return</span> result</span> True if the transfer executed correctly. Reverts on failure.</span></span> function</span> forcedTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> tokenId</span>,</span> uint256</span> amount</span>)</span> external</span> returns</span>(</span>bool</span> result</span>)</span>;</span></span> </span> ///</span> @notice</span> Changes the frozen status of `amount` of `tokenId` tokens belonging to an `account`.</span></span> ///</span> This overwrites the current value, similar to an `approve` function.</span></span> ///</span> @dev</span> Requires specific authorization. Frozen tokens cannot be transferred by the account.</span></span> ///</span> @param</span> account</span> The address of the account whose tokens are to be frozen.</span></span> ///</span> @param</span> tokenId</span> The ID of the token to freeze.</span></span> ///</span> @param</span> amount</span> The amount of tokens to freeze. It can be greater than account balance.</span></span> ///</span> @return</span> result</span> True if the freezing executed correctly. Reverts on failure.</span></span> function</span> setFrozenTokens</span>(</span>address</span> account</span>,</span> uint256</span> tokenId</span>,</span> uint256</span> amount</span>)</span> external</span> returns</span>(</span>bool</span> result</span>)</span>;</span></span> </span> ///</span> @notice</span> Checks if a specific account is allowed to transact according to token rules.</span></span> ///</span> @dev</span> This is often used for allowlist/KYC/KYB/AML checks.</span></span> ///</span> @param</span> account</span> The address to check.</span></span> ///</span> @return</span> allowed</span> True if the account is allowed, false otherwise.</span></span> function</span> canTransact</span>(</span>address</span> account</span>)</span> external</span> view</span> returns</span> (</span>bool</span> allowed</span>)</span>;</span></span> </span> ///</span> @notice</span> Checks the frozen status/amount of a specific `tokenId`.</span></span> ///</span> @dev</span> It could return an amount higher than the account's balance.</span></span> ///</span> @param</span> account</span> The address of the account.</span></span> ///</span> @param</span> tokenId</span> The ID of the token.</span></span> ///</span> @return</span> amount</span> The amount of `tokenId` tokens currently frozen for `account`.</span></span> function</span> getFrozenTokens</span>(</span>address</span> account</span>,</span> uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>uint256</span> amount</span>)</span>;</span></span> </span> ///</span> @notice</span> Checks if a transfer is currently possible according to token rules. It enforces validations on the frozen tokens.</span></span> ///</span> @dev</span> This can involve checks like allowlists, blocklists, transfer limits and other policy-defined restrictions.</span></span> ///</span> @param</span> from</span> The address sending tokens.</span></span> ///</span> @param</span> to</span> The address receiving tokens. </span></span> ///</span> @param</span> tokenId</span> The ID of the token being transferred.</span></span> ///</span> @param</span> amount</span> The amount being transferred.</span></span> ///</span> @return</span> allowed</span> True if the transfer is allowed, false otherwise.</span></span> function</span> canTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> tokenId</span>,</span> uint256</span> amount</span>)</span> external</span> view</span> returns</span> (</span>bool</span> allowed</span>)</span>;</span></span> }</span></span></code></pre>canTransact</code>, canTransfer</code> and getFrozenTokens</code></h3> These provide views into the implementing contract's compliance, transfer policy logic and freezing status. These functions:</p> MUST NOT revert.</p> </li> MUST NOT change the storage of the contract.</p> </li> MAY depend on context (e.g., current timestamp, block number or msg.sender</code>).</p> </li> The canTransfer</code></p> MUST validate that the amount</code> being transferred doesn't exceed the unfrozen amount (which is the difference between the current balance and the frozen balance).</li> MUST perform a canTransact</code> check on the from</code> and to</code> parameters. An important documentation note is that ERC-3643</a> doesn't perform a canTransact</code> check within canTransfer</code> as required.</li> MUST return false in general, if any permissioned rule would prevent a given transfer from succeeding. A transfer refers to any operation that emits the token’s canonical transfer event. A permissioned check can be a pausing mechanism, a call to canTransact</code> or anything else that requires privileged actors.</li> </ul> </li> getFrozenTokens</code> will return the absolute frozen amount, which MAY exceed the account's current balance. In ERC-721</a> tokens, it MAY return true even if the account does not hold the token.</p> </li> </ul> forcedTransfer</code></h3> This function provides a standard mechanism for forcing a transfer from a from</code> to a to</code> address. The function:</p> MUST directly manipulate balances or ownership to transfer the asset from from</code> to to</code> either by transferring or burning from from</code> and minting to to</code>.</li> MUST be restricted in access.</li> MUST perform necessary validation checks (e.g., sufficient balance/ownership of a specific token).</li> MUST emit both the standard transfer event (from the base standard) and the ForcedTransfer</code> event.</li> In single-party permissioned contexts: It MAY bypass the canTransfer</code> checks. If this happens, and the transfer involves tokens that are currently counted as frozen, it MUST unfreeze the assets first and emit a Frozen</code> event before the underlying base token transfer event reflecting the change. Having the unfrozen amount changed before the actual transfer is critical for tokens that might be susceptible to reentrancy attacks doing external checks on recipients as it is the case for ERC-721</a> and ERC-1155</a> tokens.</li> It SHOULD at least perform a canTransact</code> check on the to</code> parameter to ensure compliance.</li> </ul> </li> In multi-party permissioned contexts: It SHOULD perform the canTransfer</code> checks and SHOULD NOT bypass the frozen constraints.</li> </ul> </li> MUST revert in cases where validations and/or canTransact</code> checks return false or fail.</li> </ul> setFrozenTokens</code></h3> It provides a way to freeze or unfreeze assets held by a specific account. This is useful for temporary lock mechanisms. This function:</p> MUST emit the Frozen</code> event.</li> MUST be restricted in access.</li> MUST allow freezing more assets than those held. This allows for future balances withholding.</li> MUST revert in cases of logical issues or validation checks failure.</li> </ul> Additional Specifications</h3> The contract MUST implement the ERC-165</a> supportsInterface</code> function and MUST return true for the bytes4</code> value (representing the interfaceId</code>):</p> 0x29388973</code> for the fungible interface.</li> 0xa8fdc849</code> for the non-fungible interface.</li> 0x5627c61a</code> for the multi token interface.</li> </ul> Implementations of these interfaces MUST implement the necessary functions of their chosen base standard (e.g., ERC-20</a> for the fungible interface, ERC-721</a> for the non-fungible interface and ERC-1155</a> for the multi token interface) and MUST also restrict access to sensitive functions like forcedTransfer</code> and setFrozenTokens</code> using an appropriate access control mechanism (e.g., onlyOwner</code>, Role-Based Access Control). The specific mechanism is NOT mandated by this interface standard.</p> Implementations MUST ensure their transfer methods exhibit the following behavior:</p> Public transfers</strong> (transfer</code>, transferFrom</code>, safeTransferFrom</code>, etc.) MUST NOT succeed in cases in which canTransfer</code> or canTransact</code> would return false</code> for either one or both from</code> and to</code> addresses.</li> Minting</strong> in permissionless contexts (e.g., public mint</code> functions) MUST NOT succeed for accounts where canTransact</code> on the recipient would return false</code>. In permissioned contexts (e.g., authorized minting by privileged roles), minting SHOULD respect canTransact</code> checks on the recipient, though implementations MAY bypass these checks when necessary for operational or compliance reasons.</li> Burning</strong> in permissionless contexts (e.g., public burn</code> functions) MUST respect canTransfer</code> check, MUST respect the canTransact</code> check on the token holder and MUST NOT allow burning more assets than the unfrozen amount. In permissioned contexts (e.g., authorized burning by privileged roles), burning MAY succeed for accounts where canTransact</code> on the token holder would return false</code>, and MAY burn more assets than the unfrozen amount, in which case the contract MUST update the frozen status accordingly and emit a Frozen</code> event before the underlying base token transfer event.</li> </ul> The ERC7943CannotTransact</code>/ERC7943CannotTransfer</code> errors MAY be used as a general revert mechanism whenever internal calls to canTransact</code>/canTransfer</code> return false. They MAY be replaced by more specific errors depending on the custom checks performed inside those calls, or simply not used.</p> In general, the standard prioritizes error specificity, meaning that specific errors such as ERC7943InsufficientUnfrozenBalance</code> SHOULD be thrown when applicable. The ERC7943InsufficientUnfrozenBalance</code> error SHOULD be triggered when a transfer is attempted from account</code> with an amount</code> less than or equal to its balance, but greater than its unfrozen balance or with a tokenId</code> which is currently frozen. If the amount</code> is greater than the whole balance or the tokenId</code> is not owned by the account</code>, unrelated from the frozen amount, more specific errors from the base standard SHOULD be used instead.</p> Rationale</h2> Minimalism:</strong> Defines only the essential functions (forcedTransfer</code>, setFrozenTokens</code>, canTransact</code>, canTransfer</code>, getFrozenTokens</code>) and associated events/errors needed for common RWA compliance and control patterns, avoiding mandated complexity or opinionated features. The reason to introduce specific errors (ERC7943CannotTransact</code>, ERC7943CannotTransfer</code> and ERC7943InsufficientUnfrozenBalance</code>) is to provide completeness with the introduced functionalities (canTransact</code>, canTransfer</code> and getFrozenTokens</code>). As dictated in the specifications, error specificity is prioritized, leaving space for implementations to accommodate more explicit errors. Regarding the events Frozen</code> and ForcedTransfer</code>, the reason for their existence is to signal uncommon</em> transfers (like in forcedTransfer</code>) but also to help off-chain indexers to correctly keep track and account for asset seizures and freezing. As mentioned in the specifications, the order in which these events are emitted in relation to the base token contract events is important in practice and merits special attention.</li> Flexible compliance:</strong> Provides standard view functions (canTransact</code>, canTransfer</code>, getFrozenTokens</code>) for compliance checks without dictating how</em> those checks are implemented internally by the token contract. This allows diverse compliance strategies.</li> Compatibility:</strong> Designed as an interface layer compatible with existing base standards like ERC-20</a>, ERC-721</a> and ERC-1155</a>. Implementations extend from ERC-7943</a> alongside their base standard interface. Additionally, with the adopted naming conventions, automatic backward compatibility is achieved with already existing standards like ERC-3643</a> and ERC-7518</a>.</li> Essential enforcement rules:</strong> Includes forcedTransfer</code> and setFrozenTokens</code> as standard functions, acknowledging their importance for regulatory enforcement in the RWA space, distinct from standard transfers. Mandates access control for this sensitive function. To maintain a lean EIP, a single setFrozenTokens</code> function (which overwrites the frozen asset quantity) and one Frozen</code> event were favored over distinct freeze</code>/unfreeze</code> functions and events.</li> ERC-165</a>:</strong> Ensures implementing contracts can signal support for this interface.</li> </ul> As an example, an AMM pool or a lending protocol can integrate with ERC-7943</a> based ERC-20</a> tokens by calling canTransact</code> or canTransfer</code> to handle these assets in a compliant manner. Enforcement actions like forcedTransfer</code> and setFrozenTokens</code> can either be called by third party entities or be integrated by external protocols to allow for automated and programmable compliance. Users can then expand these tokens with additional features to fit the specific needs of individual asset types, either with on-chain identity systems, historical balances tracking for dividend distributions, semi-fungibility with token metadata, and other custom functionalities.</p> Extensibility</h3> While this ERC provides the necessary primitives for regulated assets, any additional feature can be added through extensions. Few examples:</p> If for any administrative function like setFrozenTokens</code> it is necessary to attach a proof to the call, the contract can have a function that batches operations like:</li> </ol> contract</span> TokenWithLegalProofs</span> is</span> IERC7943MultiToken</span> {</span></span> .</span>.</span>.</span></span> </span> function</span> setFrozenTokensWithProof</span>(</span>address</span> account</span>,</span> uint256</span> tokenId</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> legalProof</span>)</span> external</span> onlyOwner</span> returns</span>(</span>bool</span> result</span>)</span> {</span></span> ///</span> do anything with `legalProof`</span></span> return</span> setFrozenTokens</span>(</span>account</span>,</span> tokenId</span>,</span> amount</span>)</span>;</span></span> }</span></span> }</span></span></code></pre> Since the setFrozenTokens</code> function overwrites the absolute frozen amount and given the fact that the standard allows for multiple privileged accounts, some race-conditions might happen. If that's the case, one can build an extension function that works with expected values of amounts frozen, like:</li> </ol> function</span> setFrozenTokensIf</span>(</span>address</span> account</span>,</span> uint256</span> expectedPrev</span>,</span> uint256</span> newAmount</span>)</span> external</span> onlyOwner</span> returns</span>(</span>bool</span> result</span>)</span> {</span></span> require</span>(</span>frozenTokens</span>[</span>account</span>]</span> ==</span> expectedPrev</span>,</span> ERC7943ExpectedValueMismatch</span>(</span>expectedPrev</span>,</span> frozenTokens</span>[</span>account</span>]</span>)</span>)</span>;</span></span> return</span> setFrozenTokens</span>(</span>account</span>,</span>newAmount</span>)</span>;</span></span> }</span></span></code></pre> Alternatively, another solution can be using delta amounts:</p> function</span> setFrozenTokensDelta</span>(</span>address</span> account</span>,</span> int256</span> deltaAmount</span>)</span> external</span> onlyOwner</span> returns</span>(</span>bool</span> result</span>)</span> {</span></span> uint256</span> actualValue </span>=</span> frozenTokens</span>[</span>account</span>]</span>;</span></span> if</span>(</span>deltaAmount </span>></span>=</span> 0</span>)</span> actualValue </span>+</span>=</span> uint256</span>(</span>deltaAmount</span>)</span>;</span></span> else</span> {</span></span> uint256</span> sub </span>=</span> uint256</span>(</span>-</span>deltaAmount</span>)</span>;</span></span> require</span>(</span>sub </span><</span>=</span> actualValue</span>,</span> ERC7943ExpectedValueMismatch</span>(</span>sub</span>,</span> actualValue</span>)</span>)</span>;</span></span> actualValue </span>-</span>=</span> sub</span>;</span></span> }</span></span> return</span> setFrozenTokens</span>(</span>account</span>,</span> actualValue</span>)</span>;</span></span> }</span></span></code></pre> Note</em> These helpers reduce accidental overwrites and expand in functionalities but do not prevent same-block conflicting updates or mempool ordering races by different privileged actors.</p> Developers can also perform several operations through the use of multicall</code> patterns similar to the one defined in ERC-6357</a> so that a mix of the given primitives with additional features can be batched in one transaction:</li> </ol> contract</span> ERC7943Fungible</span> is</span> IERC7943Fungible</span>, </span>Multicall</span> {</span></span> //</span> Now any combination of `setFrozenTokens`/`forcedTransfer` </span></span> //</span> coupled with other functionalities like the ones to blacklist/whitelist users</span></span> //</span> can be submitted in one transaction through the use of `multicall` function</span></span> }</span></span></code></pre> Functionalities like pausability can be added on top, either through the use of modifiers or directly within functions implementations:</li> </ol> function</span> canTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> amount</span>)</span> external</span> view</span> returns</span> (</span>bool</span> allowed</span>)</span> {</span></span> if</span>(</span>paused</span>(</span>)</span>)</span> return</span> allowed</span>;</span></span> //</span> ... other checks</span></span> }</span>;</span></span> }</span></span></code></pre>Notes on naming</h3> The naming conventions in this ERC were carefully chosen to establish clarity and semantic consistency within the broader RWA ecosystem while maintaining neutrality and broad applicability.</p> forcedTransfer</code></strong>: This term was selected for its neutrality. While names like confiscation</em>, revocation</em>, or recovery</em> describe specific motivations, forcedTransfer</code> purely denotes the direct action of transferring assets, irrespective of the underlying reason. forcedTransfer</code> was preferred over forceTransfer</code> to maintain backward compatibility with ERC-3643</a>.</li> canTransfer</code></strong>: This name was preferred over isTransferAllowed</code> for consistency with established RWA standards including ERC-3643</a> and ERC-7518</a>. This alignment promotes interoperability and reduces cognitive overhead when working across different RWA tokens.</li> setFrozenTokens</code> / getFrozenTokens</code></strong>: These names were chosen for managing transfer restrictions and align with ERC-3643</a> naming patterns. Frozen</em> was also selected for its general applicability to both fungible (amount-based) and non-fungible (status-based) assets, as terms like amount</em> or asset(s)</em> might not be universally fitting.</li> ERC7943InsufficientUnfrozenBalance</code></strong>: Discussions around insufficient</em> being similar to unavailable</em> arose, where unavailable</em> might have better suggested a temporal condition like a freezing status. However, the term available</em>/unavailable</em> was also overlapping with frozen</em>/unfrozen</em> creating more confusion and duality. Finally, coupling insufficient</em> with the specified unfrozen balance</em> better represents the domain, prefix and subject of the error, according to ERC-6093</a> guidelines.</li> </ul> Backwards Compatibility</h2> This EIP defines a new interface standard and does not alter existing ones like ERC-20</a>, ERC-721</a> and ERC-1155</a>. Standard wallets and explorers can interact with the base token functionality of implementing contracts, subject to the rules enforced by that contract's implementation of canTransact</code>, canTransfer</code> and getFrozenTokens</code> functions. Full support for the ERC-7943</a> functions requires explicit integration.</p> Reference Implementation</h2> Reference implementations of uRWA for ERC-20</a>, ERC-721</a> and ERC-1155</a> token implementations is provided in assets folder. They use the OpenZeppelin library and include an account whitelist and enumerable role-based access control. These examples are provided for educational purposes only and are not audited.</p> Security Considerations</h2> Access Control for forcedTransfer</code> and setFrozenTokens</code>:</strong> The security of the mechanism chosen by the implementer to restrict access to these functions is paramount. Unauthorized access could lead to asset theft. Secure patterns (multisig, timelocks) are highly recommended.</li> Front-run of the setFrozenTokens</code> function:</strong> The setFrozenTokens</code> function might be susceptible to front-running, similar to the approve</code> function of the ERC-20</a>. If the suggestion of allowing freezing more than what an account owns is not followed, a front-run might be an incentive to an account to avoid any attempt of freezing its balance. Additional features to gradually increment or decrement the frozen status MAY be considered for implementation.</li> Implementation Logic:</strong> The correctness of the implementation</em> behind all interface functions is critical. Flaws in this logic could bypass intended transfer restrictions or incorrectly block valid transfers.</li> Standard Contract Security:</strong> Implementations MUST adhere to general smart contract security best practices (reentrancy guards where applicable, checks-effects-interactions, etc.). Specifically in the checks-effects-interactions consideration, implementations need to be aware of tokens having hooks, especially on recipients like in ERC-721</a> or ERC-1155</a>. In such circumstances it might be convenient to adopt reentrancy guards to prevent unwanted executions.</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Proof-based Broadcast in ERC-7786 Gateways 2025-06-06T00:00:00+00:00 Abstract</h2> This document defines standardized broadcasting semantics and attributes for ERC-7786</a> cross-chain messaging that enable trustless message verification through cryptographic proofs. Messages are committed on source chains in verifiable ways, then verified on destination chains using cryptographic proofs of the source chain's state or transaction history. This approach provides cross-chain communication without relying on external validators or bridge operators.</p> Motivation</h2> Cross-chain messaging protocols typically rely on external validators, multisigs, or optimistic mechanisms that introduce trust assumptions and potential points of failure. Cryptographic proofs offer an alternative approach where messages can be verified using the consensus mechanisms and cryptographic commitments of the chains themselves (e.g. storage proofs for EVM chains).</p> However, cryptographic proof verification requires chain-specific routing information, proof data, and verification parameters that are not addressed by the base ERC-7786</a> interface. Additionally, while ERC-7786</a> defines basic broadcasting through "omitted or zeroed" recipient addresses, it does not specify granular broadcasting patterns that enable targeting specific chains or chain types. Enhanced broadcasting semantics enable messages to be sent with varying levels of specificity, from all addresses on a specific chain to all supported infrastructure.</p> This document standardizes these requirements as ERC-7786</a> attributes, enabling cryptographic proof-based messaging within the established cross-chain messaging framework. The specification supports multi-hop verification paths, allowing messages to traverse through multiple intermediary chains when direct verification is not possible.</p> The key benefits of this approach include:</p> Trustless verification</strong>: No external validators or multisigs required. Chains trust their own consensus mechanisms.</li> Universal compatibility</strong>: Works between chains with verifiable state relationships through shared settlement infrastructure or compatible proof systems.</li> Flexible messaging patterns</strong>: Supports both targeted and granular broadcast messaging through standardized semantics, enabling new classes of applications like oracles and intent settlement systems.</li> Composability</strong>: Full integration with existing ERC-7786</a> infrastructure and tooling</li> </ul> Specification</h2> 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.</p> Broadcasting Semantics</h3> ERC-7786</a> defines broadcasting as using "omitted or zeroed" recipient addresses (containing an ERC-7930</a> interoperable address with all fields set to zero). This specification extends that concept to enable granular broadcasting patterns through ERC-7930</a>'s flexible address structure:</p> Broadcasting semantics in this specification extend ERC-7786</a> by allowing:</p> Interoperable addresses with AddressLength</code> set to 0 and specified ChainType</code> and/or ChainReference</code> to broadcast messages to all addresses on a given chain</li> Interoperable addresses with ChainReferenceLength</code> set to 0 and a specified ChainType</code> to broadcast to all chains of a given type</li> Interoperable addresses with all fields set to zero to indicate universal broadcasting to all supported chains and addresses</li> </ul> Receivers of broadcast messages SHOULD validate the source and authenticity of messages according to their own security requirements.</p> Cryptographic Proof Attributes</h3> This specification defines the following ERC-7786</a> attributes for cryptographic proof messaging. Gateways MUST return true if supportsAttribute</code> is called with the selector for supported attributes.</p> route((bytes,bytes,uint256)[])</code></h4> Specifies the verification path from destination to source chain with corresponding proofs and version requirements. Each tuple contains a bytes-encoded address that SHOULD be called for verification of the next chain's state or transaction history, the cryptographic proof required for that verification step, and the expected version of the verification logic (0 means any version is acceptable). The route address MAY invoke other gateways to resend the message to the next hop.</p> When a non-zero version is specified, gateways MUST reject messages if the route address does not support the exact required version (unless 0</code>). Route addresses SHOULD implement version querying mechanisms to enable compatibility checking.</p> The route MUST form a valid path where each step represents a direct relationship between chains that enables state or transaction verification. For multi-hop scenarios, the route creates a chain of trust where each step verifies the next, ultimately establishing the authenticity of the source chain's state. Gateways MUST reject messages with invalid or incomplete proof data.</p> abi</span>.</span>encodeWithSignature</span>(</span>"route((bytes,bytes,uint256)[])"</span>,</span> hops</span>)</span>;</span></span></code></pre>inclusionProof(bytes)</code></h4> The cryptographic proof demonstrating that a specific message exists in the source chain's committed state at a finalized block or transaction. For EVM chains, this would typically be an event inclusion proof or storage proof.</p> ERC-7786</a> receivers MUST validate the cryptographic proof according to the source chain's proof system.</p> abi</span>.</span>encodeWithSignature</span>(</span>"inclusionProof(bytes)"</span>,</span> proofData</span>)</span>;</span></span></code></pre>targetBlock(uint256)</code></h4> Specifies the block number or height on the source chain where the message was committed. For chains that don't use sequential block numbers, this represents the equivalent commitment identifier.</p> ERC-7786</a> receivers MAY validate the target block for freshness or finality requirements according to their security policies. Receivers MAY ignore this attribute if not needed for their use case.</p> When provided, this attribute SHOULD correspond to the block or commitment whose state is proven by the cryptographic proof.</p> abi</span>.</span>encodeWithSignature</span>(</span>"targetBlock(uint256)"</span>,</span> blockNumber</span>)</span>;</span></span></code></pre>Relationship to Existing Proof Protocols</h3> This ERC provides standard attributes that enable protocols like ERC-7888</a> (for EVM storage proofs) and other proof systems to implement ERC-7786</a> gateways without rebuilding their core verification logic. For example, an ERC-7888</a> Broadcaster MAY expose an ERC-7786</a> interface using these attributes while maintaining its existing storage proof architecture. Similarly, other proof systems can implement these same attributes using their native proof mechanisms.</p> Caching</h3> Gateways implementing this specification MAY implement caching mechanisms to optimize repeated proof verifications.</p> Mutability of Message Commitments</h3> Gateways MAY choose to commit messages in ways that cannot be deleted or modified after being set, providing immutability guarantees. While not required by this standard, implementers can use ERC-7201</a> to calculate namespaces for immutable storage locations on EVM chains, or equivalent immutability mechanisms on other chain architectures.</p> Verification Process</h3> In ERC-7786</a>, the payload</code> contains the actual message data to be delivered, while the attributes</code> contain proof metadata that establishes the payload's authenticity. The destination gateway validates the attributes through cryptographic verification, and it MAY cache results for future use.</p> For multihop scenarios, each route step verifies the next chain's state commitment, creating a chain of trust from destination to source. This enables message verification across multiple intermediate chains, similar to systems like ERC-7888</a>'s BlockHashProver chains.</p> Message verification follows these steps:</p> Parse the route</code> and inclusionProof</code> attributes from the message, and optionally targetBlock</code> if provided</li> Validate all required attributes are present and well-formed</li> For each route step, verify block hash transition or equivalent state commitment using the paired proof and validate version requirements if specified (non-zero)</li> Use the inclusionProof</code> to verify that message data exists in the source chain's committed state at the target block obtained from the route verification. The source chain SHOULD correspond to the final validated step in the route verification process</li> Optionally validate the targetBlock</code> for freshness or finality requirements if the attribute is provided and the receiver chooses to validate it</li> Execute the message if all verifications pass</li> </ol> Rationale</h2> This standard extends ERC-7786</a>'s attribute system to add cryptographic proof capabilities without creating new interfaces. This approach maintains compatibility with existing infrastructure while enabling trustless cross-chain verification, allowing implementations to focus on proof verification logic rather than rebuilding messaging infrastructure.</p> Broadcasting and Cryptographic Proofs</h3> ERC-7786</a> natively supports broadcasting through "omitted or zeroed" ERC-7930</a> interoperable addresses. This specification extends that foundation to enable granular broadcasting patterns through ERC-7930</a>'s flexible address structure. Empty address components (AddressLength</code> = 0) allow broadcasting to all addresses on a specific chain, while empty chain references (ChainReferenceLength</code> = 0) enable broadcasting to all chains of a specific type (e.g., all EVM chains via eip155</code> namespace). Universal broadcasting uses fully zeroed addresses as defined in ERC-7786</a>.</p> This multi-level broadcasting approach leverages ERC-7930</a>'s inherent address structure and ERC-7786</a>'s existing broadcast semantics rather than introducing new patterns, ensuring consistency with the cross-chain messaging ecosystem. The granularity enables efficient message distribution patterns: oracle feeds can target specific chains, governance messages can address entire chain families, and emergency notifications can reach all supported infrastructure.</p> Cryptographic proofs provide trustless verification relying only on chain consensus mechanisms. This approach offers universal accessibility, cryptographic guarantees, cost efficiency (gas only on source/destination chains), and enables implicit batching through shared state commitments. Multi-hop routing extends this capability to chains without direct verification relationships.</p> Attribute Design</h3> The two required attributes provide the essential functionality for cryptographic proof verification, while the optional targetBlock</code> attribute enables additional freshness and finality validation when needed. Combining route information into a single tuple maintains type safety while separating proof verification from chain state transitions allows independent optimization. The optional nature of targetBlock</code> provides implementation flexibility without adding unnecessary complexity to basic use cases.</p> Caching</h3> Caching can improve performance by storing verification results for reuse. Since proofs are deterministic, they can be safely cached. This is especially useful for broadcast messages that need multiple verifications. Implementations should cache both block hash transitions and proof verification results, while invalidating the cache when proof infrastructure changes.</p> Mutability of Message Commitments</h3> Proving a commitment that could be deleted or modified may introduce additional security risks. For example, if a message is committed in a way that allows deletion after the message is sent, the proof will still be valid. This is why the specification does not require immutability, but allows gateways to choose to commit messages in immutable ways if they so desire.</p> Backwards Compatibility</h2> This ERC extends ERC-7786</a> through its attribute system and introduces no breaking changes to existing implementations. Gateways that do not support cryptographic proof attributes will simply reject messages containing them, which is the expected behavior for unsupported features.</p> Existing ERC-7786</a> tooling and infrastructure can immediately leverage cryptographic proof messaging without modification, as the base interface remains unchanged.</p> Reference Implementation</h2> Basic Gateway Usage</h3> struct</span> Hop</span> {</span></span> bytes</span> gateway</span>;</span> //</span> bytes-encoded address of the gateway</span></span> bytes</span> proof</span>;</span></span> uint256</span> version</span>;</span> //</span> 0 = any version</span></span> }</span></span> </span> //</span> Prepare route with proofs and version requirements</span></span> Hop</span>[</span>]</span> memory</span> hops </span>=</span> new</span> Hop</span>[</span>]</span>(</span>2</span>)</span>;</span></span> hops</span>[</span>0</span>]</span> =</span> Hop</span>(</span>gateway1</span>,</span> proof1</span>,</span> 1</span>)</span>;</span> //</span> Require version 1</span></span> hops</span>[</span>1</span>]</span> =</span> Hop</span>(</span>gateway2</span>,</span> proof2</span>,</span> 0</span>)</span>;</span> //</span> Any version acceptable</span></span> </span> //</span> Example 1: Address Broadcasting - broadcast to all addresses on Arbitrum One (42161)</span></span> bytes</span> memory</span> addressBroadcast </span>=</span> abi</span>.</span>encodePacked</span>(</span></span> uint16</span>(</span>1</span>)</span>,</span> //</span> Version</span></span> uint16</span>(</span>0x0000</span>)</span>,</span> //</span> ChainType: eip155</span></span> uint8</span>(</span>2</span>)</span>,</span> //</span> ChainReferenceLength: 2 bytes for chain ID</span></span> uint16</span>(</span>42161</span>)</span>,</span> //</span> ChainReference: Arbitrum One (42161)</span></span> uint8</span>(</span>0</span>)</span> //</span> AddressLength: 0 (empty address = broadcast to all addresses)</span></span> )</span>;</span></span> </span> //</span> Example 2: Chain Type Broadcasting - broadcast to all EIP-155 chains</span></span> bytes</span> memory</span> chainTypeBroadcast </span>=</span> abi</span>.</span>encodePacked</span>(</span></span> uint16</span>(</span>1</span>)</span>,</span> //</span> Version</span></span> uint16</span>(</span>0x0000</span>)</span>,</span> //</span> ChainType: eip155</span></span> uint8</span>(</span>0</span>)</span>,</span> //</span> ChainReferenceLength: 0 (broadcast to all chains of this type)</span></span> uint8</span>(</span>0</span>)</span> //</span> AddressLength: 0 (empty address)</span></span> )</span>;</span></span> </span> //</span> Example 3: Universal Broadcasting - broadcast to all supported chains and addresses</span></span> bytes</span> memory</span> universalBroadcast </span>=</span> abi</span>.</span>encodePacked</span>(</span></span> uint16</span>(</span>1</span>)</span>,</span> //</span> Version</span></span> uint16</span>(</span>0x0000</span>)</span>,</span> //</span> ChainType: 0 (all chain types)</span></span> uint8</span>(</span>0</span>)</span>,</span> //</span> ChainReferenceLength: 0 (all chains)</span></span> uint8</span>(</span>0</span>)</span> //</span> AddressLength: 0 (all addresses)</span></span> )</span>;</span></span> </span> bytes</span>[</span>]</span> memory</span> attributes </span>=</span> new</span> bytes</span>[](</span>3</span>)</span>;</span></span> attributes</span>[</span>0</span>]</span> =</span> abi</span>.</span>encodeWithSignature</span>(</span>"route((bytes,bytes,uint256)[])"</span>,</span> hops</span>)</span>;</span></span> attributes</span>[</span>1</span>]</span> =</span> abi</span>.</span>encodeWithSignature</span>(</span>"inclusionProof(bytes)"</span>,</span> proofData</span>)</span>;</span></span> attributes</span>[</span>2</span>]</span> =</span> abi</span>.</span>encodeWithSignature</span>(</span>"targetBlock(uint256)"</span>,</span> blockNumber</span>)</span>;</span> //</span> Optional</span></span> </span> //</span> Send message with address broadcasting</span></span> gateway</span>.</span>sendMessage</span>(</span></span> addressBroadcast</span>,</span> //</span> broadcast to all addresses on Arbitrum One</span></span> abi</span>.</span>encode</span>(</span>"priceUpdate"</span>,</span> asset</span>,</span> price</span>)</span>,</span></span> attributes</span></span> )</span>;</span></span> </span> //</span> Send message with chain type broadcasting </span></span> gateway</span>.</span>sendMessage</span>(</span></span> chainTypeBroadcast</span>,</span> //</span> broadcast to all EIP-155 chains</span></span> abi</span>.</span>encode</span>(</span>"governanceProposal"</span>,</span> proposalId</span>,</span> votingPeriod</span>)</span>,</span></span> attributes</span></span> )</span>;</span></span> </span> //</span> Send message with universal broadcasting</span></span> gateway</span>.</span>sendMessage</span>(</span></span> universalBroadcast</span>,</span> //</span> broadcast to all supported chains and addresses</span></span> abi</span>.</span>encode</span>(</span>"pause"</span>,</span> reason</span>)</span>,</span></span> attributes</span></span> )</span>;</span></span></code></pre>Security Considerations</h2> Validation Requirements</h3> Gateways must rigorously validate all proof data to prevent message forgery, including proof format, completeness, and cryptographic validity. Route addresses must correspond to legitimate proof infrastructure forming a valid, connected path between chains. Only finalized blocks or equivalent commitment points should be used for proof generation to prevent reorganization attacks.</p> Consumers of cryptographic proof messages should implement appropriate freshness checks, as proofs can verify messages at any historical block or commitment, potentially including very old messages. This is not required for gateways offering immutable message commitments.</p> Route Security</h3> The security of a multi-hop route is only as strong as the weakest proof in the verification path. When multiple route steps are used, the overall security level is determined by the step with the lowest cryptographic guarantees or the least secure consensus mechanism. Implementers should carefully evaluate each hop in their routes and consider the cumulative security implications when designing cross-chain verification paths.</p> Broadcast Message Security</h3> Since broadcast messages can be executed by any party, receivers should implement robust validation of message sources and contents. This includes verifying the sender's authority and the message's semantic validity.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Crosschain EIP-712 Signatures 2025-06-05T00:00:00+00:00 Abstract</h2> This ERC defines a standard approach for creating and verifying crosschain signatures using EIP-712</a>. By omitting the chainId</code> field from the EIP-712 domain, a signature can be valid across multiple chains. Chain-specific operations are encoded as an array of structured messages, where each chain receives the array of message hashes and only the full message data relevant to that chain. This enables efficient crosschain signature validation using standard EIP-712 encoding without requiring special wallet support.</p> Motivation</h2> Current account abstraction solutions require separate signatures for each blockchain network. This creates poor user experience for crosschain operations such as:</p> Crosschain intents</strong>: Users wanting to trade assets across multiple chains atomically</li> Multi-chain DAO governance</strong>: Voting on proposals that affect protocol instances across different networks</li> Unified account management</strong>: Managing the same account deployed on multiple chains</li> Crosschain social recovery</strong>: Recovery processes that span multiple networks</li> </ul> Existing proposals either require complex Merkle tree constructions (which need wallet-specific UI to verify all leaves) or non-standard encoding schemes that lack wallet adoption. This ERC provides a simpler approach using only standard EIP-712 encoding with array types, enabling crosschain signatures with minimal on-chain overhead while maintaining full transparency in standard wallet signing interfaces.</p> Specification</h2> 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.</p> Crosschain Domain Semantics</h3> A crosschain EIP-712</a> signature MUST omit the chainId</code> field from the EIP712Domain</code> type and domain object. Since chainId</code> is optional per EIP-712</a>, omitting it signals that the signature is intended for crosschain validity.</p> Contract addresses and chainIds MUST be validated per-chain, so typically, only name</code> and version</code> are included in the main domain. The verifyingContract</code> field MAY be used to bind the signature to a specific application deployed deterministically on the same address across all chains the signature is intended to be valid on, allowing to omit the contract address from the chain-specific structs.</p> Message Array Encoding</h3> Crosschain operations MUST be encoded as an array of message structs with chain-specific fields. Each struct in the array SHOULD include the target chainId</code> field. When contracts are deployed at different addresses across chains, the struct SHOULD also include the verifyingContract</code> (or equivalent) field to bind each operation to its specific contract address unless the main domain includes the verifyingContract</code> field.</p> Implementers MAY use the canonical EIP712Domain</code> struct but named to avoid collisions with EIP712Domain</code> (e.g., EIP712ChainDomain</code>) so it can be nested inside the chain-specific structs, allowing to include the chainId</code> and verifyingContract</code> fields.</p> Per EIP-712</a>, arrays are encoded as keccak256(encodeData(element[0]) ‖ encodeData(element[1]) ‖ ... ‖ encodeData(element[n]))</code>, where each element is a struct that is recursively encoded as hashStruct(element[i])</code>, and nested structs are also recursively hashed.</p> In practice, this means the array of chain-specific operations is represented as an array of pre-computed bytes32</code> struct hashes (one for each chain). The hash of this array is computed as keccak256(abi.encodePacked(structsArray))</code>, which concatenates all 32-byte hashes and produces the array hash that matches the standard EIP-712</a> array encoding for reference types.</p> Struct Hash</h4> Per EIP-712</a>, the signature is computed over a complete message struct (e.g., CrossChainIntent</code>, MultiChainVote</code>), not just the array of operations. Applications implementing verification MUST define a type hash for the complete message struct that includes the array of operations.</p> Wrapping the array of operations in a main struct also allows to include other message fields (e.g., nonce</code>, deadline</code>) in the struct hash. For example, for a CrossChainIntent</code> struct would be encoded as:</p> bytes32</span> constant</span> CROSSCHAIN_INTENT_TYPEHASH </span>=</span> keccak256</span>(</span></span> "CrossChainIntent(ChainOperation[] operations,uint256 nonce,uint256 deadline)ChainOperation(EIP712ChainDomain domain,address target,uint256 value,bytes data)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span></span> )</span>;</span></span> </span> fullStructHash </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span> CROSSCHAIN_INTENT_TYPEHASH</span>,</span></span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>chainOperationsArray</span>)</span>)</span>,</span></span> nonce</span>,</span></span> deadline</span></span> )</span>)</span>;</span></span></code></pre> Applications implementing verification MUST use the same typehash across all chains where the application is deployed.</p> On-Chain Verification</h3> To enable applications to detect and verify crosschain signatures through standard ECDSA validation or ERC-1271</a> isValidSignature</code> calls, crosschain signatures SHOULD be encoded with metadata in the signature parameter. The signature validation flow requires the contract application to detect the encoding of this ERC, parse the signature components, and then verify the signature agains the reconstructed crosschain message hash.</p> The signature encoding format uses ABI encoding for dynamic types (arrays and bytes) with the following structure:</p> [0x00:0x09] magic (9 bytes)</span></span> [0x09:0x0a] fields (1 byte)</span></span> [0x0a:0x0c] structIndex (2 bytes, big-endian uint16)</span></span> [0x0c:0x20] application (20 bytes)</span></span> [0x20:0x40] structsArrayOffset (32 bytes, big-endian uint256, offset to structsArray location)</span></span> [structsArrayOffset:structsArrayOffset + 32] structsArrayLength (32 bytes, big-endian uint256)</span></span> [structsArrayOffset + 32:structsArrayOffset + 32 + structsArrayLength 32] structsArray (structsArrayLength * 32 bytes)</span></span> [crossChainSignatureOffset:crossChainSignatureOffset + 32] crossChainSignatureLength (32 bytes, big-endian uint256)</span></span> [crossChainSignatureOffset + 32:crossChainSignatureOffset + 32 + crossChainSignatureLength] crossChainSignature (crossChainSignatureLength bytes)</span></span></code></pre> Equivalent to the following ABI encoding:</p> bytes32</span> header </span>=</span> bytes32</span>(</span>abi</span>.</span>encodePacked</span>(</span>CrossChainSignatureChecker</span>.</span>ERC7964_MAGIC</span>,</span> fields</span>,</span> structIndex</span>,</span> address</span>(</span>application</span>)</span>)</span>)</span>;</span></span> abi</span>.</span>encode</span>(</span>header</span>,</span> structsArray</span>,</span> crossChainSignature</span>)</span>;</span> //</span> (bytes32, bytes, bytes32[])</span></span></code></pre> Where:</p> magic</code></strong>: A fixed 9-byte value 0x796479647964796479</code> used to detect encoded crosschain signatures</li> fields</code></strong>: A single byte encoding which EIP-712</a> domain fields are present (per ERC-5267</a>)</li> structIndex</code></strong>: The index in the structsArray</code> corresponding to the current chain's operation</li> application</code></strong>: The address of a contract implementing ERC-5267</a> that provides the EIP-712</a> domain information</li> structsArrayOffset</code></strong>: The offset (in bytes) from the start of the signature to where the structsArray</code> begins.</li> structsArrayLength</code></strong>: The number of elements in the structs array</li> structsArray</code></strong>: Array of bytes32</code> hashes, one per chain operation</li> crossChainSignatureOffset</code></strong>: The offset (in bytes) from the start of the signature to where the crossChainSignature</code> begins.</li> crossChainSignatureLength</code></strong>: The length of the crosschain signature in bytes</li> crossChainSignature</code></strong>: The actual signature bytes that sign the crosschain message</li> </ul> This encoding allows applications to identify when a signature is a crosschain signature, rebuild the EIP-712 domain information needed to reconstruct the expected typed hash, and verify the signature against the reconstructed crosschain message hash.</p> Applications can detect crosschain signatures by checking if the first 9 bytes of the signature equal the magic value 0x796479647964796479</code>. If detected, applications MUST:</p> Parse the encoded metadata from the signature</li> Verify that structsArray[structIndex]</code> matches the struct hash of the current chain's message</li> Query the ERC-5267</a> contract at application</code> to obtain the EIP-712 domain</li> Reconstruct the full EIP-712</a> hash using the domain, the main struct hash and the array of chain-specific struct hashes</li> Verify the crossChainSignature</code> against the reconstructed typed hash</li> </ol> Wallet Display</h3> Standard EIP-712</a> wallets will automatically display the array of chain-specific messages in a readable format. Wallets MAY enhance the display by grouping operations by chain and showing chain names instead of chain IDs for better user experience.</p> Rationale</h2> Standard EIP-712 Compatibility</h3> This ERC uses only standard EIP-712</a> encoding without any extensions or special constructs. All fields in the EIP712Domain</code> are optional per the standard, so omitting chainId</code> is perfectly valid. This means any wallet that supports EIP-712 can sign these messages and any application that supports EIP-712 can verify them.</p> The main benefit of this approach is that users can achieve a full transparent view of the crosschain message in any wallet provider that supports EIP-712</a>.</p> Main Struct Hash</h3> For wallet providers to show the crosschain message properly, they need a primaryType</code> to display the message. This specification does not mandate a specific primaryType</code> to allow for flexibility in the implementation, but defines the requirements for the array of operations and the main struct to ensure a secure EIP-712 message.</p> The specification requires that each of the operations include the chainId</code> field to avoid replaying the same operation on other chains. The verifyingContract</code> field (or equivalent) is used to bind the operation to its specific contract address and is optional if the main EIP712Domain</code> includes the verifyingContract</code> field since the domain hash would include the application's address.</p> Array Encoding vs Merkle Trees</h3> Alternative approaches use Merkle trees to commit to crosschain operations. While Merkle trees can reduce on-chain overhead for many chains, they have a critical drawback:</p> Wallet Verification Complexity</strong>: Standard EIP-712 wallets cannot display Merkle tree leaves. Users signing a Merkle root have no way to verify all operations in their wallet UI. Wallets would need to implement custom logic to:</p> Request all leaves from the application</li> Verify the Merkle tree construction</li> Display all operations across all chains</li> Ensure no malicious operations are hidden</li> </ol> This breaks the principle of trustless signing, users must trust the application to correctly provide all leaves, and wallet developers must implement and maintain custom verification logic.</p> The array-based approach provides full transparency</strong> using standard EIP-712. Users see all chain-specific operations in any compliant wallet without custom support. No hidden operations are possible since all array elements are displayed as part of the standard EIP-712 message structure.</p> On-chain overhead comparison</strong>: For reasonable crosschain operations, the overhead difference is minimal.</p> With the array approach, each chain receives all N operation hashes (N × 32 bytes</code>). With Merkle trees (assuming a binary tree), each chain receives a Merkle proof of size ceil(log₂(N)) × 32 bytes</code>. Both approaches reconstruct the root/array hash on-chain from the provided data and verify it against the signature, no additional calldata for the root is needed. While Merkle proofs grow logarithmically vs. the array's linear growth, the practical savings are small for reasonable use cases:</p> Chains</th> Array (N × 32)</th> Merkle (⌈log₂(N)⌉ × 32)</th> Savings</th></tr></thead> 2</td> 64 bytes (2 × 32)</td> 32 bytes (1 × 32)</td> 32 bytes (1 hash)</td></tr> 3</td> 96 bytes (3 × 32)</td> 64 bytes (2 × 32)</td> 32 bytes (1 hash)</td></tr> 4</td> 128 bytes (4 × 32)</td> 64 bytes (2 × 32)</td> 64 bytes (2 hashes)</td></tr> 5</td> 160 bytes (5 × 32)</td> 96 bytes (3 × 32)</td> 64 bytes (2 hashes)</td></tr> 8</td> 256 bytes (8 × 32)</td> 96 bytes (3 × 32)</td> 160 bytes (5 hashes)</td></tr> </tbody></table> For 2-5 chains (the reasonable case for crosschain operations), Merkle trees save only 32-64 bytes (1-2 hashes) per transaction. This minimal savings doesn't justify the complexity and loss of transparency. Merkle trees only become significantly more efficient at 8+ chains, which is an uncommon use case and may indicate the operation should be split into multiple signatures for better user comprehension and failure isolation.</p> Omitting chainId vs using 0</code></h3> Omitting chainId</code> entirely is cleaner than using a special value like 0</code> because it explicitly signals that the signature is intended for crosschain validity.</p> Signature Encoding Format</h3> The custom binary encoding format for crosschain signatures was selected to minimize calldata and memory overhead. The format packs metadata values that can be read to the stack and uses ABI encoding for structsArray</code> and crossChainSignature</code> for easy calldata and memory casting.</p> The magic value is used to detect crosschain signatures and is designed to be easy to parse and verify. It's a fixed 9-byte value that is easy to identify and verify. The length was selected to pack it along with bytes1(fields)</code>, uint16(structIndex)</code> and address(application)</code> into a single 32-byte word. While 9 bytes is shorter than a full 32-byte hash, the collision probability remains negligible in practice—an attacker would need to produce a valid ECDSA or ERC-1271</a> signature that randomly begins with these exact 9 bytes, which has probability 2^-72 (approximately 1 in 4.7 × 10^21) assuming a uniform distribution.</p> The fields</code> byte encodes which EIP-712 domain fields are present in the main domain (per ERC-5267</a>), enabling dynamic field selection. Only name</code> and version</code> are normally set in the main domain, since chainId</code> is omitted for crosschain validity since each chain-specific struct includes its own chainId</code> and optionally verifyingContract</code> (or equivalent), allowing each chain to validate its own contract address as part of the struct hash verification.</p> The application</code> address refers to any contract that implements ERC-5267</a>'s eip712Domain()</code> function. This contract provides the domain separator information needed to reconstruct the crosschain message hash. The application contract does not need to be the contract that executes the operation: it serves solely as a source of EIP-712 domain metadata. Applications could either deploy dedicated immutable domain separator contracts to ensure consistent domain information across all chains, or use the executing contract itself if it implements ERC-5267</a>.</p> Backwards Compatibility</h2> This ERC uses standard EIP-712</a> without modifications. Existing wallets and applications that support EIP-712 can immediately work with crosschain signatures without any changes, though they may not recognize the crosschain semantics.</p> Applications that verify signatures with a domain that includes a specific chainId</code> will reject crosschain signatures (where chainId</code> is omitted), providing safe failure by default. Applications that wish to support crosschain signatures must explicitly implement the verification pattern described in this ERC.</p> Reference Implementation</h2> To validate a crosschain signature, the application can use the following library:</p> import</span> {</span>SignatureChecker</span>}</span> from</span> "@openzeppelin/contracts/utils/cryptography/SignatureChecker.sol"</span>;</span></span> import</span> {</span>MessageHashUtils</span>}</span> from</span> "@openzeppelin/contracts/utils/cryptography/MessageHashUtils.sol"</span>;</span></span> import</span> {</span>IERC5267</span>}</span> from</span> "@openzeppelin/contracts/interfaces/IERC5267.sol"</span>;</span></span> import</span> {</span>Calldata</span>}</span> from</span> "@openzeppelin/contracts/utils/Calldata.sol"</span>;</span></span> </span> library</span> CrossChainSignatureChecker</span> {</span></span> bytes9</span> internal</span> constant</span> ERC7964_MAGIC </span>=</span> 0x796479647964796479</span>;</span></span> </span> function</span> isValidCrossChainSignatureNow</span>(</span></span> address</span> signer</span>,</span></span> bytes32</span> hash</span>,</span></span> bytes</span> calldata</span> erc7964Signature</span>,</span></span> function</span>(</span>bytes32</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> structHash</span></span> )</span> internal</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span> (</span></span> bool</span> success</span>,</span></span> bytes1</span> fields</span>,</span></span> uint16</span> structIndex</span>,</span></span> address</span> application</span>,</span></span> bytes32</span>[</span>]</span> calldata</span> structsArray</span>,</span></span> bytes</span> calldata</span> crossChainSignature</span></span> )</span> =</span> parseCrossChainSignature</span>(</span>erc7964Signature</span>)</span>;</span></span> if</span> (</span>!</span>success </span>\|\|</span> structsArray</span>[</span>structIndex</span>]</span> !=</span> hash</span>)</span> return</span> false</span>;</span></span> </span> string</span> memory</span> name</span>;</span></span> string</span> memory</span> version</span>;</span></span> uint256</span> chainId</span>;</span></span> address</span> verifyingContract</span>;</span></span> bytes32</span> domainSalt</span>;</span></span> (</span>,</span> name</span>,</span> version</span>,</span> chainId</span>,</span> verifyingContract</span>,</span> domainSalt</span>,</span> )</span> =</span> IERC5267</span>(</span>application</span>)</span>.</span>eip712Domain</span>(</span>)</span>;</span></span> </span> bytes32</span> typedHash </span>=</span> MessageHashUtils</span>.</span>toTypedDataHash</span>(</span></span> MessageHashUtils</span>.</span>toDomainSeparator</span>(</span>fields</span>,</span> name</span>,</span> version</span>,</span> chainId</span>,</span> verifyingContract</span>,</span> domainSalt</span>)</span>,</span></span> structHash</span>(</span>keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>structsArray</span>)</span>)</span>)</span></span> )</span>;</span></span> return</span> SignatureChecker</span>.</span>isValidSignatureNowCalldata</span>(</span>signer</span>,</span> typedHash</span>,</span> crossChainSignature</span>)</span>;</span></span> }</span></span> </span> function</span> parseCrossChainSignature</span>(</span></span> bytes</span> calldata</span> erc7964Signature</span></span> )</span></span> internal</span></span> pure</span></span> returns</span> (</span></span> bool</span> success</span>,</span></span> bytes1</span> fields</span>,</span></span> uint16</span> structIndex</span>,</span></span> address</span> application</span>,</span></span> bytes32</span>[</span>]</span> calldata</span> structsArray</span>,</span></span> bytes</span> calldata</span> crossChainSignature</span></span> )</span></span> {</span></span> //</span> magic (9 bytes) + fields (1 byte) + structIndex (2 bytes) + application (20 bytes) + structsArrayOffset (32 bytes) +</span></span> //</span> structsArrayLength (32 bytes) + crossChainSignatureOffset (32 bytes) + crossChainSignatureLength (32 bytes)</span></span> if</span> (</span>erc7964Signature</span>.</span>length </span><</span> 0x9f</span> \|\|</span> bytes9</span>(</span>erc7964Signature</span>[</span>0</span>:</span>9</span>]</span>)</span> !=</span> ERC7964_MAGIC</span>)</span> {</span></span> return</span> (</span>false</span>,</span> 0</span>,</span> 0</span>,</span> address</span>(</span>0</span>)</span>,</span> _empty32BytesArrayCalldata</span>(</span>)</span>,</span> Calldata</span>.</span>emptyBytes</span>(</span>)</span>)</span>;</span></span> }</span></span> fields </span>=</span> erc7964Signature</span>[</span>9</span>]</span>;</span></span> structIndex </span>=</span> uint16</span>(</span>bytes2</span>(</span>erc7964Signature</span>[</span>10</span>:</span>]</span>)</span>)</span>;</span></span> application </span>=</span> address</span>(</span>bytes20</span>(</span>erc7964Signature</span>[</span>12</span>:</span>]</span>)</span>)</span>;</span></span> </span> uint256</span> structsArrayOffset </span>=</span> uint256</span>(</span>bytes32</span>(</span>erc7964Signature</span>[</span>0x20</span>:</span>]</span>)</span>)</span>;</span></span> uint256</span> structsArrayDataOffset </span>=</span> structsArrayOffset </span>+</span> 32</span>;</span></span> if</span> (</span>structsArrayOffset </span><</span> 0x60</span> \|\|</span> structsArrayDataOffset </span>></span> erc7964Signature</span>.</span>length</span>)</span> {</span></span> return</span> (</span>false</span>,</span> 0</span>,</span> 0</span>,</span> address</span>(</span>0</span>)</span>,</span> _empty32BytesArrayCalldata</span>(</span>)</span>,</span> Calldata</span>.</span>emptyBytes</span>(</span>)</span>)</span>;</span></span> }</span></span> uint256</span> structsArrayLength </span>=</span> uint256</span>(</span>bytes32</span>(</span>erc7964Signature</span>[</span>structsArrayOffset</span>:</span>]</span>)</span>)</span>;</span></span> if</span> (</span>structsArrayDataOffset </span>+</span> structsArrayLength </span></span> 32</span> ></span> erc7964Signature</span>.</span>length</span>)</span> {</span></span> return</span> (</span>false</span>,</span> 0</span>,</span> 0</span>,</span> address</span>(</span>0</span>)</span>,</span> _empty32BytesArrayCalldata</span>(</span>)</span>,</span> Calldata</span>.</span>emptyBytes</span>(</span>)</span>)</span>;</span></span> }</span></span> </span> uint256</span> crossChainSignatureOffset </span>=</span> structsArrayDataOffset </span>+</span> structsArrayLength </span></span> 32</span>;</span></span> uint256</span> crossChainSignatureDataOffset </span>=</span> crossChainSignatureOffset </span>+</span> 32</span>;</span></span> if</span> (</span>crossChainSignatureOffset </span><</span> 0x60</span> \|\|</span> crossChainSignatureDataOffset </span>></span> erc7964Signature</span>.</span>length</span>)</span> {</span></span> return</span> (</span>false</span>,</span> 0</span>,</span> 0</span>,</span> address</span>(</span>0</span>)</span>,</span> _empty32BytesArrayCalldata</span>(</span>)</span>,</span> Calldata</span>.</span>emptyBytes</span>(</span>)</span>)</span>;</span></span> }</span></span> uint256</span> crossChainSignatureLength </span>=</span> uint256</span>(</span>bytes32</span>(</span>erc7964Signature</span>[</span>crossChainSignatureOffset</span>:</span>]</span>)</span>)</span>;</span></span> if</span> (</span>crossChainSignatureDataOffset </span>+</span> crossChainSignatureLength </span>></span> erc7964Signature</span>.</span>length</span>)</span> {</span></span> return</span> (</span>false</span>,</span> 0</span>,</span> 0</span>,</span> address</span>(</span>0</span>)</span>,</span> _empty32BytesArrayCalldata</span>(</span>)</span>,</span> Calldata</span>.</span>emptyBytes</span>(</span>)</span>)</span>;</span></span> }</span></span> </span> assembly</span> (</span>"memory-safe"</span>)</span> {</span></span> structsArray</span>.</span>offset </span>:=</span> add</span>(</span>erc7964Signature</span>.</span>offset</span>,</span> structsArrayDataOffset</span>)</span></span> structsArray</span>.</span>length </span>:=</span> structsArrayLength</span></span> }</span></span> crossChainSignature </span>=</span> erc7964Signature</span>[</span></span> crossChainSignatureDataOffset</span>:</span>crossChainSignatureDataOffset </span>+</span> crossChainSignatureLength</span></span> ]</span>;</span></span> return</span> (</span>true</span>,</span> fields</span>,</span> structIndex</span>,</span> application</span>,</span> structsArray</span>,</span> crossChainSignature</span>)</span>;</span></span> }</span></span> </span> function</span> _empty32BytesArrayCalldata</span>(</span>)</span> private</span> pure</span> returns</span> (</span>bytes32</span>[</span>]</span> calldata</span> result</span>)</span> {</span></span> assembly</span> (</span>"memory-safe"</span>)</span> {</span></span> result</span>.</span>offset </span>:=</span> 0</span></span> result</span>.</span>length </span>:=</span> 0</span></span> }</span></span> }</span></span> }</span></span></code></pre> A collection of examples of how to use this ERC to fulfill the Motivation</em> use cases.</p> Crosschain Intent Example</h3> A user wants to execute a crosschain trade: sell USDC on Ethereum, receive ETH on Arbitrum:</p> {</span></span> types</span>:</span> {</span></span> EIP712Domain</span>:</span> [</span></span> {</span> name</span>:</span> "</span>name</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>version</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span></span> //</span> Note: chainId is omitted for crosschain validity</span></span> ]</span>,</span></span> CrossChainIntent</span>:</span> [</span></span> {</span> name</span>:</span> "</span>operations</span>"</span>,</span> type</span>:</span> "</span>ChainOperation[]</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>nonce</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>deadline</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span></span> ]</span>,</span></span> ChainOperation</span>:</span> [</span></span> {</span> name</span>:</span> "</span>domain</span>"</span>,</span> type</span>:</span> "</span>EIP712ChainDomain</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>target</span>"</span>,</span> type</span>:</span> "</span>address</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>value</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>data</span>"</span>,</span> type</span>:</span> "</span>bytes</span>"</span> }</span></span> ]</span>,</span></span> EIP712ChainDomain</span>:</span> [</span></span> {</span> name</span>:</span> "</span>chainId</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>verifyingContract</span>"</span>,</span> type</span>:</span> "</span>address</span>"</span> }</span></span> ]</span></span> }</span>,</span></span> primaryType</span>:</span> "</span>CrossChainIntent</span>"</span>,</span></span> domain</span>:</span> {</span></span> name</span>:</span> "</span>CrossChainDEX</span>"</span>,</span></span> version</span>:</span> "</span>1</span>"</span></span> }</span>,</span></span> message</span>:</span> {</span></span> operations</span>:</span> [</span></span> {</span></span> domain</span>:</span> {</span></span> chainId</span>:</span> 1</span>,</span></span> verifyingContract</span>:</span> "</span>0x123321...</span>"</span> //</span> User's account on Ethereum</span></span> }</span>,</span></span> target</span>:</span> "</span>0xA0b86a33E6776885F5Db...</span>"</span>,</span> //</span> USDC contract</span></span> value</span>:</span> 0</span>,</span></span> data</span>:</span> "</span>0xa9059cbb...</span>"</span> //</span> transfer(settler, 1000 USDC)</span></span> }</span>,</span></span> {</span></span> domain</span>:</span> {</span></span> chainId</span>:</span> 42161</span>,</span></span> verifyingContract</span>:</span> "</span>0x123321...</span>"</span> //</span> User's account on Arbitrum</span></span> }</span>,</span></span> target</span>:</span> "</span>0xArbitrumSettler...</span>"</span>,</span></span> value</span>:</span> 0</span>,</span></span> data</span>:</span> "</span>0x3ccfd60b...</span>"</span> //</span> claim(0.5 ETH min)</span></span> }</span></span> ]</span>,</span></span> nonce</span>:</span> 42</span>,</span></span> deadline</span>:</span> 1704067200</span></span> }</span></span> }</span></span></code></pre> On-chain verification on Ethereum:</strong></p> Applications can verify crosschain signatures using the encoded format. The signature contains all necessary metadata to reconstruct and verify the crosschain message:</p> import</span> {</span>EIP712</span>}</span> from</span> "@openzeppelin/contracts/utils/cryptography/EIP712.sol"</span>;</span></span> import</span> {</span>Nonces</span>}</span> from</span> "@openzeppelin/contracts/utils/Nonces.sol"</span>;</span></span> import</span> {</span>CrossChainSignatureChecker</span>}</span> from</span> "./CrossChainSignatureChecker.sol"</span>;</span></span> </span> contract</span> CrossChainDEX</span> is</span> EIP712</span>, </span>Nonces</span> {</span></span> using</span> CrossChainSignatureChecker</span> for</span> address</span>;</span></span> </span> bytes32</span> public</span> constant</span> EIP712_CHAIN_DOMAIN_TYPEHASH </span>=</span></span> keccak256</span>(</span>"EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span> bytes32</span> public</span> constant</span> CHAIN_OPERATION_TYPEHASH </span>=</span></span> keccak256</span>(</span>"ChainOperation(EIP712ChainDomain domain,address target,uint256 value,bytes data)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span> bytes32</span> public</span> constant</span> CROSSCHAIN_INTENT_TYPEHASH </span>=</span></span> keccak256</span>(</span>"CrossChainIntent(ChainOperation[] operations,uint256 nonce,uint256 deadline)ChainOperation(EIP712ChainDomain domain,address target,uint256 value,bytes data)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span> </span> mapping</span>(</span>bytes32</span> operationHash </span>=></span> uint256</span>)</span> private</span> _deadlines</span>;</span></span> </span> constructor</span>(</span>)</span> EIP712</span>(</span>"CrossChainDEX", "1") </span>{</span>}</span></span> </span> function</span> executeIntent</span>(</span></span> address</span> account</span>,</span></span> ChainOperation</span> calldata</span> currentOp</span>,</span></span> uint256</span> nonce</span>,</span></span> uint256</span> deadline</span>,</span></span> bytes</span> calldata</span> signature</span></span> )</span> external</span> {</span></span> bytes32</span> currentOpHash </span>=</span> _structHash</span>(</span>currentOp</span>)</span>;</span></span> </span> _useCheckedNonce</span>(</span>account</span>,</span> nonce</span>)</span>;</span></span> _deadlines</span>[</span>currentOpHash</span>]</span> =</span> deadline</span>;</span></span> </span> require</span>(</span></span> account</span>.</span>isValidCrossChainSignatureNowCalldata</span>(</span></span> currentOpHash</span>,</span></span> signature</span>,</span></span> _crossChainStructHash</span></span> )</span>,</span></span> "Invalid signature"</span></span> )</span>;</span></span> </span> (</span>bool</span> success</span>,</span> )</span> =</span> currentOp</span>.</span>target</span>.</span>call</span>{</span>value</span>:</span> currentOp</span>.</span>value</span>}</span>(</span>currentOp</span>.</span>data</span>)</span>;</span></span> require</span>(</span>success</span>,</span> "Execution failed"</span>)</span>;</span></span> }</span></span> </span> function</span> _crossChainStructHash</span>(</span>bytes32</span> operationsHash</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span> return</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>CROSSCHAIN_INTENT_TYPEHASH</span>,</span> operationsHash</span>,</span> nonces</span>(</span>account</span>)</span>,</span> _deadlines</span>[</span>operationsHash</span>]</span>)</span>)</span>;</span></span> }</span></span> </span> function</span> _structHash</span>(</span>ChainOperation</span> calldata</span> op</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span> return</span> keccak256</span>(</span></span> abi</span>.</span>encode</span>(</span></span> CHAIN_OPERATION_TYPEHASH</span>,</span></span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>EIP712_CHAIN_DOMAIN_TYPEHASH</span>,</span> block</span>.</span>chainid</span>,</span> address</span>(</span>this</span>)</span>)</span>)</span>,</span></span> op</span>.</span>target</span>,</span></span> op</span>.</span>value</span>,</span></span> keccak256</span>(</span>op</span>.</span>data</span>)</span></span> )</span></span> )</span>;</span></span> }</span></span> }</span></span></code></pre> The Arbitrum settler would use the same signature with currentIndex: 1</code> and the full data for op[1]</code>. Each chain only receives the full calldata for its own operation, while other operations are represented as 32-byte hashes.</p> Multi-Chain Governance Example</h3> A DAO member votes on a proposal affecting all chain deployments:</p> {</span></span> types</span>:</span> {</span></span> EIP712Domain</span>:</span> [</span></span> {</span> name</span>:</span> "</span>name</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>version</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span></span> ]</span>,</span></span> MultiChainVote</span>:</span> [</span></span> {</span> name</span>:</span> "</span>votes</span>"</span>,</span> type</span>:</span> "</span>ChainVote[]</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>nonce</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span></span> ]</span>,</span></span> ChainVote</span>:</span> [</span></span> {</span> name</span>:</span> "</span>domain</span>"</span>,</span> type</span>:</span> "</span>EIP712ChainDomain</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>proposalId</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>support</span>"</span>,</span> type</span>:</span> "</span>uint8</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>reason</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span></span> ]</span>,</span></span> EIP712ChainDomain</span>:</span> [</span></span> {</span> name</span>:</span> "</span>chainId</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>verifyingContract</span>"</span>,</span> type</span>:</span> "</span>address</span>"</span> }</span></span> ]</span></span> }</span>,</span></span> primaryType</span>:</span> "</span>MultiChainVote</span>"</span>,</span></span> domain</span>:</span> {</span></span> name</span>:</span> "</span>MultiChainDAO</span>"</span>,</span></span> version</span>:</span> "</span>1</span>"</span></span> }</span>,</span></span> message</span>:</span> {</span></span> votes</span>:</span> [</span></span> {</span></span> domain</span>:</span> {</span></span> chainId</span>:</span> 1</span>,</span></span> verifyingContract</span>:</span> "</span>0x123321...</span>"</span> //</span> DAO contract on Ethereum</span></span> }</span>,</span></span> proposalId</span>:</span> 42</span>,</span></span> support</span>:</span> 1</span>,</span> //</span> For</span></span> reason</span>:</span> "</span>This upgrade improves security</span>"</span></span> }</span>,</span></span> {</span></span> domain</span>:</span> {</span></span> chainId</span>:</span> 137</span>,</span></span> verifyingContract</span>:</span> "</span>0x321321...</span>"</span> //</span> DAO contract on Polygon</span></span> }</span>,</span></span> proposalId</span>:</span> 42</span>,</span></span> support</span>:</span> 1</span>,</span> //</span> For</span></span> reason</span>:</span> "</span>This upgrade improves security</span>"</span></span> }</span></span> ]</span>,</span></span> nonce</span>:</span> 7</span></span> }</span></span> }</span></span></code></pre> On-chain verification on each DAO:</strong></p> import</span> {</span>EIP712</span>}</span> from</span> "@openzeppelin/contracts/utils/cryptography/EIP712.sol"</span>;</span></span> import</span> {</span>Nonces</span>}</span> from</span> "@openzeppelin/contracts/utils/Nonces.sol"</span>;</span></span> import</span> {</span>CrossChainSignatureChecker</span>}</span> from</span> "./CrossChainSignatureChecker.sol"</span>;</span></span> </span> contract</span> MultiChainDAO</span> is</span> EIP712</span>, </span>Nonces</span> {</span></span> using</span> CrossChainSignatureChecker</span> for</span> address</span>;</span></span> </span> bytes32</span> public</span> constant</span> EIP712_CHAIN_DOMAIN_TYPEHASH </span>=</span></span> keccak256</span>(</span>"EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span> bytes32</span> public</span> constant</span> CHAIN_VOTE_TYPEHASH </span>=</span></span> keccak256</span>(</span>"ChainVote(EIP712ChainDomain domain,uint256 proposalId,uint8 support,string reason)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span> bytes32</span> public</span> constant</span> MULTICHAIN_VOTE_TYPEHASH </span>=</span></span> keccak256</span>(</span>"MultiChainVote(ChainVote[] votes,uint256 nonce)ChainVote(EIP712ChainDomain domain,uint256 proposalId,uint8 support,string reason)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span> </span> constructor</span>(</span>)</span> EIP712</span>(</span>"MultiChainDAO", "1") </span>{</span>}</span></span> </span> function</span> castVoteWithSignature</span>(</span></span> ChainVote</span> calldata</span> currentVote</span>,</span></span> uint256</span> nonce</span>,</span></span> address</span> voter</span>,</span></span> bytes</span> calldata</span> erc7964Signature</span></span> )</span> external</span> {</span></span> bytes32</span> currentVoteHash </span>=</span> _structHash</span>(</span>currentVote</span>)</span>;</span></span> </span> _useCheckedNonce</span>(</span>voter</span>,</span> nonce</span>)</span>;</span></span> </span> require</span>(</span></span> voter</span>.</span>isValidCrossChainSignatureNowCalldata</span>(</span></span> currentVoteHash</span>,</span></span> erc7964Signature</span>,</span></span> _crossChainStructHash</span></span> )</span>,</span></span> "Invalid signature"</span></span> )</span>;</span></span> </span> _castVote</span>(</span>currentVote</span>.</span>proposalId</span>,</span> voter</span>,</span> currentVote</span>.</span>support</span>,</span> currentVote</span>.</span>reason</span>)</span>;</span></span> }</span></span> </span> function</span> _crossChainStructHash</span>(</span>bytes32</span> votesHash</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span> return</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>MULTICHAIN_VOTE_TYPEHASH</span>,</span> votesHash</span>,</span> nonces</span>(</span>voter</span>)</span>)</span>)</span>;</span></span> }</span></span> </span> function</span> _structHash</span>(</span>ChainVote</span> calldata</span> vote</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span> return</span> keccak256</span>(</span></span> abi</span>.</span>encode</span>(</span></span> CHAIN_VOTE_TYPEHASH</span>,</span></span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>EIP712_CHAIN_DOMAIN_TYPEHASH</span>,</span> block</span>.</span>chainid</span>,</span> address</span>(</span>this</span>)</span>)</span>)</span>,</span></span> vote</span>.</span>proposalId</span>,</span></span> vote</span>.</span>support</span>,</span></span> keccak256</span>(</span>bytes</span>(</span>vote</span>.</span>reason</span>)</span>)</span></span> )</span></span> )</span>;</span></span> }</span></span> }</span></span></code></pre> This vote signature can be submitted to DAO contracts on both Ethereum and Polygon, enabling coordinated multi-chain governance decisions.</p> Unified Account Management Example</h3> A user wants to add a new signer to their multisig account deployed across multiple chains:</p> {</span></span> types</span>:</span> {</span></span> EIP712Domain</span>:</span> [</span></span> {</span> name</span>:</span> "</span>name</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>version</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span></span> ]</span>,</span></span> MultiChainAccountUpdate</span>:</span> [</span></span> {</span> name</span>:</span> "</span>updates</span>"</span>,</span> type</span>:</span> "</span>AccountUpdate[]</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>nonce</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span></span> ]</span>,</span></span> AccountUpdate</span>:</span> [</span></span> {</span> name</span>:</span> "</span>domain</span>"</span>,</span> type</span>:</span> "</span>EIP712ChainDomain</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>operation</span>"</span>,</span> type</span>:</span> "</span>uint8</span>"</span> }</span>,</span> //</span> 0=addSigner, 1=removeSigner, 2=changeThreshold</span></span> {</span> name</span>:</span> "</span>signerData</span>"</span>,</span> type</span>:</span> "</span>bytes</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>threshold</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span></span> ]</span>,</span></span> EIP712ChainDomain</span>:</span> [</span></span> {</span> name</span>:</span> "</span>chainId</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>verifyingContract</span>"</span>,</span> type</span>:</span> "</span>address</span>"</span> }</span></span> ]</span></span> }</span>,</span></span> primaryType</span>:</span> "</span>MultiChainAccountUpdate</span>"</span>,</span></span> domain</span>:</span> {</span></span> name</span>:</span> "</span>MultiChainMultisig</span>"</span>,</span></span> version</span>:</span> "</span>1</span>"</span></span> }</span>,</span></span> message</span>:</span> {</span></span> updates</span>:</span> [</span></span> {</span></span> domain</span>:</span> {</span></span> chainId</span>:</span> 1</span>,</span></span> verifyingContract</span>:</span> "</span>0x123321...</span>"</span> //</span> Account on Ethereum</span></span> }</span>,</span></span> operation</span>:</span> 0</span>,</span> //</span> addSigner</span></span> signerData</span>:</span> "</span>0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20</span>"</span>,</span></span> threshold</span>:</span> 3</span></span> }</span>,</span></span> {</span></span> domain</span>:</span> {</span></span> chainId</span>:</span> 137</span>,</span></span> verifyingContract</span>:</span> "</span>0x123321...</span>"</span> //</span> Account on Polygon</span></span> }</span>,</span></span> operation</span>:</span> 0</span>,</span> //</span> addSigner</span></span> signerData</span>:</span> "</span>0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20</span>"</span>,</span></span> threshold</span>:</span> 3</span></span> }</span>,</span></span> {</span></span> domain</span>:</span> {</span></span> chainId</span>:</span> 42161</span>,</span></span> verifyingContract</span>:</span> "</span>0x123321...</span>"</span> //</span> Account on Arbitrum</span></span> }</span>,</span></span> operation</span>:</span> 0</span>,</span> //</span> addSigner</span></span> signerData</span>:</span> "</span>0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20</span>"</span>,</span></span> threshold</span>:</span> 3</span></span> }</span></span> ]</span>,</span></span> nonce</span>:</span> 42</span></span> }</span></span> }</span></span></code></pre> On-chain execution:</strong></p> import</span> {</span>EIP712</span>}</span> from</span> "@openzeppelin/contracts/utils/cryptography/EIP712.sol"</span>;</span></span> import</span> {</span>Nonces</span>}</span> from</span> "@openzeppelin/contracts/utils/Nonces.sol"</span>;</span></span> import</span> {</span>CrossChainSignatureChecker</span>}</span> from</span> "./CrossChainSignatureChecker.sol"</span>;</span></span> </span> contract</span> MultiChainMultisig</span> is</span> EIP712</span>, </span>Nonces</span> {</span></span> using</span> CrossChainSignatureChecker</span> for</span> address</span>;</span></span> </span> bytes32</span> public</span> constant</span> EIP712_CHAIN_DOMAIN_TYPEHASH </span>=</span></span> keccak256</span>(</span>"EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span> bytes32</span> public</span> constant</span> ACCOUNT_UPDATE_TYPEHASH </span>=</span></span> keccak256</span>(</span>"AccountUpdate(EIP712ChainDomain domain,uint8 operation,bytes signerData,uint256 threshold)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span> bytes32</span> public</span> constant</span> MULTICHAIN_ACCOUNT_UPDATE_TYPEHASH </span>=</span></span> keccak256</span>(</span>"MultiChainAccountUpdate(AccountUpdate[] updates,uint256 nonce)AccountUpdate(EIP712ChainDomain domain,uint8 operation,bytes signerData,uint256 threshold)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span> </span> constructor</span>(</span>)</span> EIP712</span>(</span>"MultiChainMultisig", "1") </span>{</span>}</span></span> </span> function</span> updateAccountWithSignature</span>(</span></span> AccountUpdate</span> calldata</span> currentUpdate</span>,</span></span> uint256</span> nonce</span>,</span></span> bytes</span> calldata</span> erc7964Signature</span></span> )</span> external</span> {</span></span> bytes32</span> currentUpdateHash </span>=</span> _structHash</span>(</span>currentUpdate</span>)</span>;</span></span> </span> _useCheckedNonce</span>(</span>address</span>(</span>this</span>)</span>,</span> nonce</span>)</span>;</span></span> </span> require</span>(</span></span> address</span>(</span>this</span>)</span>.</span>isValidCrossChainSignatureNowCalldata</span>(</span></span> currentUpdateHash</span>,</span></span> erc7964Signature</span>,</span></span> _crossChainStructHash</span></span> )</span>,</span></span> "Invalid signature"</span></span> )</span>;</span></span> </span> if</span> (</span>currentUpdate</span>.</span>operation </span>==</span> 0</span>)</span> {</span></span> _addSigner</span>(</span>currentUpdate</span>.</span>signerData</span>,</span> currentUpdate</span>.</span>threshold</span>)</span>;</span></span> }</span> //</span> ... other operations</span></span> }</span></span> </span> function</span> _crossChainStructHash</span>(</span>bytes32</span> updatesHash</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span> return</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>MULTICHAIN_ACCOUNT_UPDATE_TYPEHASH</span>,</span> updatesHash</span>,</span> nonces</span>(</span>address</span>(</span>this</span>)</span>)</span>)</span>)</span>;</span></span> }</span></span> </span> function</span> _structHash</span>(</span>AccountUpdate</span> calldata</span> update</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span> return</span> keccak256</span>(</span></span> abi</span>.</span>encode</span>(</span></span> ACCOUNT_UPDATE_TYPEHASH</span>,</span></span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>EIP712_CHAIN_DOMAIN_TYPEHASH</span>,</span> block</span>.</span>chainid</span>,</span> address</span>(</span>this</span>)</span>)</span>)</span>,</span></span> update</span>.</span>operation</span>,</span></span> keccak256</span>(</span>update</span>.</span>signerData</span>)</span>,</span></span> update</span>.</span>threshold</span></span> )</span></span> )</span>;</span></span> }</span></span> </span> function</span> _addSigner</span>(</span>bytes</span> calldata</span> signerData</span>,</span> uint256</span> threshold</span>)</span> internal</span> {</span></span> //</span> Implementation for adding signer</span></span> }</span></span> }</span></span></code></pre> This signature enables the multisig owners to add a new signer and update the threshold across all chain deployments simultaneously. The same account address exists on Ethereum, Polygon, and Arbitrum, and this single signature authorizes the updates on all three networks.</p> CrossChain Social Recovery Example</h3> A user has lost access to their account and guardians need to initiate recovery across multiple networks:</p> {</span></span> types</span>:</span> {</span></span> EIP712Domain</span>:</span> [</span></span> {</span> name</span>:</span> "</span>name</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>version</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span></span> //</span> Note: verifyingContract is omitted since the recovery module is deployed on different addresses across chains for this example</span></span> ]</span>,</span></span> MultiChainRecovery</span>:</span> [</span></span> {</span> name</span>:</span> "</span>recoveries</span>"</span>,</span> type</span>:</span> "</span>ChainRecovery[]</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>nonce</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span></span> ]</span>,</span></span> ChainRecovery</span>:</span> [</span></span> {</span> name</span>:</span> "</span>domain</span>"</span>,</span> type</span>:</span> "</span>EIP712ChainDomain</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>newOwner</span>"</span>,</span> type</span>:</span> "</span>address</span>"</span> }</span></span> ]</span>,</span></span> EIP712ChainDomain</span>:</span> [</span></span> {</span> name</span>:</span> "</span>chainId</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span>,</span></span> {</span> name</span>:</span> "</span>verifyingContract</span>"</span>,</span> type</span>:</span> "</span>address</span>"</span> }</span></span> ]</span></span> }</span>,</span></span> primaryType</span>:</span> "</span>MultiChainRecovery</span>"</span>,</span></span> domain</span>:</span> {</span></span> name</span>:</span> "</span>CrossChainSocialRecovery</span>"</span>,</span></span> version</span>:</span> "</span>1</span>"</span></span> }</span>,</span></span> message</span>:</span> {</span></span> recoveries</span>:</span> [</span></span> {</span></span> domain</span>:</span> {</span></span> chainId</span>:</span> 1</span>,</span></span> verifyingContract</span>:</span> "</span>0x123321...</span>"</span> //</span> Recovery module on Ethereum</span></span> }</span>,</span></span> newOwner</span>:</span> "</span>0x9999999999999999999999999999999999999999</span>"</span></span> }</span>,</span></span> {</span></span> domain</span>:</span> {</span></span> chainId</span>:</span> 137</span>,</span></span> verifyingContract</span>:</span> "</span>0x321321...</span>"</span> //</span> Recovery module on Polygon</span></span> }</span>,</span></span> newOwner</span>:</span> "</span>0x9999999999999999999999999999999999999999</span>"</span></span> }</span>,</span></span> {</span></span> domain</span>:</span> {</span></span> chainId</span>:</span> 42161</span>,</span></span> verifyingContract</span>:</span> "</span>0x432432...</span>"</span> //</span> Recovery module on Arbitrum</span></span> }</span>,</span></span> newOwner</span>:</span> "</span>0x9999999999999999999999999999999999999999</span>"</span></span> }</span></span> ]</span>,</span></span> nonce</span>:</span> 1</span></span> }</span></span> }</span></span></code></pre> On-chain execution with guardian multisig:</strong></p> import</span> { </span>CrossChainSignatureChecker</span> }</span> from</span> "./CrossChainSignatureChecker.sol"</span>;</span></span> </span> bytes32</span> constant</span> EIP712_CHAIN_DOMAIN_TYPEHASH </span>=</span> keccak256</span>(</span></span> "EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span></span> )</span>;</span></span> bytes32</span> constant</span> CHAIN_RECOVERY_TYPEHASH </span>=</span> keccak256</span>(</span></span> "ChainRecovery(EIP712ChainDomain domain,address newOwner)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span></span> )</span>;</span></span> bytes32</span> constant</span> MULTICHAIN_RECOVERY_TYPEHASH </span>=</span> keccak256</span>(</span></span> "MultiChainRecovery(ChainRecovery[] recoveries,uint256 nonce)ChainRecovery(EIP712ChainDomain domain,address newOwner)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span></span> )</span>;</span></span> </span> uint256</span> private</span> _tempNonce</span>;</span></span> </span> function</span> initiateRecoveryWithSignature</span>(</span></span> ChainRecovery</span> calldata</span> currentRecovery</span>,</span></span> uint256</span> nonce</span>,</span></span> address</span>[</span>]</span> calldata</span> guardians</span>,</span></span> bytes</span>[</span>]</span> calldata</span> guardianErc7964Signatures</span></span> )</span> external</span> {</span></span> require</span>(</span>guardians</span>.</span>length </span>==</span> guardianErc7964Signatures</span>.</span>length</span>,</span> "Mismatched arrays"</span>)</span>;</span></span> //</span> Note</span>: chainId and verifyingContract validation is implicit in the struct hash verification</span></span> </span> //</span> Verify the current recovery hash matches all guardian signatures</span></span> bytes32</span> currentRecoveryHash </span>=</span> _structHash</span>(</span>currentRecovery</span>)</span>;</span></span> </span> _tempNonce </span>=</span> nonce</span>;</span></span> </span> //</span> Verify all guardian signatures are valid and count valid guardian signatures</span></span> uint256</span> validSignatures </span>=</span> 0</span>;</span></span> for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> guardians</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span> if</span> (</span></span> CrossChainSignatureChecker</span>.</span>isValidCrossChainSignatureNow</span>(</span></span> guardians</span>[</span>i</span>]</span>,</span></span> currentRecoveryHash</span>,</span></span> guardianErc7964Signatures</span>[</span>i</span>]</span>,</span></span> _computeRecoveryStructHash</span></span> )</span> &&</span> isGuardian</span>(</span>guardians</span>[</span>i</span>]</span>)</span></span> )</span> {</span></span> validSignatures</span>+</span>+</span>;</span></span> }</span></span> }</span></span> require</span>(</span>validSignatures </span>></span>=</span> 3</span>,</span> "Insufficient guardian signatures"</span>)</span>;</span></span> </span> //</span> Schedule recovery with delay</span></span> _scheduleRecovery</span>(</span>currentRecovery</span>.</span>newOwner</span>,</span> block</span>.</span>timestamp </span>+</span> RECOVERY_DELAY</span>)</span>;</span></span> }</span></span> </span> function</span> _computeRecoveryStructHash</span>(</span></span> bytes32</span> recoveriesHash</span></span> )</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span> return</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span> MULTICHAIN_RECOVERY_TYPEHASH</span>,</span></span> recoveriesHash</span>,</span></span> _tempNonce</span></span> )</span>)</span>;</span></span> }</span></span> </span> function</span> _structHash</span>(</span>ChainRecovery</span> calldata</span> recovery</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span> return</span> keccak256</span>(</span></span> abi</span>.</span>encode</span>(</span></span> CHAIN_RECOVERY_TYPEHASH</span>,</span></span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>EIP712_CHAIN_DOMAIN_TYPEHASH</span>,</span> block</span>.</span>chainid</span>,</span> address</span>(</span>this</span>)</span>)</span>)</span>,</span></span> recovery</span>.</span>newOwner</span></span> )</span></span> )</span>;</span></span> }</span></span></code></pre> This signature enables guardians to schedule a recovery operation across all chains. The process includes:</p> Guardian Signatures</strong>: Multiple guardians sign the same crosschain recovery message (3-of-5 threshold)</li> Schedule Phase</strong>: Once sufficient guardians sign, the recovery is scheduled on all networks with a delay</li> Security Window</strong>: Delay period where malicious recovery attempts can be detected and canceled</li> Execution Phase</strong>: After the delay, the recovery replaces the account's owner</li> CrossChain Consistency</strong>: The same recovery operation is scheduled simultaneously on Ethereum, Polygon, and Arbitrum</li> </ol> Security Considerations</h2> Crosschain Replay</h3> This ERC intentionally enables replay across chains, the same signature is designed to be used on multiple chains. The verifyingContract</code> field (set to the user's account address) binds the signature to a specific account, preventing unauthorized use. However, applications must implement their own replay protection mechanisms such as including nonces and deadlines in the message.</p> Account Validation</h3> Applications verifying signatures should check that the signing account exists on the current chain. An account that exists on Ethereum but not Polygon should not have signatures accepted on Polygon. For counterfactual accounts that have not been deployed yet, applications should follow ERC-6492</a> to validate signatures.</p> Code and State Differences</h3> Contract code and state may differ across chains at the same address. Signatures that pass isValidSignature()</code> on one chain may fail on another due to state divergence or chain-specific logic. For example, a crosschain message that has uses a nonce</code> field may find that the nonce is already used on one of the chains. Applications should handle signature validation failures gracefully and should not assume uniform behavior across chains.</p> Partial Execution Risk</h3> Crosschain signatures do not guarantee atomic execution. A signature may be successfully validated on some chains but not others. This can result in partial fulfillment of the intent. Applications should implement refund mechanisms to allow users to recover from failed partial executions.</p> Additionally, operations may execute in different orders across chains due to varying network conditions, block times, and congestion levels. An operation intended to execute first may complete last on a congested chain, leading to unexpected state changes. For example, in a crosschain trade, a user might sell an asset on one chain before successfully acquiring its replacement on another chain, creating temporary exposure. Applications should design operations to be order-independent where possible, or implement coordination mechanisms to ensure proper sequencing.</p> Signature Expiration</h3> Signatures without explicit expiration remain valid indefinitely. If an operation is not executed on some chains, it can be executed later, potentially with unexpected consequences. Applications may include deadline</code> or validUntil</code> fields in messages to prevent stale signature execution.</p> Wallet Display Considerations</h3> Since this ERC relies on standard EIP-712 wallet display, users depend on their wallet to correctly show all crosschain operations. Users should:</p> Review All Operations</strong>: Check every element in the message array</li> Verify Chain IDs</strong>: Ensure operations target the expected chains</li> Check Amounts</strong>: Verify asset amounts and addresses on each chain</li> Understand Atomicity</strong>: Know that operations may execute independently</li> </ol> Wallet developers should enhance displays to highlight crosschain nature and show warnings about partial execution risks.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Encode chain id with transaction hash 2025-05-22T00:00:00+00:00 Abstract</h2> This standard proposes a way to encode the combination of a chain ID and a transaction hash into one string.</p> Motivation</h2> Looking up a transaction by its hash always requires the context of the chain - a transaction hash alone is not enough to identify the used chain. If the chain information is included in the string itself, finding the right chain for the transaction is easy.</p> Such strings can then be used, for example, in a forwarder service that forwards to the correct blockchain explorer.</p> The chain id is included in some object formats, such as the transaction object inside the blockchain itself, but that object has a lot of unneeded data for our purposes.</p> Specification</h2> The encoded string has three components:</p> A chain ID, denoted as chainId</code>. The used chain id MUST be based on EIP-155</a> and the chain ID repository stated in that EIP.</li> A transaction hash, denoted as txHash</code>. The hash MUST include the 0x</code> prefix.</li> A static string tx</code>, acting as a type identifier.</li> </ul> The syntax is: chainId:txHash:tx</code>.</p> An example for a transaction with hash 0xc55e2b90168af6972193c1f86fa4d7d7b31a29c156665d15b9cd48618b5177ef</code> that was issued on chain ID 1</code> is: 1:0xc55e2b90168af6972193c1f86fa4d7d7b31a29c156665d15b9cd48618b5177ef:tx</code>.</p> All of the characters are case-insensitive.</p> Rationale</h2> The chain ID is the most important detail when routing queries based on this standard and is therefore the first element in the string. The transaction hash is the second most important element.</p> The suffix tx</code> is used to differentiate from, for example, addresses. Without the tx</code> it would remain unclear whether an encoded string refers to an address, a transaction hash or something else.</p> Security Considerations</h2> This EIP does not introduce direct security risks. It is up to the external service providers (such as wallet developers and blockchain explorers) to decide how and if they want to incorporate this EIP.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Key Hash Based Tokens 2025-05-16T00:00:00+00:00 Abstract</h2> This EIP proposes two token interfaces: ERC-KeyHash721</strong> for non-fungible tokens (NFTs) and ERC-KeyHash20</strong> for fungible tokens (similar to ERC-20</a>). Both of them utilize cryptographic key hashes (“keyHash”, or keccak256(key)</code>) instead of Ethereum addresses to manage ownership. This enhances privacy by authorizing by the public key’s ECDSA signature (address derived from keccak256(key[1:])</code>) and matching keyHash = keccak256(key)</code>, without storing addresses on‑chain. Consequently, it empowers users to conduct transactions using any address they choose. By separating ownership from transaction initiation, these standards allow gas fees to be paid by third parties without relinquishing token control, making them suitable for batch transactions and gas sponsorship. Security is ensured by implementing robust ECDSA signature verification on key functions (transfer</code>) to prevent message tampering.</p> Motivation</h2> Traditional ERC-721</a> and ERC-20</a> tokens bind ownership to Ethereum addresses, which are publicly visible and may be linked to identities, compromising privacy. The key hash-based ownership model allows owners to prove control without exposing addresses, ideal for anonymous collectibles, private transactions, or decentralized identity use cases. Additionally, separating ownership from gas fee payment enables third-party gas sponsorship, improving user experience in high-gas or batch transaction scenarios. This proposal aligns with the privacy principles of ERC-5564</a> (Stealth Addresses) and extends them to token ownership.</p> Specification</h2> 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.</p> Overview</h3> This proposal defines two token interfaces:</p> IERCKeyHash721</code>: For non-fungible tokens (NFTs), each identified by a unique tokenId</code>, with ownership managed via keyHash</code> (keccak256(key)</code>).</li> IERCKeyHash20</code>: For fungible tokens, with balances associated with keyHash</code>.</li> </ul> Token operations (transfer</code>) require the owner's key(an uncompressed secp256k1 public key) and an ECDSA signature produced by the private key corresponding to the key (i.e., the address derived from keccak256(key[1:])</code> excluding the 0x04 prefix) to prove ownership, ensuring only legitimate owners can execute actions. Signatures follow EIP-712</a> structured data hashing to prevent message tampering, with per-keyHash nonces and deadlines to prevent replay attacks.</p> Implementers MAY optionally add administrative functions such as mint</code> (create new tokens) and destroy</code> (remove tokens) based on application requirements. These functions are not part of the core interface of this ERC; if provided, they SHOULD enforce strict access control, correct supply accounting, and preserve the key‑hash privacy model without exposing addresses.</p> Notably, the approve function is intentionally omitted. The key is designed for one-time use and is revealed only during token transfer transactions. Once revealed, holdings are typically migrated to fresh keyHashes; implementations MAY disallow reuse of previously revealed keyHash. Since transactions can be submitted by any address, the signature must be generated by the address derived from the key. This binds authorization to the key while allowing any relayer address to submit and pay gas.</p> ERC-KeyHash721: Non-Fungible Token Interface</h3> Interface</h4> interface</span> IERCKeyHash721</span> {</span></span> //</span> Events</span></span> event</span> KeyHashTransfer721</span>(</span>uint256</span> indexed</span> tokenId</span>, </span>bytes32</span> indexed</span> fromKeyHash</span>, </span>bytes32</span> indexed</span> toKeyHash</span>)</span>;</span></span> event</span> KeyHashBurn721</span>(</span>uint256</span> indexed</span> tokenId</span>, </span>bytes32</span> indexed</span> ownerKeyHash</span>)</span>;</span></span> </span> //</span> View functions (aligned with ERC-721)</span></span> function</span> name</span>(</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span>;</span></span> function</span> symbol</span>(</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span>;</span></span> function</span> tokenURI</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span>;</span></span> function</span> totalSupply</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> function</span> ownerOf</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span> </span> //</span> State-changing functions</span></span> function</span> mint</span>(</span>uint256</span> tokenId</span>,</span> bytes32</span> keyHash</span>)</span> external</span>;</span></span> function</span> transfer</span>(</span>uint256</span> tokenId</span>,</span> bytes32</span> toKeyHash</span>,</span> bytes</span> memory</span> key</span>,</span> bytes</span> memory</span> signature</span>,</span> uint256</span> deadline</span>)</span> external</span>;</span></span> function</span> destroy</span>(</span>uint256</span> tokenId</span>,</span> bytes</span> memory</span> key</span>,</span> bytes</span> memory</span> signature</span>,</span> uint256</span> deadline</span>)</span> external</span>;</span></span> }</span></span></code></pre>Function Descriptions</h4> transfer</code></h5> transfer</span>(</span>uint256</span> tokenId</span>,</span> bytes32</span> toKeyHash</span>,</span> bytes</span> memory</span> key</span>,</span> bytes</span> memory</span> signature</span>,</span> uint256</span> deadline</span>)</span> external</span>;</span></span></code></pre> Description</strong>: Transfers the specified token from the current owner's keyHash</code> to toKeyHash</code>. The caller provides the owner's key to prove ownership. The signature is verified using EIP-712</a> structured data. Parameters</strong>:</p> tokenId</code>: uint256</code> - The token ID to transfer.</li> toKeyHash</code>: bytes32</code> - The new owner's key hash.</li> key</code>: bytes</code> - MUST be a 65-byte uncompressed secp256k1 public key with prefix 0x04.</li> signature</code>: bytes</code> - ECDSA signature produced by the private key corresponding to the key, verifying ownership and preventing malicious relay attacks.</li> deadline</code>: uint256</code> - Signature expiration timestamp (Unix seconds). Signature Message</strong>: EIP-712</a> structured data: solidity struct Transfer { uint256 tokenId; bytes32 toKeyHash; uint256 nonce; uint256 deadline; } </code> Events</strong>: Emits KeyHashTransfer721(tokenId, fromKeyHash, toKeyHash)</code>. Requirements</strong>:</li> Token MUST exist (non-zero fromKeyHash</code>).</li> keccak256(key)</code> MUST equal the current fromKeyHash</code>.</li> Signature MUST be valid.</li> block.timestamp</code> MUST be <= deadline</code>.</li> toKeyHash</code> MUST NOT be zero.</li> Updates ownership to toKeyHash</code>.</li> </ul> Other Functions</strong>: name</code>, symbol</code>, tokenURI</code>, and totalSupply</code> align with ERC-721</a> . ownerOf</code> returns bytes32</code> (keyHash) instead of an address.tokenURI</code> is part of the core interface and MAY return an empty string if metadata is not provided.</li> </ul> Key Concepts</h4> Key (key</code>)</strong>: An uncompressed secp256k1 public key (65 bytes, starting with 0x04), used to prove ownership. Implementations MUST validate the key format:</li> </ul> require</span>(</span>key</span>.</span>length </span>==</span> 65</span> &&</span> key</span>[</span>0</span>]</span> ==</span> 0x04</span>,</span> "BAD_KEY_FMT"</span>)</span>;</span></span></code></pre> Key Hash (keyHash</code>)</strong>: A bytes32</code> value representing keccak256(key)</code>, identifying ownership without exposing addresses.</li> Token Existence</strong>: A token exists if its keyHash</code> is non-zero.</li> Nonce</strong>: Nonces are tracked per keyHash and per contract. Each ERC-KeyHash contract maintains its ownmapping(bytes32 =>uint256)keyNonces. Cross-contract replay is already prevented by the EIP-712 domain (verifyingContract, chainId). Signers MUST serialize operations for the same keyHashwithin the same contract.</li> </ul> ERC-KeyHash20: Fungible Token Interface</h3> Interface</h4> interface</span> IERCKeyHash20</span> {</span></span> //</span> Events</span></span> event</span> KeyHashTransfer20</span>(</span>bytes32</span> indexed</span> fromKeyHash</span>, </span>bytes32</span> indexed</span> toKeyHash</span>, </span>uint256</span> amount</span>)</span>;</span></span> </span> //</span> View functions (aligned with ERC-20)</span></span> function</span> name</span>(</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span>;</span></span> function</span> symbol</span>(</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span>;</span></span> function</span> decimals</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint8</span>)</span>;</span></span> function</span> totalSupply</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> function</span> balanceOf</span>(</span>bytes32</span> keyHash</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> </span> //</span> State-changing functions</span></span> function</span> mint</span>(</span>bytes32</span> keyHash</span>,</span> uint256</span> amount</span>)</span> external</span>;</span></span> function</span> transfer</span>(</span>bytes32</span> fromKeyHash</span>,</span> bytes32</span> toKeyHash</span>,</span> uint256</span> amount</span>,</span> bytes</span> memory</span> key</span>,</span> bytes</span> memory</span> signature</span>,</span> uint256</span> deadline</span>,</span> bytes32</span> leftKeyHash</span>)</span> external</span>;</span></span> }</span></span></code></pre>Function Descriptions</h4> transfer</code></h5> transfer</span>(</span>bytes32</span> fromKeyHash</span>,</span> bytes32</span> toKeyHash</span>,</span> uint256</span> amount</span>,</span> bytes</span> memory</span> key</span>,</span> bytes</span> memory</span> signature</span>,</span> uint256</span> deadline</span>,</span> bytes32</span> leftKeyHash</span>)</span></span></code></pre> Description</strong>: Transfers amount</code> tokens from fromKeyHash</code> to toKeyHash</code>, with remaining balance assigned to leftKeyHash</code> (controlled by the sender). The caller provides the owner's key to prove ownership. The signature is verified using EIP-712</a> structured data. Mimics Bitcoin's UTXO model for partial transfers. Parameters</strong>:</p> fromKeyHash</code>: bytes32</code> - Token owner's key hash.</li> toKeyHash</code>: bytes32</code> - Recipient's key hash.</li> amount</code>: uint256</code> - Amount to transfer.</li> key</code>: bytes</code> - MUST be a 65-byte uncompressed secp256k1 public key with prefix 0x04.</li> signature</code>: bytes</code> - ECDSA signature.</li> deadline</code>: uint256</code> - Signature expiration timestamp.</li> leftKeyHash</code>: bytes32</code> - Key hash for remaining balance (balance - amount</code>). MUST NOT equal toKeyHash</code> or fromKeyHash</code> (strict mode to enforce key rotation and unlinkability). Signature Message</strong>: EIP-712</a> structured data: solidity struct Transfer { bytes32 fromKeyHash; bytes32 toKeyHash; uint256 amount; uint256 nonce; uint256 deadline; bytes32 leftKeyHash; } </code> Events</strong>: Emits KeyHashTransfer20(fromKeyHash, toKeyHash, amount)</code>. Requirements</strong>:</li> fromKeyHash</code> MUST have sufficient balance (balanceOf[fromKeyHash] >= amount</code>).</li> keccak256(key)</code> MUST equal fromKeyHash</code>.</li> Signature MUST be valid.</li> block.timestamp</code> MUST be <= deadline</code>.</li> toKeyHash</code> and leftKeyHash</code> MUST NOT be zero.</li> Updates balances: balanceOf[fromKeyHash] = 0</code>, balanceOf[toKeyHash] += amount</code>, balanceOf[leftKeyHash] += (original balance - amount)</code>.</li> </ul> Other Functions</strong>: name</code>, symbol</code>, decimals</code>, and totalSupply</code> align with ERC-20</a>. balanceOf</code> uses bytes32</code> parameter.</li> </ul> Signature Verification</h3> For transfer</code>:</p> Verify keccak256(key) == current keyHash</code>.</p> </li> Compute EIP-712</a> message hash:</p> bytes32</span> digest </span>=</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span></span> "\x19\x01"</span>,</span></span> DOMAIN_SEPARATOR</span>,</span></span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span> TYPE_HASH</span>,</span> //</span> Struct-specific type hash</span></span> params </span>//</span> Struct fields (e.g., tokenId, toKeyHash, nonce, deadline)</span></span> )</span>)</span></span> )</span>)</span>;</span></span></code></pre></li> Recover signer address using ecrecover(digest, signature)</code>.</p> </li> REQUIRE signer == address(uint160(uint256(keccak256(key[1:])))), where key is a 65‑byte uncompressed secp256k1 public key (0x04 \|\| X \|\| Y) and key[1:] denotes the 64‑byte XY payload (prefix removed)</p> </li> On successful verification, increment _keyNonces[currentOwnerKeyHash] (i.e., _keyNonces[ownerKeyHash] for ERC‑KeyHash721 and _keyNonces[fromKeyHash] for ERC‑KeyHash20) to prevent replay.</p> </li> Verify block.timestamp <= deadline</code>.</p> </li> </ol> Requirements</h3> Contracts MUST maintain mappings: ERC-KeyHash721: tokenId</code> to keyHash</code>.</li> ERC-KeyHash20: keyHash</code> to balance.</li> </ul> </li> MUST use per-keyHash nonces (mapping(bytes32 => uint256) _keyNonces</code>) for replay protection.</li> MUST implement EIP-712</a> for signature hashing.</li> MUST enforce deadline</code> to limit signature validity.</li> MUST verify signatures and hash keys in transfer</code>.</li> For ERC-KeyHash20, MUST enforce strict mode for leftKeyHash</code> by requiring it to be different from both toKeyHash</code> and fromKeyHash</code>. This prevents change consolidation with the recipient or original account, promoting key rotation and unlinkability.</li> </ul> Rationale</h2> Advantages of Key Hash</h3> Privacy</strong>: ownerOf</code> and balanceOf</code> return keyHash</code>, not addresses. Users can use unique key pairs per token or balance, reducing linkability.</li> Gas Fee Separation</strong>: Anyone can call transfer</code> with a valid signature, paying gas fees, enabling batch transactions or gas sponsorship.</li> Flexibility</strong>: Aligns with ERC-5564</a> stealth addresses, extending privacy to tokens.</li> </ul> Transfer Design</h3> Open to any caller with valid signatures, ensuring only owners operate while allowing gas sponsorship.</li> EIP-712</a> signatures prevent message tampering by including all critical parameters.</li> Per-keyHash nonces and deadlines prevent replay attacks.</li> </ul> Backwards Compatibility</h2> This proposal is not compatible with ERC-721</a> or ERC-20</a> due to bytes32</code> key hashes instead of addresses. Adapters can bridge to existing systems for privacy-focused use cases.</p> Reference Implementation</h2> ERC-KeyHash721 Implementation</h3> pragma</span> solidity</span> ^0.8.0</span>;</span></span> import</span> "@openzeppelin/contracts/utils/cryptography/ECDSA.sol"</span>;</span></span> import</span> "@openzeppelin/contracts/utils/cryptography/EIP712.sol"</span>;</span></span> </span> contract</span> KeyHashERC721</span> is</span> EIP712</span> {</span></span> using</span> ECDSA</span> for</span> bytes32</span>;</span></span> </span> string</span> public</span> name</span>;</span></span> string</span> public</span> symbol</span>;</span></span> mapping</span>(</span>uint256</span> =></span> bytes32</span>)</span> private</span> _tokenKeyHashes</span>;</span></span> mapping</span>(</span>uint256</span> =></span> bool</span>)</span> private</span> _destroyedTokens</span>;</span></span> uint256</span> public</span> totalSupply</span>;</span></span> mapping</span>(</span>bytes32</span> =></span> uint256</span>)</span> private</span> _keyNonces</span>;</span></span> </span> event</span> KeyHashTransfer721</span>(</span>uint256</span> indexed</span> tokenId</span>, </span>bytes32</span> indexed</span> fromKeyHash</span>, </span>bytes32</span> indexed</span> toKeyHash</span>)</span>;</span></span> event</span> KeyHashBurn721</span>(</span>uint256</span> indexed</span> tokenId</span>, </span>bytes32</span> indexed</span> ownerKeyHash</span>)</span>;</span></span> </span> bytes32</span> private</span> constant</span> TRANSFER_TYPEHASH </span>=</span> keccak256</span>(</span></span> "Transfer(uint256 tokenId,bytes32 toKeyHash,uint256 nonce,uint256 deadline)"</span></span> )</span>;</span></span> bytes32</span> private</span> constant</span> DESTROY_TYPEHASH </span>=</span> keccak256</span>(</span></span> "Destroy(uint256 tokenId,uint256 nonce,uint256 deadline)"</span></span> )</span>;</span></span> </span> constructor</span>(</span>string</span> memory</span> _name</span>,</span> string</span> memory</span> _symbol</span>)</span></span> EIP712</span>(</span>"KeyHashERC721", "1")</span></span> {</span></span> name </span>=</span> _name</span>;</span></span> symbol </span>=</span> _symbol</span>;</span></span> }</span></span> </span> function</span> ownerOf</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span> require</span>(</span>_tokenKeyHashes</span>[</span>tokenId</span>]</span> !=</span> 0</span> &&</span> !</span>_destroyedTokens</span>[</span>tokenId</span>]</span>,</span> "Token does not exist"</span>)</span>;</span></span> return</span> _tokenKeyHashes</span>[</span>tokenId</span>]</span>;</span></span> }</span></span> </span> function</span> tokenURI</span>(</span>uint256</span>)</span> external</span> pure</span> returns</span> (</span>string</span> memory</span>)</span> {</span> return</span> ""</span>;</span> }</span></span> </span> function</span> transfer</span>(</span></span> uint256</span> tokenId</span>,</span></span> bytes32</span> toKeyHash</span>,</span></span> bytes</span> memory</span> key</span>,</span></span> bytes</span> memory</span> signature</span>,</span></span> uint256</span> deadline</span></span> )</span> external</span> {</span></span> require</span>(</span>toKeyHash </span>!=</span> bytes32</span>(</span>0</span>)</span>,</span> "Invalid recipient hash"</span>)</span>;</span></span> require</span>(</span>_tokenKeyHashes</span>[</span>tokenId</span>]</span> !=</span> 0</span> &&</span> !</span>_destroyedTokens</span>[</span>tokenId</span>]</span>,</span> "Token does not exist"</span>)</span>;</span></span> require</span>(</span>block</span>.</span>timestamp </span><</span>=</span> deadline</span>,</span> "Signature expired"</span>)</span>;</span></span> require</span>(</span>key</span>.</span>length </span>==</span> 65</span> &&</span> key</span>[</span>0</span>]</span> ==</span> 0x04</span>,</span> "BAD_KEY_FMT"</span>)</span>;</span></span> bytes32</span> currentKeyHash </span>=</span> _tokenKeyHashes</span>[</span>tokenId</span>]</span>;</span></span> require</span>(</span>keccak256</span>(</span>key</span>)</span> ==</span> currentKeyHash</span>,</span> "BAD_KEYHASH"</span>)</span>;</span></span> </span></span> uint256</span> nonce </span>=</span> _keyNonces</span>[</span>currentKeyHash</span>]</span>;</span></span> bytes32</span> structHash </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span> TRANSFER_TYPEHASH</span>,</span></span> tokenId</span>,</span></span> toKeyHash</span>,</span></span> nonce</span>,</span></span> deadline</span></span> )</span>)</span>;</span></span> bytes32</span> digest </span>=</span> _hashTypedDataV4</span>(</span>structHash</span>)</span>;</span></span> address</span> signer </span>=</span> digest</span>.</span>recover</span>(</span>signature</span>)</span>;</span></span> address</span> expectedAddress </span>=</span> _addressFromUncompressedKey</span>(</span>key</span>)</span>;</span></span> require</span>(</span>signer </span>==</span> expectedAddress</span>,</span> "Invalid signature"</span>)</span>;</span></span> _keyNonces</span>[</span>currentKeyHash</span>]</span> =</span> nonce </span>+</span> 1</span>;</span> //</span> 验签通过后再自增</span></span> </span> _tokenKeyHashes</span>[</span>tokenId</span>]</span> =</span> toKeyHash</span>;</span></span> emit</span> KeyHashTransfer721</span>(</span>tokenId</span>,</span> currentKeyHash</span>,</span> toKeyHash</span>)</span>;</span></span> }</span></span> </span> </span> function</span> getNonce</span>(</span>bytes32</span> keyHash</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span> {</span></span> return</span> _keyNonces</span>[</span>keyHash</span>]</span>;</span></span> }</span></span> </span></span> function</span> _addressFromUncompressedKey</span>(</span>bytes</span> memory</span> key</span>)</span> internal</span> pure</span> returns</span> (</span>address</span>)</span> {</span></span> //</span> key: 65 bytes, [0] = 0x04, [1..32] = X, [33..64] = Y </span></span> require</span>(</span>key</span>.</span>length </span>==</span> 65</span> &&</span> key</span>[</span>0</span>]</span> ==</span> 0x04</span>,</span> "BAD_KEY_FMT"</span>)</span>;</span></span> bytes32</span> x</span>;</span></span> bytes32</span> y</span>;</span></span> assembly</span> {</span></span> x </span>:=</span> mload</span>(</span>add</span>(</span>key</span>,</span> 0x21</span>)</span>)</span> //</span> key[1..32] </span></span> y </span>:=</span> mload</span>(</span>add</span>(</span>key</span>,</span> 0x41</span>)</span>)</span> //</span> key[33..64] </span></span> }</span></span> bytes32</span> h </span>=</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>x</span>,</span> y</span>)</span>)</span>;</span> //</span> 64-byte XY </span></span> return</span> address</span>(</span>uint160</span>(</span>uint256</span>(</span>h</span>)</span>)</span>)</span>;</span></span> }</span></span> }</span></span></code></pre>ERC-KeyHash20 Implementation</h3> pragma</span> solidity</span> ^0.8.0</span>;</span></span> import</span> "@openzeppelin/contracts/utils/cryptography/ECDSA.sol"</span>;</span></span> import</span> "@openzeppelin/contracts/utils/cryptography/EIP712.sol"</span>;</span></span> </span> contract</span> KeyHashERC20</span> is</span> EIP712</span> {</span></span> using</span> ECDSA</span> for</span> bytes32</span>;</span></span> </span> string</span> public</span> name</span>;</span></span> string</span> public</span> symbol</span>;</span></span> uint8</span> public</span> decimals</span>;</span></span> mapping</span>(</span>bytes32</span> =></span> uint256</span>)</span> public</span> balanceOf</span>;</span></span> uint256</span> public</span> totalSupply</span>;</span></span> mapping</span>(</span>bytes32</span> =></span> uint256</span>)</span> private</span> _keyNonces</span>;</span></span> </span> event</span> KeyHashTransfer20</span>(</span>bytes32</span> indexed</span> fromKeyHash</span>, </span>bytes32</span> indexed</span> toKeyHash</span>, </span>uint256</span> amount</span>)</span>;</span></span> </span> bytes32</span> private</span> constant</span> TRANSFER_TYPEHASH </span>=</span> keccak256</span>(</span></span> "Transfer(bytes32 fromKeyHash,bytes32 toKeyHash,uint256 amount,uint256 nonce,uint256 deadline,bytes32 leftKeyHash)"</span></span> )</span>;</span></span> </span> constructor</span>(</span>string</span> memory</span> _name</span>,</span> string</span> memory</span> _symbol</span>)</span></span> EIP712</span>(</span>"KeyHashERC20", "1")</span></span> {</span></span> name </span>=</span> _name</span>;</span></span> symbol </span>=</span> _symbol</span>;</span></span> decimals </span>=</span> 18</span>;</span></span> }</span></span> </span> </span> function</span> transfer</span>(</span></span> bytes32</span> fromKeyHash</span>,</span></span> bytes32</span> toKeyHash</span>,</span></span> uint256</span> amount</span>,</span></span> bytes</span> memory</span> key</span>,</span></span> bytes</span> memory</span> signature</span>,</span></span> uint256</span> deadline</span>,</span></span> bytes32</span> leftKeyHash</span></span> )</span> external</span> {</span></span> require</span>(</span>balanceOf</span>[</span>fromKeyHash</span>]</span> ></span>=</span> amount</span>,</span> "Insufficient balance"</span>)</span>;</span></span> require</span>(</span>toKeyHash </span>!=</span> bytes32</span>(</span>0</span>)</span>,</span> "Invalid recipient hash"</span>)</span>;</span></span> require</span>(</span>leftKeyHash </span>!=</span> bytes32</span>(</span>0</span>)</span>,</span> "Invalid leftKeyHash"</span>)</span>;</span></span> require</span>(</span>leftKeyHash </span>!=</span> toKeyHash</span>,</span> "LEFT_EQ_TO"</span>)</span>;</span></span> require</span>(</span>leftKeyHash </span>!=</span> fromKeyHash</span>,</span> "LEFT_EQ_FROM"</span>)</span>;</span></span> require</span>(</span>block</span>.</span>timestamp </span><</span>=</span> deadline</span>,</span> "Signature expired"</span>)</span>;</span></span> require</span>(</span>key</span>.</span>length </span>==</span> 65</span> &&</span> key</span>[</span>0</span>]</span> ==</span> 0x04</span>,</span> "BAD_KEY_FMT"</span>)</span>;</span></span> require</span>(</span>keccak256</span>(</span>key</span>)</span> ==</span> fromKeyHash</span>,</span> "BAD_KEYHASH"</span>)</span>;</span></span> </span> uint256</span> nonce </span>=</span> _keyNonces</span>[</span>fromKeyHash</span>]</span>;</span></span> bytes32</span> structHash </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span> TRANSFER_TYPEHASH</span>,</span></span> fromKeyHash</span>,</span></span> toKeyHash</span>,</span></span> amount</span>,</span></span> nonce</span>,</span></span> deadline</span>,</span></span> leftKeyHash</span></span> )</span>)</span>;</span></span> bytes32</span> digest </span>=</span> _hashTypedDataV4</span>(</span>structHash</span>)</span>;</span></span> address</span> signer </span>=</span> digest</span>.</span>recover</span>(</span>signature</span>)</span>;</span></span> address</span> expectedAddress </span>=</span> _addressFromUncompressedKey</span>(</span>key</span>)</span>;</span></span> require</span>(</span>signer </span>==</span> expectedAddress</span>,</span> "Invalid signature"</span>)</span>;</span></span> _keyNonces</span>[</span>fromKeyHash</span>]</span> =</span> nonce </span>+</span> 1</span>;</span> //</span> 验签通过后再自增</span></span> </span> uint256</span> remaining </span>=</span> balanceOf</span>[</span>fromKeyHash</span>]</span> -</span> amount</span>;</span></span> balanceOf</span>[</span>fromKeyHash</span>]</span> =</span> 0</span>;</span></span> balanceOf</span>[</span>toKeyHash</span>]</span> +</span>=</span> amount</span>;</span></span> balanceOf</span>[</span>leftKeyHash</span>]</span> +</span>=</span> remaining</span>;</span></span> emit</span> KeyHashTransfer20</span>(</span>fromKeyHash</span>,</span> toKeyHash</span>,</span> amount</span>)</span>;</span></span> }</span></span> </span> function</span> getNonce</span>(</span>bytes32</span> keyHash</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span> {</span></span> return</span> _keyNonces</span>[</span>keyHash</span>]</span>;</span></span> }</span></span> </span> function</span> _addressFromUncompressedKey</span>(</span>bytes</span> memory</span> key</span>)</span> internal</span> pure</span> returns</span> (</span>address</span>)</span> {</span></span> //</span> key: 65 bytes, [0] = 0x04, [1..32] = X, [33..64] = Y </span></span> require</span>(</span>key</span>.</span>length </span>==</span> 65</span> &&</span> key</span>[</span>0</span>]</span> ==</span> 0x04</span>,</span> "BAD_KEY_FMT"</span>)</span>;</span></span> bytes32</span> x</span>;</span></span> bytes32</span> y</span>;</span></span> assembly</span> {</span></span> x </span>:=</span> mload</span>(</span>add</span>(</span>key</span>,</span> 0x21</span>)</span>)</span> //</span> key[1..32] </span></span> y </span>:=</span> mload</span>(</span>add</span>(</span>key</span>,</span> 0x41</span>)</span>)</span> //</span> key[33..64] </span></span> }</span></span> bytes32</span> h </span>=</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>x</span>,</span> y</span>)</span>)</span>;</span> //</span> 64-byte XY </span></span> return</span> address</span>(</span>uint160</span>(</span>uint256</span>(</span>h</span>)</span>)</span>)</span>;</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> Replay Attacks</strong>: Mitigation</strong>: Per-keyHash nonces (_keyNonces[keyHash]</code>) increment after each operation, invalidating old signatures.</li> Design</strong>: Similar to EIP-2612</a> permit mechanism, ensuring owner-controlled nonce sequences.</li> </ul> </li> Message Tampering</strong>: Mitigation</strong>: EIP-712</a> structured signatures include all critical parameters (tokenId</code>, toKeyHash</code>, amount</code>, leftKeyHash</code>, etc.), preventing relayer tampering. Signatures are function-specific (TRANSFER_TYPEHASH</code>, DESTROY_TYPEHASH</code>).</li> Audit</strong>: Contracts MUST be audited to ensure no parameter omissions or hash collisions.</li> </ul> </li> Signature Expiration</strong>: Mitigation</strong>: deadline</code> parameter ensures signatures expire, reducing risks of leaked signatures.</li> </ul> </li> Privacy Limitations</strong>: Issue</strong>: Public keys (key) are revealed in calldata; the corresponding Ethereum addresses can be derived off‑chain from keccak256(key[1:]). Use fresh keys (toKeyHash / leftKeyHash) to reduce linkability.</li> Recommendation</strong>: Use new key pairs per token or balance to minimize linkability. Store hashKey</code> securely, as it is sensitive.</li> </ul> </li> Key Management</strong>: Risk</strong>: Loss or compromise of the private key corresponding to key</code> results in loss of control. Store private keys securely.</li> Recommendation</strong>: Use safe systems to save key</code>.</li> </ul> </li> Gas Costs</strong>: Issue</strong>: Signature verification and EIP-712</a> hashing increase gas costs.</li> Recommendation</strong>: Optimize implementations and consider gas sponsorship to offset costs.</li> </ul> </li> Signature Malleability</strong>: Implementations MUST reject malleable signatures (low‑S, v ∈ {27, 28}). OpenZeppelin’s ECDSA helpers enforce these checks by default.</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Permissionless CREATE2 Factory 2025-05-15T00:00:00+00:00 Abstract</h2> This ERC defines a permissionless and deterministic deployment mechanism across all EVM-compatible chains. It uses the EIP-7702</a> Set Code for EOAs (0x4)</code> transaction type to deploy a universal CREATE2 factory contract to a fixed address (0xC0DEb853af168215879d284cc8B4d0A645fA9b0E</code>) with known bytecode. The factory can then create any new contract to a deterministic address using the EIP-1014</a> CREATE2 (0xf5)</code> opcode. It does not require preinstalls, secret keys, or chain-specific infrastructure.</p> Motivation</h2> Ensuring that contracts share the same address and code on multiple chains is a hard problem. It is typically done by having a known CREATE2 factory contract at a specific address that can further deterministically deploy new contracts using the CREATE2 (0xf5)</code> opcode.</p> However, there is a bootstrapping problem: how do you get a CREATE2 factory contract with a specific address and code?</p> Existing Solutions</h3> There are currently three main approaches to this problem:</p> 1. Nick's Method</h4> Use Nick's method to randomly generate a signature for a transaction without</strong> EIP-155</a> replay protection that deploys the CREATE2 factory. Nick's method ensures that there is no known private key for the account that deploys the CREATE2 factory, meaning that the resulting contract will have a deterministic address and code on all chains. This strategy is used by the Deterministic Deployment Proxy</em> (deployed to 0x4e59b44847b379578588920ca78fbf26c0b4956c</code>, including on Ethereum Mainnet), one of the most widely used CREATE2 factory contracts.</p> Downsides</strong>:</p> It does not work on chains that only accept EIP-155 replay-protected transactions.</li> It is sensitive to changes in gas parameters on the target chain since the gas price and limit in the deployment transaction is sealed, and a new one cannot be signed without a private key.</li> Reverts, such as those caused by alternative gas schedules, make the CREATE2 factory no longer deployable.</li> </ul> 2. Secret Private Key</h4> Keep a carefully guarded secret key and use it to sign transactions to deploy CREATE2 factory contracts. The resulting contract will have a deterministic address and code on all chains where the transaction at a given nonce of the deployer account is a CREATE2 factory deployment, which can be verified post-deployment to ensure trustlessness. Additionally, this method does not have the same gas sensitivity downsides as Nick's method, as the private key can sign a creation transaction with appropriate gas parameters at the time of execution. This is the strategy used by the Safe Singleton Factory</em> and CreateX</em> (deployed to 0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7</code> and 0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed</code> respectively, including on Ethereum Mainnet).</p> Downsides</strong>:</p> It is permissioned: the party that holds the secret key has the ultimate say on which chains will get the CREATE2 factory deployments.</li> This requires carefully guarding a secret key; if it is exposed or lost, deployments are no longer guaranteed on new chains.</li> If the transaction at the given nonce is not a successful CREATE2 factory deployment, then it is no longer possible to have a CREATE2 factory at the canonical address; this can happen by human error, for example.</li> </ul> 3. Preinstalls</h4> Have popular CREATE2 deployment factories deployed on new chains by default. This is, for example, what OP Stack and ZKsync do as part of their preinstalls, including the CREATE2 factory contracts mentioned above. This ensures that the CREATE2 factory contracts have known addresses and codes.</p> Downsides</strong>:</p> It is not standardized nor adopted by all chains.</li> It is permissioned as a chain can choose not to include a specific CREATE2 factory contract preinstalled.</li> Attempts to standardize this with RIP-7740 have not been successful.</li> </ul> Proposal: Using EIP-7702 Type 0x4</code> Transactions</h3> This ERC proposes a permissionless alternative fourth mechanism to the existing ones described above with none of their downsides. Additionally, it standardizes a set of deployment parameters for a universal</strong> CREATE2 factory deployment. This ensures a common CREATE2 factory for the community instead of multiple competing copies with slightly different codes at different addresses. This single CREATE2 factory copy can bootstrap additional deterministic deployment infrastructure (such as the comprehensive CreateX universal contract deployer).</p> Benefits</strong></p> Universally applicable: It can be executed on any chain by any user and guarantees a reliable determination of smart contract deployments on any chain.</li> Fault resistant: The method is secure against "out of gas" and other errors.</li> Permissionless: The universal CREATE2 factory contract can be deployed by anyone.</li> </ul> Specification</h2> 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.</p> Parameters</h3> Parameter</th> Value</th></tr></thead> DEPLOYER_PRIVATE_KEY</code></td> 0x942ba639ec667bdded6d727ad2e483648a34b584f916e6b826fdb7b512633731</code></td></tr> CREATE2_FACTORY_INIT_CODE</code></td> 0x7c60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f33d52601d6003f3</code></td></tr> CREATE2_FACTORY_SALT</code></td> 0x000000000000000000000000000000000000000000000000000000000001bec5</code></td></tr> </tbody></table> Derived Parameters</h3> Derived Parameter</th> Value</th></tr></thead> DEPLOYER_ADDRESS</code></td> 0x962560A0333190D57009A0aAAB7Bfa088f58461C</code></td></tr> CREATE2_FACTORY_ADDRESS</code></td> 0xC0DEb853af168215879d284cc8B4d0A645fA9b0E</code></td></tr> CREATE2_FACTORY_RUNTIME_CODE</code></td> 0x60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f3</code></td></tr> CREATE2_FACTORY_CODE_HASH</code></td> 0x2ad75e1e9642e6fce7d293d52fa5a8f62a79a2079abb7402256add02d6e8bc30</code></td></tr> </tbody></table> Definitions</h3> Deployer</strong>: The account corresponding to DEPLOYER_PRIVATE_KEY</code> with address DEPLOYER_ADDRESS</code>.</li> CREATE2 factory contract</strong>: A contract that deploys other contracts with CREATE2 (0xf5)</code> opcode, allowing smart contracts to be deployed to deterministic addresses.</li> Bootstrap contract</strong>: The contract that the deployer</em> delegates to in order to deploy the CREATE2 factory contract</em>.</li> Bootstrapping code</strong>: The critical code in the bootstrap contract</em> that performs the CREATE2 (0xf5)</code> deployment of the CREATE2 factory contract</em>.</li> </ul> Bootstrap Contract</h3> The bootstrap contract</em> MUST execute the following or equivalent bootstrapping code</em> as an EIP-7702 delegation target for the deployer</em> account:</p> bytes</span> memory</span> initCode </span>=</span> CREATE2_FACTORY_INIT_CODE</span>;</span></span> bytes32</span> salt </span>=</span> CREATE2_FACTORY_SALT</span>;</span></span> assembly</span> (</span>"memory-safe"</span>)</span> {</span></span> create2</span>(</span>0</span>,</span> add</span>(</span>initCode</span>,</span> 32</span>)</span>,</span> mload</span>(</span>initCode</span>)</span>,</span> salt</span>)</span></span> }</span></span></code></pre> The bootstrap contract</em> MAY implement additional features such as:</p> Abort early if either CREATE2 factory contract</em> is already deployed or the deployer</em> is not correctly delegated to. This can help mitigate gas griefing from the front-running issue described below.</li> </ul> </li> Additional verification that the deployment succeeded as expected.</li> Emit events to facilitate tracking of either the bootstrap contract</em> or CREATE2 factory contract</em> deployments.</li> </ul> Deployment Process</h3> Deploy a bootstrap contract</em> described in the previous section.</li> Sign an EIP-7702 authorization using the DEPLOYER_PRIVATE_KEY</code> delegating to the bootstrap contract</em>.</li> Execute an EIP-7702 type 0x4</code> transaction with the authorization from step 2; the transaction MUST call DEPLOYER_ADDRESS</code> (either</strong> directly or indirectly) which delegates to the bootstrap contract</em> and MUST perform the CREATE2 (0xf5)</code> of the CREATE2_FACTORY_INIT_CODE</code> with CREATE2_FACTORY_SALT</code> in the bootstrapping code</em>.</li> </ol> Assuming successful execution of the bootstrapping code</em> without reverting in the context of the deployer</em>, the CREATE2 factory contract</em> will be deployed to CREATE2_FACTORY_ADDRESS</code> with code CREATE2_FACTORY_RUNTIME_CODE</code> and code hash CREATE2_FACTORY_CODE_HASH</code>.</p> Rationale</h2> Deployment Mechanism</h3> The deployment mechanism was chosen such that it is uniquely parameterized by the DEPLOYER_ADDRESS</code> (which itself is derived from the DEPLOYER_PRIVATE_KEY</code> and is therefore deterministic), the CREATE2_FACTORY_INIT_CODE</code> and the CREATE2_FACTORY_SALT</code> which are both fixed and deterministic. Additionally, since the DEPLOYER_ADDRESS</code> will deploy the CREATE2 factory contract with the CREATE2 (0xf5)</code> opcode, this guarantees that the address and code of the contract are deterministic.</p> The use of a publicly known private key enables this mechanism, as anyone can permissionlessly generate a delegation signature to any</strong> bootstrap contract that would cause the DEPLOYER_ADDRESS</code> to execute the specified CREATE2 (0xf5)</code> operation and deploy the factory contract to a completely deterministic address. Because of the use of CREATE2 (0xf5)</code>, the CREATE2 factory will be deployed to CREATE2_FACTORY_ADDRESS</code> if and only if it is deployed with CREATE2_FACTORY_INIT_CODE</code>, thus guaranteeing a deployed code hash of CREATE2_FACTORY_CODE_HASH</code>. Additionally, the semantics of CREATE2 (0xf5)</code> make it so no transaction executed by DEPLOYER_ADDRESS</code> can permanently block the deployment of the CREATE2 factory contract to CREATE2_FACTORY_ADDRESS</code>.</p> One issue with this method is that because the DEPLOYER_PRIVATE_KEY</code> is public, anyone can sign alternative delegations or transactions and front-run a legitimate CREATE2 factory deployment. The front-running would increase the nonce of the DEPLOYER_ADDRESS</code> account and render the EIP-7702 authorization in the legitimate CREATE2 factory deployment transaction invalid, causing the deployment to potentially fail. This is not considered to be a serious issue, however, as:</p> Doing so does not prevent future deployments - meaning that an attacker can only delay the deployment of the CREATE2 factory with a sustained attack at a gas cost to the attacker, but not permanently prevent it from happening.</li> The damage is limited to gas griefing for accounts that are legitimately trying to deploy the CREATE2 factory contract. Furthermore, the reference implementation was coded to minimize the gas griefing damage.</li> In the case of a very persistent malicious actor, their attack can be circumvented by either making use of private transactions or working directly with block builders.</li> </ol> Another known issue with this method is that a future network upgrade may introduce new mechanisms (such as a new opcode or transaction type) to permanently set an account's code. If this were to happen, and since the DEPLOYER_PRIVATE_KEY</code> is publicly known, the DEPLOYER_ADDRESS</code> account's code could be mistakenly or maliciously set to something that does not execute the necessary bootstrapping code, permanently preventing any future deployment of the CREATE2 factory contract. If this ERC were to gain sufficient adoption, this is not believed to be an issue as:</p> The deployment on Ethereum Mainnet would already exist, and the DEPLOYER_PRIVATE_KEY</code> would no longer have any value on Ethereum Mainnet.</li> An RIP can be adopted to ensure that CREATE2_FACTORY_ADDRESS</code> has code CREATE2_FACTORY_RUNTIME_CODE</code>.</li> </ol> Publicly Known Private Key Instead of Nick's Method</h3> Instead of using a publicly known DEPLOYER_PRIVATE_KEY</code>, Nick's method can be used to generate a random EIP-7702 authorization signature. This would prevent the front-running and forward compatibility issues described above.</p> However, in order for Nick's method to work, the EIP-7702 authorization message that is signed, defined as keccak(MAGIC \|\| rlp([chain_id, address, nonce]))</code>, must be constant. MAGIC</code> is already a constant; chain_id</code> can be trivially fixed to 0</code> to specify a chain-agnostic EIP-7702 authorization; nonce</code> can also be trivially fixed to 0</code> because Nick's method ensures the authority has no known private key, meaning it cannot sign another message that would increment the nonce. However, fixing address</code> is problematic. Doing so would require a contract with specific code to be deployed to the same address on all chains, which is the original bootstrapping problem the proposed permissionless CREATE2 factory aims to solve. Therefore, this creates a "chicken and egg problem", making it not a viable way to generate an EIP-7702 authorization signature.</p> Use of CREATE2 Factory Contract</h3> This mechanism allows the DEPLOYER_ADDRESS</code> to do any CREATE2 (0xf5)</code> deployment, so it would be possible to forgo the intermediary CREATE2 factory contract and use the deployer technique for all deployments. There are multiple downsides to this, however:</p> All contract deployments are subject to the front-running issue described above, which could become an annoyance</li> Concurrent deployments from the deployer are subject to race conditions since EIP-7702 authorizations increase the account nonce. This means that if two deployments are submitted to the mempool without knowing about each other, only the first one will actually succeed, because the EIP-7702 authorization in the second transaction is for an outdated nonce. This is not an issue when deployers are trying to deploy the same contract as proposed in this ERC since even if the second delegation and transaction fails, the contract would have been deployed as desired.</li> </ul> Multiple Transaction Procedure</h3> Unfortunately, EIP-7702 type 0x4</code> transactions are restricted to to</code> values that are not null</code>, meaning that you cannot simultaneously deploy the bootstrap contract</em> and delegate to it in a single transaction.</p> Choice of Deployer Private Key</h3> The DEPLOYER_PRIVATE_KEY</code> was chosen as the private key at derivation path m/44'/60'/0'/0/0</code> for the mnemonic make code code code code code code code code code code coconut</code>.</p> Choice of Salt</h3> The CREATE2_FACTORY_SALT</code> was chosen as the first</strong> salt value starting from 0</code> such that the CREATE2 factory's ERC-55</a> checksum address starts with the case sensitive 0xC0DE...</code> prefix. A verifiable method for mining a vanity address for the CREATE2 factory contract was chosen in order to ensure that the ERC authors did not find a CREATE2 hash collision on the CREATE2_FACTORY_ADDRESS</code> that they can exploit at some point in the future.</p> CREATE2 Factory Bytecode</h3> The CREATE2 factory has a similar interface to existing implementations. Namely, it accepts salt \|\| init_code</code> as input, which is a 32-byte salt</code> value concatenated with the init_code</code> of the contract to deploy. It will execute a CREATE2</code> with the specified salt</code> and init_code</code>, deploying a contract with init_code</code> to keccak256(0xff \|\| CREATE2_FACTORY_ADDRESS \|\| salt \|\| keccak256(init_code))[12:]</code>. This contract returns the address of the created contract padded to 32 bytes. This differs from some existing implementations, but was done to maintain consistency with the 32-byte word size on the EVM (same encoding as ecrecover</code> precompile for example). A product of this is that the return data from CREATE2 factory is compatible with the Solidity ABI. In the case where the execution of init_code</code> were to fail, any revert data is propagated to the caller.</p> Throughout both the CREATE2 factory contract initialization and runtime code, RETURNDATASIZE (0x3d)</code> is used to push 0</code> onto the stack instead of the dedicated PUSH0 (0x5f)</code> opcode. This is done to increase compatibility with chains that support EIP-7702 but not EIP-3855</a>, while remaining a 1-byte and 2-gas opcode.</p> The CREATE2_FACTORY_INIT_CODE</code> corresponds to the following assembly:</p> # SPDX-License-Identifier: CC0-1.0</span></span> </span> ### Constructor Code ###</span></span> </span> 0x0000: PUSH29 0x60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f3</span></span> # Stack: [runcode] \| Push the CREATE2 factory runtime code, left padded</span></span> # with three 0 bytes</span></span> 0x001e: RETURNDATASIZE # Stack: [0; runcode] \| Push the offset in memory to store the code</span></span> 0x001f: MSTORE # Stack: [] \| The runtime code is now in `memory[3:32]`, because of</span></span> # the 3 bytes of 0-padding</span></span> 0x0020: PUSH1 29 # Stack: [29] \| Push the code length</span></span> 0x0022: PUSH1 3 # Stack: [3; 29] \| Push the memory offset of the start of code</span></span> 0x0024: RETURN # Stack: [] \| Return the runtime code</span></span></code></pre> The CREATE2_FACTORY_RUNTIME_CODE</code> corresponds to the following assembly:</p> # SPDX-License-Identifier: CC0-1.0</span></span> </span> ### Runtime Code ###</span></span> </span> # Prepare the stack, push 32, a value that will used a lot and can summon with</span></span> # `DUP` to save on one byte of code (over `PUSH1 32`), and a 0 which will be</span></span> # used by either the `RETURN` or `REVERT` branches at the end.</span></span> 0x0000: PUSH1 32 # Stack: [32]</span></span> 0x0002: RETURNDATASIZE # Stack: [0; 32]</span></span> </span> # First, load the salt value and compute the actual code size for the CREATE2</span></span> # call, this is the calldata length minus 32 for the salt prefix.</span></span> # Stack: [0; 32]</span></span> 0x0003: RETURNDATASIZE # Stack: [0; 0; 32] \| Push the calldata offset 0 of the `salt` parameter</span></span> 0x0004: CALLDATALOAD # Stack: [salt; 0; 32] \| Load the `salt` from calldata</span></span> 0x0005: DUP3 # Stack: [32; salt; 0; 32] \| Push 32 to the stack</span></span> 0x0006: CALLDATASIZE # Stack: [msg.data.len; 32; salt; ...] \| Followed by the calldata length</span></span> 0x0007: SUB # Stack: [code.len; salt; 0; 32] \| Compute `msg.data.length - 32`, which is the length of</span></span> # the init `code`</span></span> </span> # Copy the init code to memory offset 0. Note that if the call to the contract</span></span> # incorrectly encoded, this will revert with "out of gas", as it will attempt</span></span> # to copy ~2256 bytes of calldata to memory.</span></span> # Stack: [code.len; salt; 0; 32]</span></span> 0x0008: DUP1 # Stack: [code.len; .; salt; 0; 32] \| Duplicate the length of the init code</span></span> 0x0009: DUP5 # Stack: [32; code.len; ...] \| Push the offset in calldata of the code, which is 32</span></span> # as it comes immediately after the 32-byte `salt`; use</span></span> # the 32 value at the bottom of the stack</span></span> 0x000a: RETURNDATASIZE # Stack: [0; 32; code.len; ...] \| Push the offset (0) in memory to copy the code to</span></span> 0x000b: CALLDATACOPY # Stack: [code.len; salt; 0; 32] \| Copy the init code, `memory[0:code.len]` contains the</span></span> # init `code`</span></span> </span> # Deploy the contract.</span></span> # Stack: [code.len; salt; 0; 32]</span></span> 0x000c: RETURNDATASIZE # Stack: [0; code.len; salt; 0; 32] \| Push the offset in memory starting of the start of</span></span> # init `code`, which is 0</span></span> 0x000d: CALLVALUE # Stack: [v; 0; code.len; salt; 0; 32] \| Forward the call value to the contract constructor</span></span> 0x000e: CREATE2 # Stack: [address; 0; 32] \| Do `create2(v, code, salt)`, which leaves the address</span></span> # of the contract on the stack, or 0 if the contract</span></span> # creation reverted</span></span> </span> # Verify the deployment was successful and return the address.</span></span> # Stack: [address; 0; 32]</span></span> 0x000f: DUP1 # Stack: [address; .; 0; 32] \| Duplicate the address value</span></span> 0x0010: PUSH1 0x19 # Stack: [0x0019; address; .; 0; 32] \| Push the jump destination offset for the code which</span></span> # handles successful deployments</span></span> 0x0012: JUMPI # Stack: [address; 0; 32] \| Jump if `address != 0`, i.e. `CREATE2` succeeded</span></span> </span> # CREATE2 reverted, propagate the revert data.</span></span> # Stack: [address = 0; 0; 32]</span></span> 0x0013: RETURNDATASIZE # Stack: [r.len; 0; 0; 32] \| Push the revert data length onto the stack</span></span> 0x0014: DUP2 # Stack: [0; r.len; 0; 0; 32] \| Push 0 on to the stack by duplicating; note that</span></span> # `PUSH0` is intentionally do not used for increased</span></span> # compatibility with chains that do not implement that</span></span> # specific opcode</span></span> 0x0015: RETURNDATASIZE # Stack: [r.len; 0; r.len; 0; 0; 32] \| Push the revert data length onto the stack again</span></span> 0x0016: SWAP4 # Stack: [0; 0; r.len; 0; r.len; 32] \| Reorder the stack so that both `RETURNDATACOPY` and</span></span> # `REVERT` can be called; this is done by swapping the</span></span> # revert data length on the top of the stack with the</span></span> # bottom-most 0</span></span> 0x0017: RETURNDATACOPY # Stack: [0; r.len; 32] \| Copy the revert data to `memory[0:r.len]`</span></span> 0x0018: REVERT # Stack: [32] \| Revert with `memory[0:r.len]`</span></span> </span> # CREATE2 succeeded.</span></span> 0x0019: JUMPDEST # Stack: [address; 0; 32]</span></span> 0x001a: RETURNDATASIZE # Stack: [0; address; 0; 32] \| Push the memory offset (0) to store return data at,</span></span> # `RETURNDATASIZE` is used as contract creation was</span></span> # successful, and therefore the return data has size 0</span></span> 0x001b: MSTORE # Stack: [0; 32] \| Store the address in memory, `memory[0:32]` contains</span></span> # the `address` left padded to 32-bytes</span></span> 0x001c: RETURN # Stack: [] \| Return `memory[0:32]`, i.e. the address</span></span></code></pre>Backwards Compatibility</h2> There are a few backwards compatibility considerations with the new proposal:</p> It requires an EVM chain with EIP-7702 enabled. This means not all chains can use this deployment method.</li> It would deploy yet another CREATE2 factory contract that would need to be adopted by tooling.</li> The proposed CREATE2 factory implementation returns the newly created contract address padded to 32 bytes. This is different to some existing contracts that return unpadded 20-byte address value.</li> The proposed CREATE2 factory implementation propagates revert data. This is different to some existing contracts that just revert with empty data in case executing the CREATE2 initialization code fails.</li> </ol> Reference Implementation</h2> This proposal includes a reference implementation of a bootstrap contract to which the deployer account can delegate. The reference implementation expects a call to Bootstrap</code> to the function deploy()</code> in an EIP-7702 type 0x4</code> transaction including the EIP-7702 authorization delegating DEPLOYER_ADDRESS</code> to Bootstrap</code> (NOTE: the Bootstrap</code> is called as an entry point, instead of calling DEPLOYER_ADDRESS</code> directly which allows the contract to do some up-front checks to minimize gas griefing risk):</p> //</span> SPDX-License-Identifier: CC0-1.0</span></span> pragma</span> solidity</span> ^0.8.29</span>;</span></span> </span> contract</span> Bootstrap</span> {</span></span> address</span> private</span> constant</span> _DEPLOYER_ADDRESS </span>=</span> 0x962560A0333190D57009A0aAAB7Bfa088f58461C</span>;</span></span> address</span> private</span> constant</span> _CREATE2_FACTORY_ADDRESS </span>=</span> 0xC0DEb853af168215879d284cc8B4d0A645fA9b0E</span>;</span></span> bytes32</span> private</span> constant</span> _CREATE2_FACTORY_CODE_HASH </span>=</span> hex</span>"2ad75e1e9642e6fce7d293d52fa5a8f62a79a2079abb7402256add02d6e8bc30"</span>;</span></span> bytes</span> private</span> constant</span> _CREATE2_FACTORY_INIT_CODE </span>=</span> hex</span>"7c60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f33d52601d6003f3"</span>;</span></span> bytes32</span> private</span> constant</span> _CREATE2_FACTORY_SALT </span>=</span> hex</span>"000000000000000000000000000000000000000000000000000000000001bec5"</span>;</span></span> </span> error</span> InvalidDelegation</span>(</span>)</span>;</span></span> error</span> CreationFailed</span>(</span>)</span>;</span></span> </span> function</span> deploy</span>(</span>)</span> external</span> {</span></span> if</span> (</span>_CREATE2_FACTORY_ADDRESS</span>.</span>codehash </span>==</span> _CREATE2_FACTORY_CODE_HASH</span>)</span> {</span></span> return</span>;</span></span> }</span></span> </span> bytes32</span> delegation </span>=</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>hex</span>"ef0100"</span>,</span> this</span>)</span>)</span>;</span></span> require</span>(</span>_DEPLOYER_ADDRESS</span>.</span>codehash </span>==</span> delegation</span>,</span> InvalidDelegation</span>(</span>)</span>)</span>;</span></span> </span> Bootstrap</span>(</span>_DEPLOYER_ADDRESS</span>)</span>.</span>bootstrap</span>(</span>)</span>;</span></span> }</span></span> </span> function</span> bootstrap</span>(</span>)</span> external</span> {</span></span> bytes</span> memory</span> initCode </span>=</span> _CREATE2_FACTORY_INIT_CODE</span>;</span></span> bytes32</span> salt </span>=</span> _CREATE2_FACTORY_SALT</span>;</span></span> </span> address</span> factory</span>;</span></span> assembly</span> (</span>"memory-safe"</span>)</span> {</span></span> factory </span>:=</span> create2</span>(</span>0</span>,</span> add</span>(</span>initCode</span>,</span> 32</span>)</span>,</span> mload</span>(</span>initCode</span>)</span>,</span> salt</span>)</span></span> }</span></span> </span> require</span>(</span>factory </span>==</span> _CREATE2_FACTORY_ADDRESS</span>,</span> CreationFailed</span>(</span>)</span>)</span>;</span></span> }</span></span> }</span></span></code></pre> A minimal bootstrap contract implementation is also possible (although this has a higher potential for gas griefing). The minimal bootstrap contract expects a call directly to the DEPLOYER_ADDRESS</code> in an EIP-7702 type 0x4</code> transaction including the EIP-7702 authorization delegating DEPLOYER_ADDRESS</code> to MiniBootstrap</code>:</p> //</span> SPDX-License-Identifier: CC0-1.0</span></span> pragma</span> solidity</span> ^0.8.29</span>;</span></span> </span> contract</span> MiniBootstrap</span> {</span></span> bytes</span> private</span> constant</span> _CREATE2_FACTORY_INIT_CODE </span>=</span> hex</span>"7c60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f33d52601d6003f3"</span>;</span></span> bytes32</span> private</span> constant</span> _CREATE2_FACTORY_SALT </span>=</span> hex</span>"000000000000000000000000000000000000000000000000000000000001bec5"</span>;</span></span> </span> fallback</span>(</span>)</span> external</span> {</span></span> bytes</span> memory</span> initCode </span>=</span> _CREATE2_FACTORY_INIT_CODE</span>;</span></span> assembly</span> (</span>"memory-safe"</span>)</span> {</span></span> pop</span>(</span>create2</span>(</span>0</span>,</span> add</span>(</span>initCode</span>,</span> 32</span>)</span>,</span> mload</span>(</span>initCode</span>)</span>,</span> _CREATE2_FACTORY_SALT</span>)</span>)</span></span> }</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> It is possible to front-run transactions that invalidate the deployer's EIP-7702 delegation and cause the deployment to fail. This, however, comes at a gas cost to the attacker, with limited benefit beyond delaying the deployment of the CREATE2 factory. Additionally, persistent attackers can be circumvented by either using private transaction queues or working with block builders directly to ensure that the EIP-7702 bootstrapping transaction is not front-run.</p> Future Network Upgrades</h3> If new EVM opcodes or transaction types are introduced in future network upgrades that allow an account to permanently set its code, then this method is no longer guaranteed to work. The deployer account can permanently change its code to a contract that does not have the required bootstrapping code. This can trivially be done by a malicious actor using the publicly known DEPLOYER_PRIVATE_KEY</code> and would prevent any future deployments of CREATE2 factory.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Unidirectional Wallet Uplink aka UWULink 2025-05-10T00:00:00+00:00 Abstract</h2> Universal Wallet Uplink (UWULink) is a protocol that allows applications (dApps) to request a wallet to make a batch of contract calls in a single atomic transaction without establishing a two-way connection or revealing the user's address to the requester. The protocol defines a compact binary message format using Protocol Buffers suitable for low-bandwidth channels such as QR codes or NFC tags. Two modes of operation are supported: Static Mode</strong>, where the request payload directly contains the list of calls, and Programmable Mode</strong>, where the payload references a contract that generates the list of calls.</p> Motivation</h2> dApps often require users to perform multistep interactions, such as approving a token and then executing a swap. Traditionally, accomplishing this has required multiple user confirmations or complex wallet connectivity. Recent standards like EIP-5792</a> and EIP-7702</a> introduced ways to batch multiple calls into one atomic operation via JSON-RPC (e.g. wallet_sendCalls</code>). However, current implementations of those solutions assume an active connection between dApp and wallet (e.g. injected provider or WalletConnect session), which creates an additional layer of UX friction. There is a growing need for a privacy-preserving, frictionless workflow</strong> where a dApp or product can trigger complex transactions without “connecting” their wallet or needing to disclosing their address to the application.</p> Several trends highlight this need:</p> Atomic Multi-Call Transactions:</strong> With the advent of account abstraction features like EIP-7702</a>, externally owned accounts (EOAs) can execute batch transactions</strong> a la smart contract wallets. Users expect to combine multiple actions (e.g. token approvals, swaps, transfers) into one confirmed transaction for better UX and guaranteed all-or-nothing execution. Developers likewise want to avoid partial failures or multiple prompts.</p> </li> Privacy Concerns:</strong> Current wallet connection flows (EIP-1193</a> / EIP-1102</a>) require dApps to request access to user accounts, linking the user's address with the dApp even before a transaction is made. By decoupling transaction construction from user identification, we improve privacy. The wallet should not need to announce “who” it is to the dApp just to receive a transaction request. A one-way communication means the dApp never learns the user's address or other account info, mitigating tracking and profiling risks.</p> </li> One-Way Offline Interaction:</strong> In many use cases (desktop-to-mobile workflows, point-of-sale terminals, printed media), it’s desirable to communicate a transaction request via a QR code, NFC tag, or URL without establishing a session. Protocols like WalletConnect provide a session-based two-way link, but are heavyweight when a simple one-off action is needed, and they reveal the user's account to the dApp. A unidirectional link allows, for example, a user to scan a QR code on a webpage or poster and complete an on-chain action entirely within their wallet app. This also enables fully offline dApps to hand off transactions securely to user devices.</p> </li> Compactness for QR/NFC:</strong> Encoding transaction data for use in QR codes or NFC imposes strict size limits. Prior standards (e.g. EIP-681</a> Ethereum URIs) used human-readable formats that become lengthy when including contract data (hex-encoded addresses and calldata inflate the size). WalletConnect addressed some issues by introducing a more efficient URI scheme (ERC-1328</a>) instead of embedding JSON in QR codes. UWULink builds on this principle by using a concise binary serialization (Protocol Buffers), allowing more data to be communicated in a QR code or NFC tap.</p> </li> Programmability and Offloading Logic:</strong> There are scenarios where the exact list of calls depends on on-chain state or user-specific data (for example, an airdrop claim that needs to gather all tokens claimable by that user, or a DeFi interaction where allowances may already exist). In such cases, encoding all call data statically could be unwieldy or inefficient if the dApp lacks knowledge of the user's address. UWULink’s Programmable Mode</strong> allows a dApp to redirect to a deterministic on-chain generator (a smart contract with a standard interface) that can produce the list of calls that the wallet should invoke. This allows the app to invoke arbitrary logic in generating the list of calls based on the state of the blockchain, still without exposing the user's address.</p> </li> </ul> By addressing these points, UWULink aims to enhance user experience with one-shot multi-call transactions and improve security and privacy by eliminating unnecessary data sharing.</p> Specification</h2> Overview</h3> UWULink</strong> defines a protobuf message format and interpretation for transaction requests sent from a dApp to a wallet. The only operation in scope is a request for the wallet to execute an atomic batch of contract calls</strong> on an EVM-compatible blockchain. The wallet, upon receiving a UWULink request (for example, via a QR code scan, deep link, or NFC), will decode it, present the details to the user for confirmation, and if approved, execute the calls as a single transaction on the specified chain.</p> Key characteristics of the protocol:</p> Unidirectional Communication:</strong> Communication is only dApp → wallet</strong>. The dApp encodes a request and the wallet handles it. There is no handshake or return channel in the protocol itself. The wallet is not required (or able) to send any data back to the dApp. This one-way design ensures the dApp does not learn any information about the user or wallet (such as the address or which wallet app is used) at request time. It also simplifies implementation – the dApp’s job is simply to generate a batch of calls and display it, and the wallet’s job is to execute or reject the batch.</p> </li> Atomic Batch Calls:</strong> All calls listed in the request MUST</strong> be executed atomically, i.e. all succeed or all fail together. If any specific call would revert, the wallet should revert the entire batch.</p> </li> No Identity / Auth Required:</strong> Because the request is self-contained, the wallet does not need to pre-authorize the dApp or reveal the selected account. In traditional injected scenarios, a dApp would call eth_requestAccounts</code> (as per EIP-1102</a>) to get the user's address. With UWULink, the first and only interaction is the user willingly importing the transaction request (e.g. scanning the QR). The wallet should treat it similarly to how it would treat a transaction payload from a connected dApp, except no connection context exists. If the request is malformed or not supported, the wallet can simply alert the user and refuse.</p> </li> Binary Encoding:</strong> UWULink messages are encoded as a binary blob based on a Protocol Buffers schema. This blob is then further encoded into a URI for transport via QR code or NFC tag. The string encoding of a request is the uwulink:</code> scheme followed by the base 64 encoded message:</p> uwulink:<base64_of_UWULink_message></span></span></code></pre></li> Chain Identification:</strong> The message includes a chain ID to indicate which chain the calls are intended for. The wallet must verify or use this chain ID when executing the transaction. If the wallet is not currently on the target chain, it SHOULD prompt the user to switch to that chain or automatically switch if permissible (similar to handling of chainId</code> in EIP-681</a> URIs). If the wallet cannot operate on the requested chain, it must reject the request. This ensures that the dApp’s intent (which chain’s contracts to interact with) is preserved and avoids confusion if the user is on a different network.</p> </li> Static vs Programmable Mode:</strong> There are two mutually exclusive ways to specify the batch of calls:</p> Static Mode:</strong> The request directly contains the list of calls (each with target address, calldata, and optionally ETH value) that the wallet should execute in order. This mode is straightforward and similar to existing multi-call APIs (e.g. the JSON-RPC wallet_sendCalls</code> payload from EIP-5792</a>), but encoded in a compact binary form. This is ideal when the dApp knows exactly what actions need to be performed.</li> Programmable Mode:</strong> The request contains a reference to an on-chain “resolver” contract</strong> and an input data blob. The wallet will call a predefined view function on that contract (off-chain, via eth_call</code>) to retrieve the actual list of calls</strong> to execute. The resolver contract must implement a standardized interface (detailed below) that takes the provided input (and possibly the caller’s address or other context) and returns a set of calls. This mode allows dynamic computation of call lists at execution time. It improves flexibility (the dApp can offload complex logic or personalization to the blockchain) and keeps the QR/NFC payload small since it only carries a contract address and input, rather than every call’s details. For example, a dApp could include just a reference like “resolver contract X with input Y” and that contract’s resolver function will output perhaps dozens of calls based on the latest on-chain state, the user's address, etc.</li> </ol> </li> </ul> The UWULink message includes a oneof/union to indicate which mode is used. Wallets SHOULD</strong> support both modes.</p> Protobuf Schema</h3> Below is the proposed Protocol Buffers v3 schema defining the UWULink message format:</p> syntax = "proto3";</span></span> </span> package org.ethereum.uwulink;</span></span> </span> // The top-level UWULink transaction request message.</span></span> message UWULinkRequest {</span></span> uint64 chain_id = 1; // EIP-155 chain ID for the target chain</span></span> </span> oneof request_type {</span></span> Batch batch = 2;</span></span> ResolverReference resolver = 3;</span></span> }</span></span> }</span></span> </span> // Static batch of calls</span></span> message Batch {</span></span> repeated Call calls = 1;</span></span> }</span></span> </span> // Single contract call</span></span> message Call {</span></span> bytes to = 1; // 20-byte address of target contract</span></span> optional bytes value = 2; // (optional) up to 32-byte big-endian ETH value</span></span> optional bytes data = 3; // (optional) calldata for the call</span></span> }</span></span> </span> // Reference to a resolver contract for dynamic call generation</span></span> message ResolverReference {</span></span> bytes resolver_address = 1; // 20-byte address of resolver contract</span></span> bytes resolver_data = 2; // opaque data to pass to resolver</span></span> }</span></span></code></pre> Notes on the schema:</strong></p> We use bytes</code> for addresses and other binary data. A conforming wallet implementation MUST enforce that Call.to</code> and ResolverReference.resolver_address</code> are exactly 20 bytes. The protobuf itself won't enforce length, but using a different length should cause the wallet to reject the message (to avoid ambiguity or mis-interpretation). The value</code> field in Call</code> can be 0 bytes (interpreted as 0 ETH) up to 32 bytes. Leading zeros in value</code> SHOULD be stripped in the encoding for consistency (e.g., 1 wei would be encoded as 0x01</code> not 32 bytes padded; conversely the decoder should treat a missing value</code> or empty value</code> as 0).</p> </li> All fields are numbered for efficient encoding. The oneof request_type</code> ensures only one of Batch or ResolverReference is in use. If an unknown field is present (e.g., a future extension), the wallet should ignore those unknown fields per protobuf default behavior, but core fields must be present for validity (chain_id and one of batch/resolver).</p> </li> If using a text encoding (like Base64) to embed in a URI, the entire UWULinkRequest</code> message is serialized to a binary string, then that binary is base64-encoded. For URI safety, base64 output may need to be URL-encoded (i.e., +</code>, /</code> characters percent-encoded or using the URL-safe base64 variant). This is an implementation detail, but wallet developers should be aware when parsing input. In all cases, the underlying data after decoding is expected to match the protobuf schema above.</p> </li> The schema is chosen for broad compatibility. Proto3's varint encoding will handle the chain_id</code> (which is usually small like 1, 137, etc.) in 1-2 bytes. The calls</code> repeated field will simply concatenate call entries. Each call entry will have a 1-byte field tag for to</code> followed by 20 bytes address, etc. This results in a very compact representation.</p> </li> Example of an encoded message (for illustration): A static request for chain 1 with two calls might look like:</p> Call 1: to = 0x111111...1111</code>, value = none (0), data = 0xabcdef</code></li> Call 2: to = 0x222222...2222</code>, value = 100 wei, data = (empty)</li> After encoding in protobuf and base64, the URI could be: ethereum:uwulink?request=EiABAggDEhARERERERERERERERERERERERERERIAGKDCr+8=</code> (this is a fake example string for concept; actual encoding would differ).</li> The wallet would decode that back to the structured fields.</li> </ul> </li> </ul> Wallet and dApp developers can import this .proto</code> to ensure they are constructing and parsing UWULink messages consistently.</p> Resolver Contract Interface (Programmable Mode)</h3> This standard introduces an interface that resolver contracts must implement so that wallets can query them for call batches. All resolver contracts MUST</strong> implement the following ABI (interface identifier UWUResolver</code>):</p> ///</span> @title</span> UWULink Resolver Interface</span></span> interface</span> UWUResolver</span> {</span></span> struct</span> Call</span> {</span></span> address</span> target</span>;</span></span> uint256</span> value</span>;</span></span> bytes</span> data</span>;</span></span> }</span></span> </span> //</span> Thrown when calls could not be generated, with an error code specific to this resolver.</span></span> error</span> CallGenerationFailure</span>(</span>uint256</span> errorCode</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> Compute a batch of calls for a given request.</span></span> * </span>@param</span> requester</span> The address of the wallet (EOA or contract) that is requesting the calls.</span></span> * </span>@param</span> data</span> Arbitrary request data (opaque to the wallet, provided by dApp via UWULink).</span></span> * </span>@return</span> calls</span> The list of calls that correspond to the requester and request</span></span> /</span></span> function</span> getCalls</span>(</span>address</span> requester</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> returns</span> (</span>Call</span>[</span>]</span> memory</span> calls</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> Returns the details for the given error code. Meant to be called by developers to better understand the error code for a resolver.</span></span> * Due to localization needs, it is expected that developers may call this function, but the wallet should not show this information to users.</span></span> /</span></span> function</span> getErrorCodeDetails</span>(</span>uint256</span> errorCode</span>)</span> external</span> returns</span> (</span>string</span> memory</span> information</span>)</span>;</span></span> }</span></span></code></pre> The function MAY</strong> modify state. Wallets SHOULD</strong> call it off-chain, and avoid combining the call with others e.g. via Multicall.</li> The requester</code> is included to allow the contract to tailor results to the specific user. For example, a resolver could check requester</code>’s token holdings or permissions and then return different call sets. The wallet should supply its own sending address as requester</code>. This means that the user’s address is revealed only to the RPC server</em> used by the wallet via this call, not to the dApp server or UI. In the future with the propagation of light clients, it's possible for the wallet to avoid revealing this information.</li> The data</code> parameter is the exact bytes provided in the UWULink request’s resolver_data</code>. Its contents and encoding are defined by the dApp’s usage and the contract’s logic. For instance, it might contain an enum indicating which action to perform, or some user-specific claim ID, etc.</li> The size of the returned arrays is not explicitly limited by this standard, but practical use should keep it reasonable (dozens rather than thousands of calls) both for blockchain computation reasons and for the user’s ability to comprehend the request.</li> </ul> Wallets should implement the following logic for programmable requests:</p> Perform an eth_call</code> to resolver_address</code> with to = resolver_address</code>, from = address(0)</code>, data = ABIEncodeWithSelector(UWUResolver.getCalls, userAddress, resolver_data)</code> against the latest block. The wallet MAY</strong> use the pending block, or otherwise include transactions in the state that are yet to be included in a confirmed block.</li> If the call returns successfully, decode the result. This becomes the batch of calls to execute. The wallet should then proceed exactly as if it were a static mode request containing those calls. It should display these calls to the user for confirmation (including target addresses, values, and perhaps decoded method signatures if it can).</li> If the call fails (reverts or is not implemented), the wallet MUST</strong> abort. It SHOULD surface an error to the user like "Transaction request generation failed: resolver contract call was unsuccessful." The user then knows the dApp’s request was bad or the contract might be wrong.</li> </ol> The dApp developer and resolver contract developer are responsible for ensuring that calling getCalls</code> is not too gas-intensive to execute (since wallets will execute it off-chain but it still must complete execution). Excessive computation could result in the node returning an error (out of gas exception in the eth_call context). Typically these functions will just gather data from known contracts or encode some predefined calls, which should not be prohibitively expensive.</p> Example Usage</h3> To illustrate how UWULink can be used in practice, consider the following scenarios:</p> 1. Static Mode – Token Approval and Swap (DeFi use-case):</strong></p> Alice wants to trade tokens on a decentralized exchange (DEX) using her mobile wallet, but she doesn't want to connect her wallet to the DEX website due to privacy concerns. The DEX dApp prepares a UWULink QR code for the trade. When Alice selects the tokens and amount on the website, the dApp formulates two contract calls: one to the ERC-20</a> token contract to approve()</code> the DEX's router contract, and one to the router contract to execute the swap ( swapExactTokensForTokens</code>, for example). Normally this would be two separate transactions with two confirmations. Instead, the dApp bundles them:</p> Call #1: to = TokenContract, data = approve(router, amount)</code></li> Call #2: to = RouterContract, data = swapExactTokensForTokens(params...)</code></li> </ul> Both calls have value = 0</code> (no ETH being sent directly). The dApp encodes these into a UWULinkRequest (static mode) for the current chain (e.g. Ethereum mainnet chain_id 1). The protobuf binary is base64 encoded and placed into a QR code with a URI like:</p> uwulink:CgEBEiAx... (truncated)</span></span></code></pre> Alice scans this QR with her wallet app. The wallet decodes the request: chain_id=1, two calls in batch. It recognizes it can execute an atomic batch (Alice’s wallet supports EIP-7702</a>). The wallet UI shows Alice a summary: "This dApp is requesting two actions: (1) Approve Token XYZ for spending, (2) Swap Token XYZ for Token ABC on DEX." Alice can inspect the contract addresses (perhaps the wallet resolves known token/contract names or shows the hex addresses) and the parameters. She sees that both will be submitted together in one transaction. The UI might look similar to a multi-call confirmation screen.</p> Alice accepts. Her wallet internally either crafts a 0x4 type transaction (since Alice is an EOA on Ethereum) embedding bytecode to do the two calls, or uses its smart wallet module. It then signs and broadcasts the transaction. On-chain, the two calls execute one after the other, and because of atomicity, if the swap were to fail, the approve would be reverted too (avoiding a scenario where she approved tokens without actually swapping).</p> The DEX backend or frontend can monitor the blockchain for the transaction receipt (it knows what actions it expected, or Alice can manually input the tx hash if needed). The important part is the DEX never learned Alice’s address beforehand; it only sees it when the transaction hits the blockchain, which is unavoidable for executing the trade but at that point privacy is preserved as well as any normal on-chain interaction (the dApp cannot link it to Alice’s web session unless Alice herself tells it out-of-band). This shows how UWULink achieves one-scan confirmation for what used to be multi-step, and keeps Alice’s identity private until the on-chain execution.</p> 2. Programmable Mode – Personalized Airdrop Claim:</strong></p> A project is running an airdrop where eligible users can claim several different token rewards based on on-chain activity. Bob visits the airdrop dApp page. The page could ask Bob to connect his wallet to figure out what he’s eligible for, but Bob is cautious. Instead, the dApp uses UWULink in programmable mode. It has a resolver contract deployed on-chain which, given a user address, can determine all the reward token contracts and amounts that the user is entitled to claim.</p> The dApp shows Bob a “Claim Rewards” button, which reveals a QR code. This QR encodes a UWULink request with:</p> chain_id = 5</code> (Goerli testnet, for example, where the airdrop is happening).</li> resolver_address = 0xDeeD…1234</code> (the address of the AirdropResolver contract).</li> resolver_data =</code> some bytes encoding maybe an airdrop campaign identifier or simply empty if one global campaign.</li> </ul> Bob scans this with his wallet. The wallet sees it's a resolver-type request. It calls getBatchCalls(BobAddress, resolver_data)</code> on 0xDeeD...1234</code> (as a view call). The AirdropResolver contract looks up internally that BobAddress is eligible for 3 tokens: TokenA, TokenB, and TokenC with certain amounts, and the claim function for each is claim(address claimant, uint256 amount)</code> on each token’s distributor contract. It returns three arrays: targets = [AddrA, AddrB, AddrC]</code>, values = [0,0,0]</code> (no ETH needed), callData = [ abi.encodeWithSelector(Distributor.claim, Bob, amtA), ... ]</code> for each token.</p> The wallet receives these arrays. It now has three calls to execute. It shows Bob: "Claim TokenA: amount X, Claim TokenB: amount Y, Claim TokenC: amount Z" (assuming the wallet can decode the function signatures or at least show contract addresses and method names if it has ABIs). Bob approves the batch. The wallet then either directly calls each distributor’s claim</code> in one aggregated transaction. Because Bob’s address was provided to the resolver, each claim call will credit tokens to Bob (likely the contract uses the provided address or msg.sender</code> – here it was likely coded to use the address parameter, since the actual transaction sender will be Bob’s own address in the batch execution context). The important part is Bob did not have to connect his wallet to the dApp; the eligibility and calls were determined by the on-chain contract. The dApp never saw Bob’s address, yet Bob gets his tokens in one go.</p> After execution, Bob’s wallet shows the transaction success. The dApp might simply tell him to check his balances (or it could have a public page showing which addresses claimed, etc., but it did not get a direct notification — it relies on Bob or the blockchain to know the claim happened).</p> 3. Cross-Device Payment via NFC (Point of Sale):</strong></p> Carol is at a merchant's point-of-sale device that accepts cryptocurrency payments via Ethereum. The merchant’s device can display a QR or emit an NFC message with a payment request. Instead of using a simple one-address payment URI (as in EIP-681</a>), the merchant uses UWULink to request a more sophisticated transaction: perhaps Carol will pay through a specific escrow contract or with a certain token if she has a discount coupon.</p> The device sends an NFC payload</strong> which Carol’s phone picks up (many wallet apps can register as handlers for certain NDEF messages or custom URI schemes). The payload contains a UWULinkRequest in static mode:</p> chain_id = 137 (Polygon, where the merchant operates).</li> Two calls: first call to a stablecoin contract’s transfer(merchantAddress, amount)</code> (to pay the merchant), second call to a logging contract registerPurchase(merchantId, CarolAddress, amount)</code> (to log the sale in an on-chain registry). Both calls are value 0 since a token transfer, not ETH, is used.</li> </ul> Carol’s wallet opens with the decoded request: It shows "Pay 50 USDC to Merchant XYZ and register purchase." Carol sees the merchant name resolved from the merchant’s address (if her wallet has ENS or a local registry of known merchants). She approves. The wallet then executes an atomic transaction on Polygon that calls the USDC token contract and the registry contract. The merchant’s PoS waits for confirmation on-chain (or simply trust the signed transaction once broadcast, depending on their risk tolerance). Carol’s identity remained pseudonymous; the merchant’s device did not directly get her wallet info, it only received the on-chain payment. And Carol only had to tap once to approve both token transfer and logging, rather than scan one QR to pay then perhaps another to log, etc.</p> These examples demonstrate the flexibility of UWULink:</p> In all cases, the user did not pre-connect their wallet to the application.</li> The requests can be transferred via out-of-band channels (QR/NFC/URL).</li> Multi-step operations become “one-click” (or one-scan) operations for the user.</li> The on-chain outcome is the same as if the user had manually sent those transactions, but with improved UX and privacy.</li> </ul> Rationale</h2> TBD </p> Backwards Compatibility</h2> UWULink is an additive protocol and does not break any existing standards. It is designed to coexist with current methods:</p> Existing Wallet URIs (EIP-681</a>, EIP-831</a>):</strong> UWULink can be seen as an evolution of the idea behind EIP-681 ( transaction request URIs). EIP-681 defines URIs for a single transaction (or payment) and is already supported in a limited number of wallets for QR code scanning. UWULink extends the concept to multiple calls and binary encoding. A wallet that does not recognize the uwulink:</code> scheme should simply not act on it. Typically, such a wallet would either show an error or ignore a scanned QR it cannot parse. This is a graceful failure from the user's perspective (they'll know the wallet doesn't support that request). There is no risk of confusing an UWULink QR with an EIP-681 QR, since the scheme and content format differ. Therefore, wallets that only implement support for EIP-681 will not mistakenly handle a UWULink payload as a valid request.</p> </li> Ensuring Backwards Compatibility in Data Format:</strong> The protobuf schema is designed such that new fields could be added in the future in a non-breaking way (per Proto3 rules, unknown fields are ignored by receivers). For example, a future version might add an optional uint64 expiration_timestamp</code> or string origin</code> field to carry a domain name for UI display. An older wallet would ignore these and still execute the core request. This forward-compatibility means UWULink can evolve without breaking older implementations, as long as additions are carefully made optional.</p> </li> Fall-back to Standard Flows:</strong> From a dApp perspective, implementing UWULink does not preclude supporting traditional wallet connections. A dApp can offer UWULink QR codes for users who prefer privacy or are on devices (like a separate mobile) without browser extensions. At the same time, it can have the usual “Connect Wallet” button for users who are okay with that. This multi-modal approach ensures no user is left out. Over time, if UWULink (or similar one-way flows) prove safer and more popular, they might become the default, allowing users to interact with dApps without connecting a wallet.</p> </li> Network Compatibility:</strong> We limit scope to EVM-compatible chains. That means chains that use EIP-155</a> transaction scheme and Ethereum-like addresses. On non-EVM chains, this standard doesn’t apply (though analogous concepts could). Within EVM chains, a nuance: if a chain has a different maximum gas limit or transaction format peculiarity, the wallet internally deals with that. UWULink just says "execute these calls." As long as the wallet can create a transaction that does so, it’s fine. If an EVM chain does not support atomic multi-call (some L2s or sidechains might not immediately support EIP-7702), the wallet has to handle it at the account abstraction layer if possible, or otherwise MUST</strong> reject the request. This again falls to the wallet to know its capabilities (e.g. per EIP-5792</a>’s capabilities query).</p> </li> </ul> In conclusion, UWULink aims to introduce new functionality without disrupting existing user journeys. It is opt-in for all parties. Early adopters (both dApps and wallets) can experiment with it while others continue as usual. As support grows, it could become a widely recognized standard for secure one-way wallet interactions. The design takes into account lessons from previous proposals (EIP-681</a> URIs, WalletConnect, EIP-5792</a>, etc.) and ensures that adopting UWULink is a low-risk enhancement rather than a breaking change to Ethereum’s ecosystem.</p> Security Considerations</h2> Privacy</h3> UWULink is designed with privacy in mind, but it introduces some new security aspects that implementers and users should consider:</p> No Wallet Identification:</em> The wallet does not disclose the user’s address or any wallet details to the dApp when using UWULink. This significantly improves privacy compared to typical wallet connect flows. The dApp only learns of the user's address if and when the transaction is broadcast on-chain. Even then, the dApp cannot easily correlate that address with a specific user session (the user could be anonymous on the website until that point).</li> On-Chain Resolver Calls:</em> In programmable mode, the user's address is supplied to the resolver contract as a parameter. This happens off-chain via eth_call</code>, so it does not create a public transaction. However, the node or RPC provider that the wallet uses will see that call (just like any read call). If the RPC provider is untrusted, this could leak some information (e.g., that this address is interested in this resolver's data). In most cases this is a minor concern (no more revealing than using the dApp itself while connected to an RPC), but users who are extremely privacy-conscious might prefer static mode or ensure they use a privacy-respecting RPC. Importantly, the dApp backend or frontend does not see this – only the blockchain infrastructure does.</li> No Third-Party Tracking:</em> Because UWULink can be used via local channels (QR/NFC), it avoids relying on any centralized relay. WalletConnect v1, for instance, used relay servers and handshake topics which, in theory, could be tracked or snooped (even though payloads were encrypted, the metadata might leak usage patterns). UWULink in contrast can be a completely peer-to-peer (user and dApp) interaction with minimal digital footprint aside from the eventual blockchain transaction.</li> User Consent:</em> As with any transaction, the user explicitly consents by scanning and approving the request. The user relies on the wallet's simulation and multi-factor authorization capabilities to prevent sending of malicious transactions.</li> </ul> Security of Transaction Requests</h3> Phishing and Malicious QR Codes:</em> A malicious actor could present a user with a UWULink QR code that, if scanned and approved blindly, could cause the user to transfer funds or approve tokens to the attacker. This risk is analogous to phishing links or malicious dApp websites in today's context. Users should be educated to only approve UWULink requests from sources they trust or understand. Wallets should help by displaying clear human-readable information</strong> about what the request will do:</p> Show the names or ENS of known contract addresses involved (or at least highlight unknown addresses).</li> Decode function selectors to known function names if possible (e.g., show "approve(address _spender, uint256 _value)" instead of raw hex).</li> For value transfers, show the ETH or token amount in a friendly format.</li> Possibly warn if the request involves calling an unrecognized contract with large value transfers or if it sets a high token allowance, etc.</li> </ul> </li> Atomic Execution and Reverts:</em> By enforcing atomic execution, UWULink ensures that partial completion won't lead to stuck funds or unintended states. However, this also means a malicious or buggy request could be crafted to always revert (for example, by including an incompatible call), which could waste user gas fees if not caught. Wallets should simulate the batch when possible. If the wallet can do a dry-run (for instance using eth_call</code> on a Bundler or internal simulation) it might detect a guaranteed revert and inform the user that the call set is invalid (though this might be complex to do reliably for all calls).</p> </li> Resolver Contract Trust:</em> The programmable mode introduces a potential trust issue: the user is effectively trusting the resolver contract’s code to generate the calls honestly. If the resolver contract is malicious, it could return call data that benefits an attacker. For example, a malicious resolver could ignore the input data and always return a call transferring all of the user's ETH to the attacker’s address. Mitigations:</strong></p> Ideally, resolver contracts should be open source and verified, and the dApp using them should be reputable. The wallet can’t fully know if the resolver’s output is malicious until it sees it, but the user will have a chance to review the resulting calls anyway. This is crucial: the wallet must display the resulting calls</em> from the resolver to the user, just as it would in static mode. The user should then notice if something is off (e.g., a transfer of all their ETH is about to happen).</li> Wallet developers might consider adding special handling or warnings if a resolver returns calls that do not seem correlated with the input. However, this is hard to generalize. At minimum, treat the resolver output with the same suspicion as a static request. There’s no inherent additional risk beyond what static mode has, because the user still confirms the final calls. The difference is just where the call data came from.</li> We assume resolver contracts will often be provided by the same party as the dApp and thus come with an implied level of trust (or at least, they can be audited by the community if the UWULink scheme becomes popular).</li> </ul> </li> No Automatic Spending:</em> UWULink does not introduce new signing or authorization paradigms – it uses actual transactions that the user signs on the spot. Thus, it’s less prone to the kind of issues where a signature can be later reused (like the risks with off-chain signatures). Each UWULink request is one transaction (with possibly multiple subcalls). After it's executed, the link cannot be reused to automatically trigger more actions (unless the user scans it again). This is good from a security standpoint since it doesn't create long-lived permissions. One exception: if a call within the batch is an approval or something, that is an on-chain permission that persists as usual (the user should be made aware as normal).</p> </li> Denial of Service (DOS):</em> A malicious dApp could craft an extremely large UWULink payload (especially in static mode) that could crash or slow a wallet app upon scanning (due to memory or decoding issues). Wallets should implement size limits and perhaps streaming parsing for the protobuf to avoid crashes. If a payload exceeds a reasonable size (e.g., several kilobytes), the wallet can reject it for safety. Similarly, a resolver contract could try to return extremely large results – wallets should guard against that by limiting the amount of gas provided to the resolver via eth_call.</p> </li> Capabilities and Future Extensions:</em> UWULink intentionally does not carry any additional flags like gas limits or paymaster info (unlike EIP-5792 which has a capabilities system). This is to keep the format simple. However, this means the wallet will apply its own heuristics for gas, and by default the user pays fees. If a future extension wanted to allow gas sponsorship or other features, that could be added either by extending the protobuf (e.g., adding an optional paymaster field) or by having the resolver contract itself handle that (e.g., a resolver could incorporate a paymaster logic by returning a call to a paymaster contract as part of the batch). In any case, security considerations around gas (like a malicious paymaster causing some weird behavior) would need to be analyzed. For now, UWULink operates within the normal transaction model, so the main security focus is on the correctness of calls.</p> </li> </ul> Comparison to Traditional Flows:</strong> One might ask, does eliminating the wallet <-> dApp handshake create any new risks? In traditional connected dApp sessions, the wallet at least knows the origin of requests (e.g., which website is calling eth_sendTransaction</code> or wallet_sendCalls</code>). In UWULink, the origin is essentially "the QR code the user scanned" – the wallet might know the payload came via a QR/NFC but not which app or site. In security terms, this means the wallet cannot apply domain-based whitelists or blocklists (since there's no domain, unless the URI contains one in the payload which it typically wouldn't). Therefore, the user must manually trust and verify each request.</strong> This is akin to using a hardware wallet: every transaction is shown on a screen and the user approves it, with no assumptions about where it came from. This places responsibility on the user and makes the wallet’s job of displaying info accurately even more important.</p> Privacy vs. Usability Trade-off:</strong> Because UWULink doesn’t let the dApp query the wallet off-chain, some conveniences are lost – e.g., the dApp cannot automatically fetch the user's address to display their balance or NFTs in the UI prior to a transaction. This is a conscious privacy trade-off. Some advanced dApps might find workarounds (like asking the user to input their address manually if they want to see personalized info, or shifting more logic on-chain as in programmable mode). Users and dApp developers must understand this trade-off. In contexts where user personalization without login is needed, UWULink might require a bit more creativity, but it ensures that if the user chooses not to share anything, they truly don't until a transaction is made.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Confidential Transactions Supported Token 2025-05-09T00:00:00+00:00 Abstract</h2> Classic token contracts like ERC-20</a> enable their token holders to make transfers and/or approve others to make transfers on their behalves. The generality of token standard ERC-20</a> catalyzed decentralizing finance and many other blockchain applications. However, when it comes to privacy, although some technical schemes have been proposed, few standards have been established, which limits the evolution of privacy-preserving blockchain applications.</p> This proposal draws up a standard interface for fungible token contracts supporting confidential transactions. It provides basic transfer functionality without loss of generality, and allowance and approve functionalities. Contracts following the standard can provide confidentiality for users’ balances and token transfer value, and can enable other blockchain applications to make transfers on behalf of owners, which empowers more privacy-preserving capabilities to blockchain applications.</p> Motivation</h2> Confidential transactions have been implemented in many blockchains, either natively through blockchain protocols like Monero and Zcash, or through smart contracts like Zether1</a></sup> without modifying blockchain protocol.</p> However, when it comes to the latter way, actually few standards are proposed yet on Ethereum (and/or other EVM-compatible blockchains) to illustrate such contracts. Users and applications cannot easily detect whether a token contract supports confidential transactions or not, and so hardly can they make transfers without revealing the actual amount.</p> Consequently, this proposal is to standardize the confidential transaction supported token contracts, meanwhile without loss of generality, by only specifying core methods and events.</p> Such standard interface allows confidential transactions of tokens to be applied by certain parties which are sensitive to transfer amount, or by privacy-preserving applications.</p> Specification</h2> 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.</p> Contract Interface</h3> The proposed contract implements the following 2 interfaces: ITokenMetadata</code> and IConfidentialToken</code> .</p> ITokenMetadata</code></h4> Methods</h5> name</code></h6> function</span> name</span>(</span>)</span> public</span> view</span> returns</span> (</span>string</span>)</span></span></code></pre> Returns the name of the token - e.g. "MyConfidentialToken"</code> .</p> OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</p> symbol</code></h6> function</span> symbol</span>(</span>)</span> public</span> view</span> returns</span> (</span>string</span>)</span></span></code></pre> Returns the symbol of the token. e.g. "cHIX"</code> .</p> OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</p> decimals</code></h6> function</span> decimals</span>(</span>)</span> public</span> view</span> returns</span> (</span>uint8</span>)</span></span></code></pre> Returns the number of decimals the token uses - e.g. 8</code> , means to divide the token amount by 100000000</code> to get its user representation.</p> OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</p> IConfidentialToken</code></h4> Methods</h5> confidentialBalanceOf</code></h6> function</span> confidentialBalanceOf</span>(</span>address</span> owner</span>)</span> </span></span> public</span> view</span> returns</span> (</span>bytes</span> memory</span> confidentialBalance</span>)</span></span></code></pre> Returns the confidential balance of the account with address owner</code> .</p> confidentialTransfer</code></h6> function</span> confidentialTransfer</span>(</span></span> address</span> _to</span>,</span></span> bytes</span> memory</span> _confidentialTransferValue</span>,</span> </span></span> bytes</span> memory</span> _proof</span></span> )</span> public</span> returns</span> (</span>bool</span> success</span>)</span></span></code></pre> Transfers value</code> amount of tokens (behind _confidentialTransferValue</code> ) to address _to</code> , and MUST fire the ConfidentialTransfer</code> event. The function SHOULD throw</code> if the message caller’s _proof</code> of this transfer fails to be verified.</p> Note:</p> Callers MUST handle false</code> from returns (bool success). Callers MUST NOT assume that false</code> is never returned!</p> </li> Implementations can fully customize the proof system, (de)serialization strategies of bytes</code> and/or the business workflow. For example, when implementing "Zether"^{1</a></sup> confidential token contracts, the _confidentialTransferValue</code> and accounts' confidential balances will be encrypted homomorphically under ElGamal public keys, and _proof</code> will consist 3 parts to check:</p>} _confidentialTransferValue</code> is well encrypted under both caller's public key and _to</code> 's;</li> The plaintext value</code> behind _confidentialTransferValue</code> is non-negative;</li> The caller's confidential balance is actually enough to pay the plaintext value</code> behind _confidentialTransferValue</code> .</li> </ul> </li> </ul> confidentialTransferFrom</code></h6> function</span> confidentialTransferFrom</span>(</span></span> address</span> _from</span>,</span></span> address</span> _to</span>,</span></span> bytes</span> memory</span> _confidentialTransferValue</span>,</span> </span></span> bytes</span> memory</span> _proof</span></span> )</span> public</span> returns</span> (</span>bool</span> success</span>)</span></span> </span></span></code></pre> Transfers value</code> amount of tokens (behind _confidentialTransferValue</code> ) from address _from</code> to address _to</code> , and MUST fire the ConfidentialTransfer</code> event.</p> The confidentialTransferFrom</code> method is used for a withdraw workflow, allowing contracts to transfer tokens on your behalf. This can be used for example to allow a contract to transfer tokens on your behalf and/or to charge fees in sub-currencies. The function SHOULD throw</code> unless the _from</code> account has deliberately authorized the sender of the message via some mechanism, and SHOULD throw</code> if the message caller’s _proof</code> of this transfer fails to be verified.</p> Note:</p> Callers MUST handle false</code> from returns (bool success). Callers MUST NOT assume that false</code> is never returned!</p> </li> Implementations can fully customize the proof system, (de)serialization strategies of bytes</code> and/or the business workflow. For example, when implementing "Zether" confidential token contracts, the _confidentialTransferValue</code> and accounts' confidential balances will be encrypted homomorphically under ElGamal public keys, and _proof</code> will consist 3 parts to check:</p> _confidentialTransferValue</code> is well encrypted under public keys of _from</code> 's, _to</code> 's and caller's;</li> The plaintext value</code> behind _confidentialTransferValue</code> is non-negative;</li> The caller's confidential allowance is actually enough to pay the plaintext value</code> behind _confidentialTransferValue</code> .</li> </ul> </li> </ul> confidentialApprove</code></h6> function</span> confidentialApprove</span>(</span></span> address</span> _spender</span>,</span></span> bytes</span> memory</span> _confidentialValue</span>,</span> </span></span> bytes</span> memory</span> _proof</span></span> )</span> public</span> returns</span> (</span>bool</span> success</span>)</span></span></code></pre> Allows _spender</code> to withdraw from caller's split part of balances multiple times, up to the amount (allowance value) behind _confidentialValue</code> to 0. This function SHOULD throw</code> if the message caller’s _proof</code> of this transfer fails to be verified.</p> Caution:</p> This function behaves much differently from</strong> approve(address,uint256)</code> in ERC-20</a>.</p> Calling confidentialApprove</code> splits the confidential balance of caller's account into allowance part</em> and the left part</em>.</p> The values behind two parts above after calling confidentialApprove</code> , and the value behind the original confidential balance of caller's account before calling confidentialApprove</code> satisfy the equation:</p> $$ value_{Behind\ Allowance\ Part} + value_{Behind\ Left\ Part} = value_{Behind\ Original\ Confidential\ Balance} $$</p> The allowance part of confidential balance allows _spender</code> to withdraw multiple times through calling confidentialTransferFrom</code> until _spender</code> does not call it any more or the value behind this part is 0.</p> Every time the _spender</code> calls confidentialTransferFrom</code> , the value behind this part will be decreased by the value behind _confidentialTransferValue</code> .</li> </ul> </li> The left part remains as the new confidential balance of caller's account.</p> </li> </ul> If this function is called again it,</p> merges existing allowance part into the confidential balance of caller's account; and then</li> overwrites the current allowance part with _confidentialValue</code> .</li> </ul> Note:</p> Callers MUST handle false</code> from returns (bool success). Callers MUST NOT assume that false</code> is never returned!</p> </li> Implementations can fully customize the proof system, (de)serialization strategies of bytes</code> and/or the business workflow. For example, when implementing "Zether" confidential token contracts, the _confidentialValue</code> and accounts' confidential balances will be encrypted homomorphically under ElGamal public keys, and _proof</code> will consist 3 parts to check:</p> _confidentialValue</code> is well encrypted under public keys of caller's and _spender</code>'s;</li> The plaintext value</code> behind _confidentialValue</code> is non-negative;</li> The caller's confidential balance is actually enough to pay the plaintext value</code> behind _confidentialValue</code> .</li> </ul> </li> </ul> confidentialAllowance</code></h6> functinon </span>confidentialAllowance</span>(</span>address</span> _owner</span>,</span> address</span> _spender</span>)</span></span> public</span> view</span> returns</span> (</span>bytes</span> memory</span> _confidentialValue</span>)</span></span></code></pre> Returns the allowance part which _spender</code> is still allowed to withdraw from _owner</code>.</p> Events</h5> ConfidentialTransfer</code></h6> event</span> ConfidentialTransfer</span>(</span></span> address</span> indexed</span> _spender</span>,</span></span> address</span> indexed</span> _from</span>, </span></span> address</span> indexed</span> _to</span>, </span></span> bytes</span> _confidentialTransferValue</span></span> )</span></span></code></pre> MUST trigger when tokens are transferred.</p> Specifically, if tokens are transferred through function confidentialTransferFrom</code>, _spender</code> address MUST be set to caller's; otherwise, it SHOULD be set to 0x0</code>.</p> A confidential token contract,</p> which creates new tokens SHOULD trigger a ConfidentialTransfer</code> with the _from</code> address set to 0x0</code> when tokens are minted;</li> which destroys existent tokens SHOULD trigger a ConfidentialTransfer</code> with the _to</code> address set to 0x0</code> when tokens are burnt.</li> </ul> ConfidentialApproval</code></h6> event</span> ConfidentialApproval</span>(</span></span> address</span> indexed</span> _owner</span>,</span></span> address</span> indexed</span> _spender</span>,</span></span> bytes</span> _currentAllowancePart</span>,</span></span> bytes</span> _allowancePart</span></span> )</span></span></code></pre> MUST trigger on any successful call to confidentialApprove(address,bytes,bytes)</code>.</p> Rationale</h2> Optional Accessor of "Confidential Total Supply"</h3> function</span> confidentialTotalSupply</span>(</span>)</span> public</span> view</span> returns</span> (</span>bytes</span> memory</span>)</span></span></code></pre> Confidentiality of transfer amount makes it hard to support such field like totalSupply()</code> in ERC-20</a>. Because when it comes to the token "mint" or "burn", if every user in this contract can access totalSupply()</code> as well as decrypt it, these users will know the actual token value to be minted or burnt by comparing the totalSupply()</code> before and after such operations, which means that confidentiality no longer exists.</p> Contract implementation can optionally support confidentialTotalSupply()</code> by evaluating if anti-money laundry (see next part) and audit are required. That would be much more plausible by making a small group of parties can know the plaintext total supply behind confidentialTotalSupply()</code>.</p> Anti-money Laundry and Audit</h3> To support audit of confidential transactions and total supply, especially such token issuers are banks or other financial institutes supervised by governments or monetary authorities, confidential transactions can be implemented without changing confidentialTransfer</code> method signature, by encoding more info into parameters.</p> For example in Zether-like implementation[^2], if token transfers are required to be audited, confidentialTransfer</code> caller encrypts transfer value</code> redundantly under public keys of caller's, to</code>'s, a group of auditors', which makes it possible that related parties can exactly know the real value</code> behind. So does confidentialTotalSupply()</code>.</p> Fat Token</h3> Confidential transactions supported token can also implement ERC-20</a> at the same time.</p> Token accounts in such tokens can hold 2 kinds of balances. Such token contracts can optionally provide methods to hide ERC-20</a> plaintext balances into confidential balances, and vice versa, to reveal confidential balances back to ERC-20</a> plaintext balances.</p> ERC-20</a> interfaces will bring much more usability and utilities to confidential transaction supported tokens, realizing general confidentiality meantime.</p> Backwards Compatibility</h2> No backward compatibility issues found.</p> Security Considerations</h2> To realize full confidentiality, contracts implementing this presented interface SHOULD NOT create (mints) or destroy (burns) tokens with plaintext value parameters. For implementation, following the same encryption strategies in confidentialTransfer(address,bytes,bytes)</code> is RECOMMENDED.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Bünz, B., Agrawal, S., Zamani, M., & Boneh, D. (n.d.). Zether: Towards Privacy in a Smart Contract World</span>. https://doi.org/10.1007/978-3-030-51280-4_23</a> (Original work published 2020)[^2]: Chen, Y., Ma, X., Tang, C., & Au, M. H. (n.d.). PGC: Decentralized Confidential Payment System with Auditability</span>. https://doi.org/10.1007/978-3-030-58951-6_29</a> (Original work published 2020) ↩</a> ↩2</a></p> </li> </ol> </section> Account Abstraction Recovery Interface 2025-05-07T00:00:00+00:00 Abstract</h2> Introduce a universal account abstraction recovery mechanism recoverAccess(subject, provider, proof)</code> along with recovery provider management functions for smart accounts to securely update their access subject.</p> Motivation</h2> Account abstraction and the "contractization" of EOAs are important Ethereum milestones for improving on-chain UX and off-chain security. A wide range of smart accounts emerge daily, aiming to simplify the steep onboarding curve for new users. The ultimate smart account experience is to never ask them to deal with private keys, yet still allow for full account control and access recovery. With the developments in the Zero-Knowledge Artificial Intelligence (ZKAI) and Zero-Knowledge Two Factor Authentication (ZK2FA) fields, settling on a common mechanism may even open the doors for "account recovery provider marketplaces" to emerge.</p> The account recovery approach described in this proposal allows for multiple recovery providers to coexist and provide a wide variety of unique recovery services. In simple terms, smart accounts become "recovery provider aggregators", making it possible for the users to never rely on centralized services or projects.</p> The Account Abstraction Recovery Interface (AARI) aims to define a flexible interface for any</em> smart account to implement, allowing users to actively manage their account recovery providers and restore the access of an account in case of a private key loss.</p> Specification</h2> 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.</p> A smart account willing to support AARI MUST implement the following interface:</p> pragma</span> solidity</span> ^0.8.20</span>;</span></span> </span> /</span></span> </span>@notice</span> Defines a common account recovery interface for smart accounts to implement.</span></span> /</span></span> interface</span> IAccountRecovery</span> {</span></span> /</span></span> MUST be emitted whenever the access of the account changes as a result </span></span> * of the account recovery (e.g. in the `recoverAccess` function).</span></span> /</span></span> event</span> AccessRecovered</span>(</span>bytes</span> subject</span>)</span>;</span></span> </span></span> /</span></span> MUST be emitted whenever a new recovery provider is added to</span></span> * the account (e.g. in the `addRecoveryProvider` function).</span></span> /</span></span> event</span> RecoveryProviderAdded</span>(</span>address</span> indexed</span> provider</span>)</span>;</span></span> </span> /</span></span> MUST be emitted whenever a recovery provider is removed from</span></span> * the account (e.g. in the `removeRecoveryProvider` function).</span></span> /</span></span> event</span> RecoveryProviderRemoved</span>(</span>address</span> indexed</span> provider</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> A function to add a new recovery provider.</span></span> * SHOULD be access controlled.</span></span> * MUST check that `provider` is not `address(0)`.</span></span> * MUST call `subscribe` on the `provider`.</span></span> * MUST pass `recoveryData` to the `subscribe` function.</span></span> * </span></span> * </span>@param</span> provider</span> the address of a recovery provider (ZKP verifier) to add.</span></span> * </span>@param</span> recoveryData</span> custom data (commitment) for the recovery provider.</span></span> /</span></span> function</span> addRecoveryProvider</span>(</span>address</span> provider</span>,</span> bytes</span> memory</span> recoveryData</span>)</span> external</span> payable</span>;</span></span> </span> /</span></span> </span>@notice</span> A function to remove an existing recovery provider.</span></span> * SHOULD be access controlled.</span></span> * MUST call `unsubscribe` on the `provider`.</span></span> * </span></span> * </span>@param</span> provider</span> the address of a previously added recovery provider to remove.</span></span> /</span></span> function</span> removeRecoveryProvider</span>(</span>address</span> provider</span>)</span> external</span> payable</span>;</span></span> </span> /</span></span> </span>@notice</span> A view function to check if a provider has been previously added.</span></span> * </span></span> * </span>@param</span> provider</span> the provider to check.</span></span> * </span>@return</span> true</span> if the provider exists in the account, false otherwise.</span></span> /</span></span> function</span> recoveryProviderAdded</span>(</span>address</span> provider</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> A non-view function to recover access of a smart account.</span></span> * MUST check that `provider` exists in the account.</span></span> * MUST call `recover` on the `provider`.</span></span> * MUST update the account access according to `subject` if `proof` verification succeeds.</span></span> * MUST return `true` if the access recovery is successful.</span></span> * </span></span> * </span>@param</span> subject</span> the recovery subject (encoded owner address, access control role, etc).</span></span> * </span>@param</span> provider</span> the address of a recovery provider.</span></span> * </span>@param</span> proof</span> an encoded proof of recovery (ZKP/ZKAI, signature, etc).</span></span> * </span>@return</span> `true` if recovery is successful, `false` (or revert) otherwise.</span></span> /</span></span> function</span> recoverAccess</span>(</span></span> bytes</span> memory</span> subject</span>,</span></span> address</span> provider</span>,</span></span> bytes</span> memory</span> proof</span></span> )</span> external</span> returns</span> (</span>bool</span>)</span>;</span></span> }</span></span></code></pre> A recovery provider MUST implement the following interface:</p> /</span></span> </span>@notice</span> Defines a common recovery provider interface.</span></span> /</span></span> interface</span> IRecoveryProvider</span> {</span></span> /</span></span> MUST be emitted whenever a new account subscribes to</span></span> * the recovery provider (e.g. in the `subscribe` function).</span></span> /</span></span> event</span> AccountSubscribed</span>(</span>address</span> indexed</span> account</span>)</span>;</span></span> </span> /</span></span> MUST be emitted whenever an account unsubscribes from</span></span> * the recovery provider (e.g. in the `unsubscribe` function).</span></span> /</span></span> event</span> AccountUnsubscribed</span>(</span>address</span> indexed</span> account</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> A function that "subscribes" a smart account (msg.sender) to a recovery provider.</span></span> * SHOULD process and assign the `recoveryData` to the `msg.sender`.</span></span> * </span></span> * </span>@param</span> recoveryData</span> a recovery commitment (hash/ZKP public output) to be used </span></span> * in the `recover` function to check a recovery proof validity.</span></span> /</span></span> function</span> subscribe</span>(</span>bytes</span> memory</span> recoveryData</span>)</span> external</span> payable</span>;</span></span> </span> /</span></span> </span>@notice</span> A function that revokes a smart account subscription.</span></span> * MUST delete all the recovery data associated with the `msg.sender`.</span></span> /</span></span> function</span> unsubscribe</span>(</span>)</span> external</span> payable</span>;</span></span> </span> /</span></span> </span>@notice</span> A function to get a recovery data (commitment) of an account.</span></span> * </span></span> * </span>@param</span> account</span> the account to get the recovery data of.</span></span> * </span>@return</span> the</span> associated recovery data.</span></span> /</span></span> function</span> getRecoveryData</span>(</span>address</span> account</span>)</span> external</span> view</span> returns</span> (</span>bytes</span> memory</span>)</span>;</span></span> </span> /</span></span> </span>@notice</span> A function that checks if a recovery of a smart account (msg.sender)</span></span> * to the new subject is possible.</span></span> * SHOULD use `msg.sender`'s `recoveryData` to check the `proof` validity.</span></span> * MUST ensure that the `proof` can't be reused, e.g. update nonce.</span></span> * </span></span> * </span>@param</span> object</span> the new object (may be different to subject) to recover the `msg.sender` access to.</span></span> * </span>@param</span> proof</span> the recovery proof.</span></span> /</span></span> function</span> recover</span>(</span>bytes</span> memory</span> object</span>,</span> bytes</span> memory</span> proof</span>)</span> external</span>;</span></span> }</span></span></code></pre>Rationale</h2> The AARI is expected to work with any</em> account abstraction standard to allow for maximum account recovery flexibility. Whether it is EIP-4337</a> or EIP-7702</a>, a particular smart account provider may support account recovery by simply implementing a common interface.</p> Since the whole account recovery process is nothing but proving the knowledge of some alternative secret to a private key, it is essential for accounts to be able to "commit" to this secret. The subscribe</code> function in the recovery provider interface allows precisely for that. Moreover, if at some point in time a user wanted to "recommit" to a new secret (due to security reasons), they could multicall unsubscribe</code> + subscribe</code> functions to achieve the desired result.</p> The recovery functions accept arbitrary bytes as subject</code> and object</code> parameters to allow for a variety of access control rules to be recovered, since many smart accounts are ownerless and have no "owner" address to be directly substituted.</p> Backwards Compatibility</h2> This EIP is fully backwards compatible.</p> Security Considerations</h2> There are several security concerns to point out:</p> It is up to a smart account developer to properly access control addRecoveryProvider</code> and removeRecoveryProvider</code> functions.</li> A smart account user may be "phished" to add a malicious recovery provider to their account. In that case, a recovery provider may gain full control over the account by accepting fake recovery proofs.</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Versioned Proxy Contract Interface 2025-04-17T00:00:00+00:00 Abstract</h2> This EIP standardizes an interface for proxy contracts that allows callers to explicitly select which version of an implementation contract they want to interact with. Unlike traditional proxy patterns that only expose the latest implementation, this standard enables backward compatibility by maintaining access to previous implementations while supporting upgrades. The versioned proxy maintains a registry of implementation addresses mapped to version identifiers, allowing callers to specify their desired version at call time.</p> Motivation</h2> Smart contract upgrades are essential for fixing bugs and adding features. Current proxy patterns typically force all callers to use the latest implementation, which can break existing integrations when interfaces change.</p> Furthermore, traditional proxy patterns expose all users to risk if an upgrade is malicious, as they have no choice but to use the latest implementation. This standard allows users to remain on verified versions they trust, mitigating the risk of a compromised admin key or governance process deploying harmful code.</p> This EIP addresses several key problems:</p> Breaking Changes</strong>: Interface changes in new implementations can break existing integrations.</li> Gradual Adoption</strong>: There is no standard way to allow gradual adoption of new contract versions.</li> Malicious Upgrades</strong>: Users today must trust proxy admins indefinitely, as they can't opt out of potentially harmful upgrades without ceasing use of the contract entirely.</li> Trust Assumptions</strong>: Contract users must maintain perpetual trust in governance or admin keys, with no ability to selectively trust specific, audited implementations.</li> </ol> Specification</h2> 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.</p> Interface</h3> interface</span> IVersionedProxy</span> {</span></span> ///</span> @notice</span> Emitted when a new implementation version is registered</span></span> ///</span> @param</span> version</span> The version identifier</span></span> ///</span> @param</span> implementation</span> The address of the implementation contract</span></span> event</span> VersionRegistered</span>(</span>bytes32</span> version</span>, </span>address</span> implementation</span>)</span>;</span></span> </span></span> ///</span> @notice</span> Emitted when the default version is </span>changed</span></span> ///</span> @param</span> oldVersion</span> The previous default version</span></span> ///</span> @param</span> newVersion</span> The new default version</span></span> event</span> DefaultVersionChanged</span>(</span>bytes32</span> oldVersion</span>, </span>bytes32</span> newVersion</span>)</span>;</span></span> </span></span> ///</span> @notice</span> Registers a new implementation version</span></span> ///</span> @param</span> version</span> The version identifier (e.g., "1.0.0")</span></span> ///</span> @param</span> implementation</span> The address of the implementation contract</span></span> function</span> registerVersion</span>(</span>bytes32</span> version</span>,</span> address</span> implementation</span>)</span> external</span>;</span></span> </span></span> ///</span> @notice</span> Removes a version from the registry</span></span> ///</span> @param</span> version</span> The version identifier to remove</span></span> function</span> removeVersion</span>(</span>bytes32</span> version</span>)</span> external</span>;</span></span> </span></span> ///</span> @notice</span> Sets the default version to use when no version is specified</span></span> ///</span> @param</span> version</span> The version identifier to set as default</span></span> function</span> setDefaultVersion</span>(</span>bytes32</span> version</span>)</span> external</span>;</span></span> </span></span> ///</span> @notice</span> Gets the implementation address for a specific version</span></span> ///</span> @param</span> version</span> The version identifier</span></span> ///</span> @return</span> The</span> implementation address for the specified version</span></span> function</span> getImplementation</span>(</span>bytes32</span> version</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span> </span></span> ///</span> @notice</span> Gets the current default version</span></span> ///</span> @return</span> The</span> current default version identifier</span></span> function</span> getDefaultVersion</span>(</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span> </span></span> ///</span> @notice</span> Gets all registered versions</span></span> ///</span> @return</span> An</span> array of all registered version identifiers</span></span> function</span> getVersions</span>(</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>[</span>]</span> memory</span>)</span>;</span></span> </span></span> ///</span> @notice</span> Executes a call to a specific implementation version</span></span> ///</span> @param</span> version</span> The version identifier of the implementation to call</span></span> ///</span> @param</span> data</span> The calldata to forward to the implementation</span></span> ///</span> @return</span> The</span> return data from the implementation call</span></span> function</span> executeAtVersion</span>(</span>bytes32</span> version</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> payable</span> returns</span> (</span>bytes</span> memory</span>)</span>;</span></span> }</span></span></code></pre>Behavior Requirements</h3> The proxy contract MUST maintain a mapping of version identifiers to implementation addresses.</li> The proxy contract MUST maintain a default version that is used when no version is specified.</li> When executeAtVersion</code> is called, the proxy MUST: Verify the specified version exists</li> Forward the call to the corresponding implementation</li> Return any data returned by the implementation</li> </ul> </li> The proxy contract MUST emit appropriate events when versions are registered, or when the default version changes.</li> The proxy contract SHOULD implement access control for administrative functions (registering versions, setting default).</li> The proxy contract MAY implement EIP-1967</a> storage slots for compatibility with existing tools.</li> </ol> Fallback Function</h3> The proxy contract SHOULD implement a fallback function that forwards calls to the default implementation version when no version is specified. This maintains compatibility with traditional proxy patterns.</p> Rationale</h2> Version Identifiers as bytes32</h3> Version identifiers are specified as bytes32</code> rather than semantic versioning strings to:</p> Provide flexibility in versioning schemes</li> Reduce gas costs for storage and comparison</li> Allow for both string-based versions (converted to bytes32) and numeric versions</li> Allow for storing a Git commit identifier in SHA-1 or SHA-256</li> </ol> Explicit Version Selection</h3> The standard requires callers to explicitly select a version through executeAtVersion</code> rather than encoding version information in the call data to:</p> Maintain a clean separation between version selection and function calls</li> Avoid modifying existing function signatures</li> Make version selection explicit and auditable</li> </ol> Registry Pattern</h3> The registry pattern was chosen over alternatives like:</p> Multiple Proxies</strong>: Having separate proxies for each version would increase deployment costs and complexity</li> Version in Storage</strong>: Storing a single "current version" would not allow different callers to use different versions simultaneously</li> </ol> Default Version</h3> The default version mechanism allows the proxy to maintain compatibility with traditional proxy patterns and supports callers that don't need to specify a version.</p> Backwards Compatibility</h2> This EIP is designed to enhance backward compatibility for smart contracts. It does not introduce any backward incompatibilities with existing Ethereum standards or implementations.</p> Existing contracts that interact with proxy contracts can continue to do so without modification, as the fallback function will route calls to the default implementation.</p> Security Considerations</h2> This EIP is meant to significantly improve the security of the widely used proxy pattern.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> PermaLink Asset Bound Token 2025-04-01T00:00:00+00:00 Abstract</h2> This standard introduces a subclass of tokens known as PermaLink Asset Bound Tokens (PermaLink-ABTs)</strong>. They are a specific implementation of the broader Asset Bound Token (ABT)</strong> concept. ABTs establish a novel ownership paradigm where an asset can own another asset</strong>, enabling composable, nested, and portfolio-like token structures that evolve together over time.</p> PermaLink-ABTs implement a permanent binding mechanism where a token in one smart contract is irreversibly linked to a token in another contract. These links mirror key state data such as ownerOf</code>, tokenId</code>, totalSupply</code>, and balanceOf</code> using the assetBoundContract</code> interface. Traditional token transfer and approval functions are omitted to enforce immutability and structural cohesion between bound assets.</p> Instead of utilizing a mint</code> function, PermaLink-ABTs employ a reveal</code> mechanism that activates tokens from a predefined supply. This approach enables permissionless binding and significantly reduces gas costs. A single token can have multiple PermaLink-ABTs bound to it, acting as multiple subordinate assets, forming a unified, transferable unit that simplifies asset mobility across digital identities, NFTs, and real-world assets (RWAs).</p> By encouraging asset composability over competition, PermaLink-ABTs introduce a dynamic, future-proof model for on-chain asset evolution.</p> Motivation</h2> Traditional ownership models on Ethereum are inherently limited. Only externally owned accounts (EOAs) or smart contracts can own blockchain assets. This creates rigidity, especially as the blockchain ecosystem expands to include digital identities, tokenized real-world assets (RWAs), and NFTs. Current smart contracts are static in nature, meaning once deployed, they cannot adapt to evolving systems, unforeseen use cases, or new integration layers. There is a need for a more flexible and modular ownership model that allows for dynamic interactions between assets.</p> This standard proposes Asset Bound Tokens (ABTs)</strong> as a solution to this challenge. ABTs allow one token to be permanently bound to another across contracts, creating a dynamic, flexible, and composable ownership model. By enabling tokens to move and evolve together, ABTs pave the way for new possibilities in the on-chain economy. The following use cases illustrate why ABTs are needed:</p> On-Chain Identity Systems</strong> Governments and institutions worldwide are piloting or implementing blockchain-based identity systems, digital passports, national IDs, and verifiable credentials such as with the ongoing European Blockchain Services Infrastructure (EBSI) initiatives. These systems often require credentials to be linked across multiple registries (e.g., healthcare, banking, voting). ABTs enable the binding of identity-linked tokens into a cohesive unit, so they move together instead of requiring manual coordination and transfers. This ensures that identity-linked assets remain interconnected and dynamic, making it easier to manage and update linked data as users interact with various systems.</p> </li> Real-World Asset (RWA) Ownership Structures</strong> Tokenized businesses and assets (e.g., land, equipment, commodities) need flexible ownership models. These dynamic—businesses acquire, divest, and restructure their holdings and various assets. ABTs allow contracts to represent complex, evolving ownership hierarchies, where nested assets follow changes in their parent entity’s structure (e.g., a farming company acquiring new land or an IT firm merging with another and inheriting intellectual property). ABTs ensure businesses can efficiently manage and transfer assets on-chain without the constraints of rigid smart contracts.</p> </li> Manufacturing and Supply Chain Management</strong> Supply chains involve multiple layers of assets: raw materials → parts → products → packaging → containers. Blockchain’s transparency is invaluable, but traditional methods of creating individual tokens or smart contracts for each stage are inefficient and costly. ABTs streamline this by linking tokens across the supply chain, allowing them to be aggregated when products are built up (e.g., shoes packed in boxes, boxes placed on pallets, pallets loaded into containers) and broken down as they move through different stages (e.g., containers unloaded, pallets split, boxes unpacked). This dynamic linking and unlinking reduce redundancy, maintain transparent immutable records, and ensure seamless tracking while minimizing gas costs. By enabling the efficient flow of assets throughout the supply chain, ABTs help reduce complexity and provide a cohesive, real-time view of the entire process.</p> </li> NFT Ecosystem Optimization</strong> NFT projects often expand by launching secondary collections (e.g., additional editions, special releases). Without ABTs, this leads to fragmented value and user confusion as older and newer assets compete. ABTs allow new NFTs to be bound to originals, enhancing their value while maintaining a unified ecosystem. This strengthens liquidity and preserves market metrics, ensuring that the value of the original collection is retained and supported by the newer assets, thus benefiting both creators and collectors.</p> </li> New Opportunities for Creators</strong> ABTs empower creators to build on top of existing assets permissionlessly without needing ownership of or permission from the original smart contract. This enables a new wave of creative expression, where artists can augment and enhance NFTs (e.g., adding new visuals, audio, or interactive layers) and collaborate on existing collections. Such contributions can generate new revenue streams through shared royalties, consignment, or collaborative upgrades. Owners benefit as well, since bound enhancements can increase the inherent value of their holdings, particularly in projects involving established creators or cross-collection collaborations.</p> </li> </ol> In essence, ABTs introduce a framework where tokens are linked rather than owned. This allows for dynamic and evolving asset systems, where assets move together in harmony. If a binding token moves, all associated ABTs move with it, ensuring seamless updates and reducing the need for manual transfers. This innovation transforms traditional smart contracts from static repositories into living, evolving systems capable of adapting to changing use cases, technologies, and business models.</p> The PermaLink-ABTs</strong> implementation takes the ABT model further by enforcing a permanent binding between one token and another—whether it's another ABT, NFT or NFKBT. This permanent binding ensures that tokens can be transferred as a single unit, reducing complexity and gas fees. Instead of relying on traditional minting, PermaLink-ABTs use a reveal</code> mechanism, activating tokens from a predefined supply. This reduces gas costs and encourages efficient linking of assets, enabling greater composability across multiple sectors.</p> PermaLink-ABTs consolidate asset value by allowing multiple subordinate tokens to be linked to a single binding token, providing enhanced composability and reducing fragmentation. By requiring only the binding token to be transferred, all associated assets move in sync, making it easier to manage portfolios and move groups of assets together. This approach fosters collaboration, value accrual, and compatibility across ecosystems, whether for digital identities, RWAs, NFTs, or other on-chain assets.</p> Specification</h2> IERC7929</code> (Token Interface)</h3> NOTES</strong>:</p> The following specifications use syntax from Solidity 0.8.27</code> (or above)</li> </ul> interface</span> IERC7929</span> {</span></span> event</span> AssetBoundContractSet</span>(</span>address</span> assetBoundContract</span>)</span>;</span></span> </span> function</span> ownerOf</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span> function</span> tokenExists</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> function</span> totalSupply</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> function</span> balanceOf</span>(</span>address</span> owner</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> }</span></span></code></pre>Events</h3> AssetBoundContractSet</code> Event</h4> Emitted when the contract is deployed and bound to assetBoundContract</code></p> event</span> AssetBoundContractSet</span>(</span>address</span> assetBoundContract</span>)</span>;</span></span></code></pre>Functions</h3> The functions detailed below MUST be implemented.</p> ownerOf</code></h4> Returns the owner of the NFT specified by the tokenId</code>. Will read from the assetBoundContract</code> the owner and return it.</p> function</span> ownerOf</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span></code></pre>tokenExists</code></h4> Returns true if the token read from the assetBoundContract</code> exists. Tokens usually start existing when minted and stop existing when burned.</p> function</span> tokenExists</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span></code></pre>totalSupply</code></h4> Gets the total amount of tokens stored by the assetBoundContract</p> function</span> totalSupply</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span></code></pre>balanceOf</code></h4> Returns the number of NFTs in the assetBoundContract that an owner has.</p> function</span> balanceOf</span>(</span>address</span> owner</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span></code></pre>IERC7929Reveal</code> (Optional Token Interface)</h3> NOTES</strong>:</p> The following specifications use syntax from Solidity 0.8.27</code> (or above)</li> The Reveal extension is OPTIONAL for ERC-7929</a> contracts</li> </ul> interface</span> IERC7929Reveal</span> is</span> IERC7929</span> {</span></span> event</span> TokenRevealed</span>(</span>uint256</span> tokenId</span>)</span>;</span></span> </span> function</span> reveal</span>(</span>uint256</span>[</span>]</span> calldata</span> tokenIds</span>)</span> external</span> payable</span>;</span></span> }</span></span></code></pre>Events</h3> TokenRevealed</code> Event</h4> Emitted when the tokenId</code> is revealed</p> event</span> TokenRevealed</span>(</span>uint256</span> tokenId</span>)</span>;</span></span></code></pre>Functions</h3> The functions detailed below MUST be implemented.</p> reveal</code></h3> The reveal</code> function should be implemented to allow pre-allocated tokens to be activated on demand. This method reduces gas consumption compared to traditional minting and simplifies token activation mechanics.</p> function</span> reveal</span>(</span>uint256</span>[</span>]</span> calldata</span> tokenIds</span>)</span> external</span> payable</span>;</span></span></code></pre>Rationale</h2> The design of PermaLink-ABTs centers around the goal of enabling permanent token binding while optimizing for gas efficiency, composability, and secure ownership structures. We adopted the assetBoundContract</code> interface to mirror essential metadata such as ownerOf</code>, tokenId</code>, totalSupply</code>, and balanceOf</code> from the binding token’s contract. This ensures that PermaLink-ABTs remain synchronized with the asset they are bound to, without duplicating logic or requiring manual updates. The mirroring also ensures traceability and visibility across contracts, allowing observers and off-chain systems to reliably interpret the token relationship. To preserve the permanent nature of the bond, standard transfer</code> and approve</code> methods are omitted. This immutability guarantees that PermaLink-ABTs cannot be separated from their bound asset once revealed. If the primary token moves, all attached PermaLink-ABTs move with it. This behavior supports composability, value aggregation, and consistent ownership logic.</p> An alternative considered was allowing flexible transfer mechanics via opt-in transfer functions or whitelisting. However, this introduced unnecessary complexity and undermined the core principle of permanence. It also increased the risk of token desynchronization, accidental fragmentation, and security vulnerabilities in contract implementations. By contrast, the current design provides a simpler and more robust foundation.</p> By implementing an optional</strong> reveal</code> function in place of a traditional mint</code> function it reduce gas costs and simplifies on-chain state changes for both the deployer and owner of the token having an ABT bound to it. Unlike minting, which creates tokens at runtime and incurs higher gas fees, the reveal</code> function maps pre-allocated tokens stored in an array or mapping. This allows tokens to be activated on demand without the overhead of dynamic token creation. As a result, token issuers can prepare and store an entire supply in advance, with users later revealing and binding tokens when needed. This approach aligns with the use case of portfolio binding and asset hierarchies, where large numbers of tokens may need to be activated and bound efficiently.</p> PermaLink-ABTs enforce strict one-way binding with immutable relationships, making them especially suitable for use cases like identity systems, real-world asset (RWA) structures, and portfolio-locked NFTs. They act as permanently attached extensions to existing tokens, reducing complexity and avoiding redundant contract logic. This approach also provides a cleaner and more secure way to augment existing assets while maintaining compatibility across various blockchain use cases. This standard is intentionally minimal to ensure wide compatibility and flexibility. Developers can extend the base logic for specialized use cases, such as embedding royalty splits, upgrade paths, or linking to dynamic data feeds, without altering the underlying PermaLink mechanism.</p> Reference Implementation</h2> ERC7929</code> (Token implementation)</h3> NOTES</strong>:</p> The interface ID is (0x0b76916c</code>)</li> Callers MUST handle false</code> from returns (bool success)</code>. Callers MUST NOT assume that false</code> is never returned!</li> </ul> contract</span> ERC7929</span> is</span> IERC165</span>, </span>ERC721Enumerable</span>, </span>Ownable</span>, </span>IERC7929</span> {</span></span> ERC721Enumerable </span>public</span> assetBoundContract</span>;</span></span> </span> constructor</span>(</span></span> address</span> _assetBoundContract</span>,</span></span> string</span> memory</span> _name</span>,</span></span> string</span> memory</span> _symbol</span></span> )</span> ERC721</span>(</span>_name, _symbol) </span>{</span></span> assetBoundContract </span>=</span> ERC721Enumerable</span>(</span>_assetBoundContract</span>)</span>;</span></span> </span> emit</span> AssetBoundContractSet</span>(</span>_assetBoundContract</span>)</span>;</span></span> }</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span> region EIP-165 Implementation</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> </span> /</span></span> </span>@dev</span> See {IERC165-supportsInterface}.</span></span> /</span></span> function</span> supportsInterface</span>(</span></span> bytes4</span> interfaceId</span></span> )</span> public</span> view</span> virtual</span> override</span>(</span>ERC721Enumerable</span>,</span> IERC165</span>)</span> returns</span> (</span>bool</span>)</span> {</span></span> return</span></span> interfaceId </span>==</span> type</span>(</span>IERC7929</span>)</span>.</span>interfaceId </span>\|\|</span></span> super</span>.</span>supportsInterface</span>(</span>interfaceId</span>)</span>;</span></span> }</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span> endregion</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span> region Modifiers</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> </span> modifier</span> tokensMustExist</span>(</span>uint256</span>[</span>]</span> calldata</span> tokenIds</span>)</span> {</span></span> for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> tokenIds</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span> require</span>(</span>tokenExists</span>(</span>tokenIds</span>[</span>i</span>]</span>)</span>,</span> "ERC7929: Token does not exist"</span>)</span>;</span></span> }</span></span> _</span>;</span></span> }</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span> endregion Modifiers</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span> region mirror functions</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> </span> function</span> ownerOf</span>(</span></span> uint256</span> tokenId</span></span> )</span></span> public</span></span> view</span></span> virtual</span></span> override</span>(</span>ERC721</span>,</span> IERC7929</span>,</span> IERC721</span>)</span></span> returns</span> (</span>address</span>)</span></span> {</span></span> return</span> assetBoundContract</span>.</span>ownerOf</span>(</span>tokenId</span>)</span>;</span></span> }</span></span> </span> function</span> tokenExists</span>(</span>uint256</span> tokenId</span>)</span> public</span> view</span> virtual</span> returns</span> (</span>bool</span>)</span> {</span></span> return</span> assetBoundContract</span>.</span>ownerOf</span>(</span>tokenId</span>)</span> !=</span> address</span>(</span>0</span>)</span>;</span></span> }</span></span> </span> function</span> totalSupply</span>(</span>)</span></span> public</span></span> view</span></span> virtual</span></span> override</span>(</span>ERC721Enumerable</span>,</span> IERC7929</span>)</span></span> returns</span> (</span>uint256</span>)</span></span> {</span></span> return</span> assetBoundContract</span>.</span>totalSupply</span>(</span>)</span>;</span></span> }</span></span> </span> function</span> balanceOf</span>(</span></span> address</span> owner</span></span> )</span></span> public</span></span> view</span></span> virtual</span></span> override</span>(</span>ERC721</span>,</span> IERC7929</span>,</span> IERC721</span>)</span></span> returns</span> (</span>uint256</span>)</span></span> {</span></span> return</span> assetBoundContract</span>.</span>balanceOf</span>(</span>owner</span>)</span>;</span></span> }</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span>endregion</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span>region Disabling approve and transfer functions to prevent transfers of ABT tokens</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> </span> function</span> approve</span>(</span>address</span>,</span> uint256</span>)</span> public</span> pure</span> override</span>(</span>ERC721</span>,</span> IERC721</span>)</span> {</span></span> revert</span>(</span>"ERC7929: Approvals not allowed"</span>)</span>;</span></span> }</span></span> </span> function</span> setApprovalForAll</span>(</span></span> address</span>,</span></span> bool</span></span> )</span> public</span> pure</span> override</span>(</span>ERC721</span>,</span> IERC721</span>)</span> {</span></span> revert</span>(</span>"ERC7929: Approvals not allowed"</span>)</span>;</span></span> }</span></span> </span> function</span> transferFrom</span>(</span></span> address</span>,</span></span> address</span>,</span></span> uint256</span></span> )</span> public</span> pure</span> override</span>(</span>ERC721</span>,</span> IERC721</span>)</span> {</span></span> revert</span>(</span>"ERC7929: Transfers not allowed"</span>)</span>;</span></span> }</span></span> </span> function</span> safeTransferFrom</span>(</span></span> address</span>,</span></span> address</span>,</span></span> uint256</span></span> )</span> public</span> pure</span> override</span>(</span>ERC721</span>,</span> IERC721</span>)</span> {</span></span> safeTransferFrom</span>(</span>address</span>(</span>0</span>)</span>,</span> address</span>(</span>0</span>)</span>,</span> 0</span>,</span> ""</span>)</span>;</span></span> }</span></span> </span> function</span> safeTransferFrom</span>(</span></span> address</span>,</span></span> address</span>,</span></span> uint256</span>,</span></span> bytes</span> memory</span></span> )</span> public</span> pure</span> override</span>(</span>ERC721</span>,</span> IERC721</span>)</span> {</span></span> revert</span>(</span>"ERC7929: Transfers not allowed"</span>)</span>;</span></span> }</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span>endregion</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> }</span></span></code></pre>IERC7929Reveal</code> (Token implementation)</h3> NOTES</strong>:</p> This is an OPTIONAL extension for ERC-7929</a> contracts</li> The interface ID is (0xb93f208a</code>)</li> Callers MUST handle false</code> from returns (bool success)</code>. Callers MUST NOT assume that false</code> is never returned!</li> </ul> contract</span> ERC7929Reveal</span> is</span> ERC7929</span>, </span>IERC7929Reveal</span> {</span></span> mapping</span>(</span>uint256</span> =></span> bool</span>)</span> public</span> isRevealed</span>;</span></span> </span> constructor</span>(</span></span> address</span> _assetBoundContract</span>,</span></span> string</span> memory</span> _name</span>,</span></span> string</span> memory</span> _symbol</span></span> )</span> ERC7929</span>(</span>_assetBoundContract, _name, _symbol) </span>{</span>}</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span> region EIP-165 Implementation</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> </span> /</span></span> </span>@dev</span> See {IERC165-supportsInterface}.</span></span> /</span></span> function</span> supportsInterface</span>(</span></span> bytes4</span> interfaceId</span></span> )</span> public</span> view</span> virtual</span> override</span> returns</span> (</span>bool</span>)</span> {</span></span> return</span></span> interfaceId </span>==</span> type</span>(</span>IERC7929Reveal</span>)</span>.</span>interfaceId </span>\|\|</span></span> super</span>.</span>supportsInterface</span>(</span>interfaceId</span>)</span>;</span></span> }</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span> endregion</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span> region Modifiers</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> </span> modifier</span> tokensMustNotBeRevealed</span>(</span>uint256</span>[</span>]</span> calldata</span> tokenIds</span>)</span> {</span></span> for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> tokenIds</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span> require</span>(</span></span> !</span>isRevealed</span>[</span>tokenIds</span>[</span>i</span>]</span>]</span>,</span></span> "ERC7929: Token already revealed"</span></span> )</span>;</span></span> }</span></span> _</span>;</span></span> }</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span> endregion Modifiers</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span> region mirror functions</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> </span> function</span> ownerOf</span>(</span></span> uint256</span> tokenId</span></span> )</span> public</span> view</span> override</span>(</span>ERC7929</span>,</span> IERC7929</span>)</span> returns</span> (</span>address</span>)</span> {</span></span> return</span> super</span>.</span>ownerOf</span>(</span>tokenId</span>)</span>;</span></span> }</span></span> </span> function</span> tokenExists</span>(</span></span> uint256</span> tokenId</span></span> )</span> public</span> view</span> override</span>(</span>ERC7929</span>,</span> IERC7929</span>)</span> returns</span> (</span>bool</span>)</span> {</span></span> return</span> super</span>.</span>tokenExists</span>(</span>tokenId</span>)</span>;</span></span> }</span></span> </span> function</span> totalSupply</span>(</span>)</span></span> public</span></span> view</span></span> override</span>(</span>ERC7929</span>,</span> IERC7929</span>)</span></span> returns</span> (</span>uint256</span>)</span></span> {</span></span> return</span> super</span>.</span>totalSupply</span>(</span>)</span>;</span></span> }</span></span> </span> function</span> balanceOf</span>(</span></span> address</span> owner</span></span> )</span> public</span> view</span> override</span>(</span>ERC7929</span>,</span> IERC7929</span>)</span> returns</span> (</span>uint256</span>)</span> {</span></span> return</span> super</span>.</span>balanceOf</span>(</span>owner</span>)</span>;</span></span> }</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span>endregion</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span>region Reveal function to reveal the token URI for a given token ID(s)</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> </span> function</span> reveal</span>(</span></span> uint256</span>[</span>]</span> calldata</span> tokenIds</span></span> )</span></span> public</span></span> payable</span></span> virtual</span></span> tokensMustExist</span>(</span>tokenIds</span>)</span></span> tokensMustNotBeRevealed</span>(</span>tokenIds</span>)</span></span> {</span></span> for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> tokenIds</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span> isRevealed</span>[</span>tokenIds</span>[</span>i</span>]</span>]</span> =</span> true</span>;</span></span> emit</span> TokenRevealed</span>(</span>tokenIds</span>[</span>i</span>]</span>)</span>;</span></span> }</span></span> }</span></span> </span> ///</span>////////////////////////////////////////////////////////////</span></span> //</span>endregion</span></span> ///</span>////////////////////////////////////////////////////////////</span></span> }</span> </span></span></code></pre>Security Considerations</h2> PermaLink-ABTs are linked to another non-fungible token. If an individual loses access to this token, what we call the binding token</strong>, they also lose access to all PermaLink-ABTs that have been bound to it. This introduces a critical security consideration: the entire value of bound assets depends on the integrity and availability of the binding token.</p> To mitigate this risk, we strongly recommend the use of standards like ERC-6809</a>, a Non-Fungible Key Bound Token</strong>, which introduces on-chain two-factor authentication (2FA). ERC-6809 allows a user to bind sensitive tokens (like PermaLink-ABTs) to a secured identity layer, complete with recovery mechanisms. In the event that a user loses access to their original wallet or interacts with a malicious contract, ERC-6809 provides a safeFallback function to re-establish control.</p> In essence, all of the security guarantees of ERC-6809 extend to any PermaLink-ABTs bound to it. This layered security model not only protects against loss but also ensures recoverability and long-term viability for high-value bound assets. It is strongly encouraged that developers implementing PermaLink-ABTs integrate this or similar standards to provide a robust security foundation for users.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Signature Verifiers 2025-03-21T00:00:00+00:00 Abstract</h2> Externally Owned Accounts (EOA) can sign messages with their associated private keys. Additionally ERC-1271</a> defines a method for signature verification by smart accounts such as multisig. In both cases the identity of the signer is an ethereum address. We propose a standard to extend this concept of signer description, and signature verification, to keys that do not have an ethereum identity of their own, in the sense that they don't have their own address to represent them.</p> This new mechanism can be used to integrate new signers such as non-ethereum cryptographic curves, hardware devices, or even email addresses. This is particularly relevant when dealing with things like social-recovery of smart accounts.</p> Motivation</h2> With the development of account abstraction, there is an increasing need for non-ethereum signature verification. Cryptographic algorithms besides the natively supported secp256k1 are being used for controlling smart accounts. In particular, curves such as secp256r1 (supported by many mobile devices) and RSA keys (that are distributed by traditional institutions) are widely available. Beyond these two examples, we also see the emergence of ZK solutions for signing with emails or JWT from big Web2 services.</p> All these signature mechanisms have one thing in common: they do not have a canonical ethereum address to represent them onchain. While users could deploy ERC-1271 compatible contracts for each key individually, this would be cumbersome and expensive. As account abstraction tries to separate account addresses (that hold assets) from the key that controls them, giving fixed on-chain addresses to keys (and possibly sending assets to these addresses by mistake) is not the right approach. Instead, using a small number of verifier contracts that can process signatures in a standard way, and having the accounts rely on these verifiers, feels like the correct approach. This has the advantage that once the verifier is deployed, any key can be represented using a (verifier, key)</code> pair without requiring any setup cost.</p> The (verifier, key)</code> pairs can be given permission to control a smart account, perform social recovery, or do any other operation without ever having a dedicated on-chain address. Systems that want to adopt this approach need to transition away from the model where signers are identified by their address to a new model where signers may not have an address, and are identified by a bytes</code> object.</p> This definition is backward compatible with EOA and ERC-1271 contracts: in that case, we use the address of the identity (EOA or contract) as the verifier and the key is empty.</p> Specification</h2> 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.</p> Nomenclature</h3> Keys are represented using bytes</code> objects of arbitrary length. For example a P256 or RSA public key. Keys MUST NOT be empty.</li> Verifiers are smart contracts in charge of signature verification for a given type of key. They have an ethereum address.</li> </ul> Signature Verifier interface</h3> Verifiers MUST implement the following interface:</p> interface</span> IERC7913SignatureVerifier</span> {</span></span> /</span></span> </span>@dev</span> Verifies `signature` as a valid signature of `hash` by `key`.</span></span> </span></span> MUST return the bytes4 magic value 0x024ad318 (IERC7913SignatureVerifier.verify.selector) if the signature is valid.</span></span> * SHOULD return 0xffffffff or revert if the signature is not valid.</span></span> * SHOULD return 0xffffffff or revert if the key is empty</span></span> /</span></span> function</span> verify</span>(</span>bytes</span> calldata</span> key</span>,</span> bytes32</span> hash</span>,</span> bytes</span> calldata</span> signature</span>)</span> external</span> view</span> returns</span> (</span>bytes4</span>)</span>;</span></span> }</span></span></code></pre> Verifiers SHOULD be stateless.</p> Rationale</h2> Verifiers can be used to avoid deploying many ERC-1271 "identity contract" (one per key), which would be expensive. Using this model, new keys can be used without any deployment costs.</p> ERC-1271 already covers the cases were a key is not necessary. To avoid ambiguity, the verifiers contracts should not support (or be expected to support) empty keys. Signers that are 20 bytes long (empty key) should be handled using ERC-1271.</p> Consistency with existing systems (ecrecover and ERC-1271) requires the message to be bytes32</code> hash. These are usually produced following ERC-191</a> or ERC-712</a>. Cryptographic systems that use different hashing methods SHOULD see this hash as a message, and possibly rehash it following the relevant standards.</p> Backwards Compatibility</h2> A system can support ERC-7913</a> signers alongside EOAs and ERC-1271 in the following way.</p> A signer is a bytes</code> object that is the concatenation of an address and optionally a key: verifier \|\| key</code>. A signer is at least 20 bytes long.</p> Given a signer signer</code>, a message hash hash</code>, and a signature sign</code>, verification is done as follows:</p> if signer.length < 20</code>: verification fails;</li> split signer</code> into (verifier, key)</code> with verifier</code> being the first 20 bytes and key</code> being the rest (potentially empty)</li> if key</code> is empty, then consider that verifier</code> is the identity. verification is done using ERC-1271's isValidSignature if there is code at verifier</code> address, or ecrecover otherwise</li> </ul> </li> if key</code> is not empty, call IERC7913SignatureVerifier(verifier).verify(key, hash, signature)</code> if the return value is the expected magic value (0x024ad318</code>) then verification is successful,</li> otherwise, verification fails.</li> </ul> </li> </ul> Reference Implementation</h2> In solidity, signature verification could be implemented in the following library:</p> import</span> {</span>SignatureChecker</span>}</span> from</span> '@openzeppelin/contracts/utils/cryptography/SignatureChecker.sol'</span>;</span></span> </span> ///</span> @dev</span> Extention of openzeppelin's SignatureChecker library</span></span> library</span> SignatureCheckerExtended</span> {</span></span> function</span> isValidSignatureNow</span>(</span>bytes</span> calldata</span> signer</span>,</span> bytes32</span> hash</span>,</span> bytes</span> memory</span> signature</span>)</span> internal</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span> if</span> (</span>signer</span>.</span>length </span><</span> 20</span> )</span> {</span></span> return</span> false</span>;</span></span> }</span> else</span> if</span> (</span>signer</span>.</span>length </span>==</span> 20</span>)</span> {</span></span> return</span> SignatureChecker</span>.</span>isValidSignatureNow</span>(</span>address</span>(</span>bytes20</span>(</span>signer</span>)</span>)</span>,</span> hash</span>,</span> signature</span>)</span>;</span></span> }</span> else</span> {</span></span> try</span> IERC7913SignatureVerifier</span>(</span>address</span>(</span>bytes20</span>(</span>signer</span>[</span>0</span>:</span>20</span>]</span>)</span>)</span>)</span>.</span>verify</span>(</span>signer</span>[</span>20</span>:</span>]</span>,</span> hash</span>,</span> signature</span>)</span> returns</span> (</span>bytes4</span> magic</span>)</span> {</span></span> return</span> magic </span>==</span> IERC7913SignatureVerifier</span>.</span>verify</span>.</span>selector</span>;</span></span> }</span> catch</span> {</span></span> return</span> false</span>;</span></span> }</span></span> }</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> Signer may be used for anything from smart account session key (with a short lifetime of a few hours/days) to social recovery "guardians" that may only be used several years after they are setup. In order to ensure that these signers remain valid "in perpetuity", the verifier contract should be trustless. This means that the verifiers should not be upgradeable contracts.</p> Verifiers should also not depend on any value that can be modified after deployment. In solidity terms, the verify</code> function should be pure. Any parameters that are involved in signature verification should either be part of the key, or part of immutable code of the verifier. Using immutable</code> variable (in solidity) would be safe. The stateless aspect of the verifier also ensure compliance (of the verifier) with ERC-7562</a> scope rules.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Composite EIP-712 Signatures 2025-03-20T00:00:00+00:00 Abstract</h2> This ERC provides a standard for signing multiple typed-data messages with a single signature by encoding them into a Merkle tree. This allows components to independently verify messages, without requiring full knowledge of the others. It provides a significant UX improvement by reducing the number of signature prompts to one, while preserving the security and flexibility of the EIP-712</a> standard.</p> This ERC also gives applications the flexibility to verify messages in isolation, or in aggregate. This opens up new verification modalities: for e.g, an application can require that message (x</code>) is only valid when signed in combination message (y</code>).</p> Motivation</h2> As the ecosystem moves towards ETH-less transactions, users are often required to sign multiple off-chain messages in quick succession. Typically, a first signature is needed for a precise spend allowance (via Permit2, ERC-2612</a>, etc.), followed by subsequent messages to direct the use of funds. This creates a frictional user experience as each signature requires a separate wallet interaction and creates confusion about what, in aggregate, is being approved.</p> Current solutions have significant drawbacks:</p> Pre-approving ERC-20</a> allowance:</strong> spend creates security vulnerabilities</li> Merging multiple messages into a single message:</strong> prevents independent verifiability. Each message cannot be verified without knowledge of the entire batch</li> Separate signature requests:</strong> creates friction in the user experience</li> </ul> This ERC has the following objectives:</p> Single Signature</h3> A single signature should cover multiple messages</p> Isolated Verification</h3> Messages should be independently verifiable without knowledge of others</p> Human-readable</h3> Readability benefits of EIP-712 should be preserved. Giving wallets and users insight into what is being signed.</p> Specification</h2> Overview</h3> The composite signature scheme uses a Merkle tree to hash multiple typed-data data messages together under a single root. The user signs only the Merkle root. The process is described below.</p> Generating a Composite Signature</h3> For a set of messages [m₁, m₂, ..., mₙ]</code>, encode each using EIP-712's encode</code> and compute its hash:</p> hashₙ = keccak256(encode(mₙ))</span></span></code></pre></li> Use these message hashes as leaf nodes in a Merkle tree and compute a merkleRoot</code></p> </li> Sign the merkle root.</p> signature = sign(merkleRoot)</span></span></code></pre></li> </ol> Verification Process</h3> To verify that an individual message mₓ</code> was included in a composite signature:</p> Verify the signature on the merkleRoot</code>:</p> recoveredSigner = ecrecover(merkleRoot, signature)</span></span> isValidSignature = (recoveredSigner == expectedSigner)</span></span></code></pre></li> Compute the leaf node for message mₓ</code> and verify its path to the Merkle root, using the proof:</p> leaf = keccak256(encode(mₓ))</span></span> isValidProof = _verifyMerkleProof(leaf, merkleProof, merkleRoot)</span></span></code></pre></li> </ol> Where _verifyMerkleProof()</code> is defined as:</p> function</span> _verifyMerkleProof</span>(</span></span> bytes32</span> leaf</span>,</span></span> bytes32</span>[</span>]</span> calldata</span> proof</span>,</span></span> bytes32</span> merkleRoot</span></span> )</span> internal</span> pure</span> returns</span> (</span>bool</span>)</span> {</span></span> bytes32</span> computedRoot </span>=</span> leaf</span>;</span></span> for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> proof</span>.</span>length</span>;</span> +</span>+</span>i</span>)</span> {</span></span> if</span> (</span>computedRoot </span><</span> proof</span>[</span>i</span>]</span>)</span> {</span></span> computedRoot </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>computedRoot</span>,</span> proof</span>[</span>i</span>]</span>)</span>)</span>;</span></span> }</span> else</span> {</span></span> computedRoot </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>proof</span>[</span>i</span>]</span>,</span> computedRoot</span>)</span>)</span>;</span></span> }</span></span> }</span></span> </span> return</span> computedRoot </span>==</span> merkleRoot</span>;</span></span> }</span></span></code></pre> The message is verified if and only if (1) and (2) succeed.</p> isVerified = isValidSignature && isValidProof</span></span></code></pre>Specification of eth_signTypedData_v5</code> JSON RPC method.</h3> This ERC adds a new method eth_signTypedData_v5</code> to Ethereum JSON-RPC. This method allows signing multiple typed data messages with a single signature using the specification described above. The signing account must be prior unlocked.</p> This method returns: the signature, merkle root, and an array of proofs (each corresponding to an input message).</p> Parameters</h4> Address</code> - Signing account</li> TypedData \| TypedDataArray</code> - A single TypedData object or Array of TypedData</code> objects from EIP-712.</li> </ol> Returns</h5> {</span></span> signature</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>;</span> //</span> Hex encoded 65 byte signature (same format as eth_sign)</span></span> merkleRoot</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>;</span> //</span> 32 byte Merkle root as hex string</span></span> proofs</span>:</span> Array</span><</span>Array</span><</span>`</span>0x</span>${</span>string</span>}</span>`</span>>></span>;</span> //</span> Array of Merkle proofs (one for each input message)</span></span> }</span></span></code></pre>Example</h5> Request:</p> {</span></span> "</span>jsonrpc</span>"</span>:</span> "</span>2.0</span>"</span>,</span></span> "</span>method</span>"</span>:</span> "</span>eth_signTypedData_v5</span>"</span>,</span></span> "</span>params</span>"</span>:</span> [</span></span> "</span>0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826</span>"</span>,</span></span> [</span></span> {</span></span> "</span>types</span>"</span>:</span> {</span></span> "</span>EIP712Domain</span>"</span>:</span> [</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>name</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>string</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>version</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>string</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>chainId</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>uint256</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>verifyingContract</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>address</span>"</span></span> }</span></span> ]</span>,</span></span> "</span>Person</span>"</span>:</span> [</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>name</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>string</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>wallet</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>address</span>"</span></span> }</span></span> ]</span>,</span></span> "</span>Mail</span>"</span>:</span> [</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>from</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>Person</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>to</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>Person</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>contents</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>string</span>"</span></span> }</span></span> ]</span></span> }</span>,</span></span> "</span>primaryType</span>"</span>:</span> "</span>Mail</span>"</span>,</span></span> "</span>domain</span>"</span>:</span> {</span></span> "</span>name</span>"</span>:</span> "</span>Ether Mail</span>"</span>,</span></span> "</span>version</span>"</span>:</span> "</span>1</span>"</span>,</span></span> "</span>chainId</span>"</span>:</span> 1</span>,</span></span> "</span>verifyingContract</span>"</span>:</span> "</span>0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC</span>"</span></span> }</span>,</span></span> "</span>message</span>"</span>:</span> {</span></span> "</span>from</span>"</span>:</span> {</span></span> "</span>name</span>"</span>:</span> "</span>Cow</span>"</span>,</span></span> "</span>wallet</span>"</span>:</span> "</span>0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826</span>"</span></span> }</span>,</span></span> "</span>to</span>"</span>:</span> {</span></span> "</span>name</span>"</span>:</span> "</span>Bob</span>"</span>,</span></span> "</span>wallet</span>"</span>:</span> "</span>0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB</span>"</span></span> }</span>,</span></span> "</span>contents</span>"</span>:</span> "</span>Hello, Bob!</span>"</span></span> }</span></span> }</span>,</span></span> {</span></span> "</span>types</span>"</span>:</span> {</span></span> "</span>EIP712Domain</span>"</span>:</span> [</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>name</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>string</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>version</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>string</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>chainId</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>uint256</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>verifyingContract</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>address</span>"</span></span> }</span></span> ]</span>,</span></span> "</span>Transfer</span>"</span>:</span> [</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>amount</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>uint256</span>"</span></span> }</span>,</span></span> {</span></span> "</span>name</span>"</span>:</span> "</span>recipient</span>"</span>,</span></span> "</span>type</span>"</span>:</span> "</span>address</span>"</span></span> }</span></span> ]</span></span> }</span>,</span></span> "</span>primaryType</span>"</span>:</span> "</span>Transfer</span>"</span>,</span></span> "</span>domain</span>"</span>:</span> {</span></span> "</span>name</span>"</span>:</span> "</span>Ether Mail</span>"</span>,</span></span> "</span>version</span>"</span>:</span> "</span>1</span>"</span>,</span></span> "</span>chainId</span>"</span>:</span> 1</span>,</span></span> "</span>verifyingContract</span>"</span>:</span> "</span>0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC</span>"</span></span> }</span>,</span></span> "</span>message</span>"</span>:</span> {</span></span> "</span>amount</span>"</span>:</span> "</span>1000000000000000000</span>"</span>,</span></span> "</span>recipient</span>"</span>:</span> "</span>0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB</span>"</span></span> }</span></span> }</span></span> ]</span></span> ]</span>,</span></span> "</span>id</span>"</span>:</span> 1</span></span> }</span></span></code></pre> Result:</p> {</span></span> "</span>id</span>"</span>: </span>1</span>,</span></span> "</span>jsonrpc</span>"</span>: </span>"</span>2.0</span>"</span>,</span></span> "</span>result</span>"</span>:</span> {</span></span> "</span>signature</span>"</span>:</span> "</span>0x4355c47d63924e8a72e509b65029052eb6c299d53a04e167c5775fd466751c9d07299936d304c153f6443dfa05f40ff007d72911b6f72307f996231605b915621c</span>"</span>,</span></span> "</span>merkleRoot</span>"</span>:</span> "</span>0x7de103665e21d6c9d9f82ae59675443bd895ed42b571c7f952c2fdc1a5b6e8d2</span>"</span>,</span></span> "</span>proofs</span>"</span>:</span> [</span></span> [</span>"</span>0x4bdbac3830d492ac3f4b0ef674786940fb33481b32392e88edafd45d507429f2</span>"</span>]</span>,</span></span> [</span>"</span>0x95be87f8abefcddc8116061a06b18906f32298a4644882d06baff852164858c6</span>"</span>]</span></span> ]</span></span> }</span></span> }</span></span></code></pre>Rationale</h2> The choice of using a Merkle tree to bundle messages provides the following additional benefits:</p> Efficient verification on-chain</h3> _verifyMerkleProof</code> has a runtime of O(log2(N))</code> where N is the number of messages that were signed.</p> Flexible Verification Modes</h3> Applications can require combination of messages be signed together to enhance security.</p> N=1</code> backwards compatibility</h3> Merkle signature for single message bundles are equal to eth_signTypedData_v4</code>. Requiring no onchain changes.</p> Backwards Compatibility</h2> When the number of message is one, eth_signTypedData_v5</code> produces the same signature as eth_signTypedData_v4</code> since merkleRoot == keccak256(encode(message))</code>. This allows eth_signTypedData_v5</code> to be a drop-in replacement for eth_signTypedData_v4</code> with no changes to on-chain verification.</p> Reference Implementation</h2> eth_signTypedData_v5</code></h3> Reference implementation of eth_signTypedData_v5</code> can be found the assets directory</a>.</p> Verifier</h3> Solidity implementation of a onchain verifier can be found the assets directory</a>.</p> Merkle</h3> Reference Merkle tree can be found in the assets directory</a>.</p> Security Considerations</h2> Replay Protection</h3> This ERC focuses on generating composite messages and verifying their signatures. It does not contain mechanisms to prevent replays. Developers must</strong> ensure their applications can handle receiving the same message twice.</p> Partial Message Verification</h3> During verification, care must</strong> be taken to ensure that both</strong> of these checks pass:</p> EIP-712 signature on the Merkle root is valid</li> Merkle proof is valid against the root</li> </ol> User Understanding</h3> Wallets must</strong> communicate to users that they are signing multiple messages at once. Wallets must</strong> display of all message types before signing.</p> To ensure batch signature requests are digestible, it is recommended to limit the maximum number of messages to 10.</p> Merkle Tree Construction</h3> Merkle tree should be constructed in a consistent manner.</p> The hashing function must</strong> be keccak256</code></li> To ensure predictable/consistent proof sizes, implementations must</strong> pad leaves with zero hashes to reach next power of two to ensure balance. Let n</code> be the number of messages. Before constructing the tree, compute the smallest k</code> such that 2^(k-1) < n ≤ 2^k</code>. Insert zero hashes into the list of messages until list of messages is equal to 2^k</code>.</li> To ensure an implicit verification path, pairs must</strong> be sorted lexicographically before constructing parent hash.</li> </ol> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> HD wallet In Treasury Management 2025-03-07T00:00:00+00:00 Abstract</h2> This proposal aims to provide a standardized method for on-chain treasury management of institutional assets, ensuring secure private key generation, hierarchical management, and departmental permission isolation while supporting asset security and transaction efficiency in multi-chain environments. By defining a unified derivation path and security mechanisms, this proposal offers an efficient and secure solution for treasury management.</p> Motivation</h2> With the rapid development of blockchain and DeFi, secure management of on-chain assets has become critical. Traditional private key management struggles to meet the security demands of large organizations in complex scenarios, where hierarchical key management, permission controls, and multi-signature mechanisms are essential. This proposal provides a standardized solution for institutional treasury management, ensuring asset security and transaction efficiency.</p> Specification</h2> 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</a> and RFC 8174</a>.</p> Derivation Path</h3> For secure on-chain treasury account key management, implementations MUST use the following hierarchical deterministic (HD) path:</p> m/44'/60'/entity_id' / department_id' / account_index</span></span></code></pre> Path Components:</p> Master Key (</strong>m</code>)</strong></p> SHALL represent the root HD wallet private key.</li> </ul> </li> BIP 44</a> Compliance Layer (44'</code>)</strong></p> MUST use 44'</code> (hardened) to indicate BIP 44 compliance.</li> </ul> </li> Coin Type Layer ( 60'</code> )</strong></p> SHALL use 60'</code> (hardened) for Ethereum and EVM-compatible chains.</li> </ul> </li> Entity Identifier ( entity_id'</code></strong>)</p> MUST be derived by hashing the subsidiary name into a hardened index.</li> MUST NOT reuse the same entity_id'</code> across distinct subsidiaries.</li> </ul> </li> Department Identifier (</strong>department_id'</code>)</strong></p> SHALL be derived by hashing the department name into a hardened index.</li> MUST isolate keys between departments via hardened derivation.</li> </ul> </li> Account Index (</strong>account_index</code>)</strong></p> MUST use non-hardened derivation to allow unified account management.</li> </ul> </li> </ol> Note on BIP 44 Adaptation</strong>:</p> The BIP 44 change</code> layer SHOULD be omitted for Ethereum/EVMs due to their account model (not UTXO).</li> </ul> Hash Conversion</h3> To derive entity_id</code> and department_id</code>:</p> Entity Index Calculation</strong></p> SHALL compute entity_id</code> as:</li> </ul> </li> </ol> entity_hash</span> =</span> sha256</span>(</span>f</span>"</span>ENTITY:</span>{</span>entity</span>}</span>"</span>.</span>encode</span>(</span>)</span>)</span>.</span>digest</span>(</span>)</span> </span></span> entity_index</span> =</span> int</span>.</span>from_bytes</span>(</span>entity_hash</span>[</span>:</span>4</span>]</span>,</span> "</span>big</span>"</span>)</span> \|</span> 0x</span>80000000</span> #</span> 2^31 ≤ index < 2^32</span></span></code></pre> Department Index Calculation</strong></p> MUST compute department_id</code> as:</li> </ul> </li> </ol> dept_hash</span> =</span> sha256</span>(</span>f</span>"</span>DEPT:</span>{</span>entity_hash</span>}</span>:</span>{</span>department</span>}</span>"</span>.</span>encode</span>(</span>)</span>)</span>.</span>digest</span>(</span>)</span> </span></span> dept_index</span> =</span> int</span>.</span>from_bytes</span>(</span>dept_hash</span>[</span>:</span>4</span>]</span>,</span> "</span>big</span>"</span>)</span> \|</span> 0x</span>80000000</span> #</span> 2^31 ≤ index < 2^32</span></span></code></pre> Output Constraints</strong></p> Generated indices MUST be integers in [2^31, 2^32-1]</code> to enforce hardened derivation.</li> </ul> </li> </ol> Extended Path for Role-Based Access</h3> For finer access control (e.g., roles within departments):</p> m/60'/entity_id' / department_id' /role_id'/ account_index</span></span></code></pre> Role Identifier (</strong>role_id'</code>)</strong></p> SHOULD use hardened derivation to isolate role-specific keys.</li> </ul> </li> </ol> Compatibility Note</strong>:</p> Omitting the 44'</code> layer MAY cause incompatibility with standard wallets (e.g., MetaMask).</li> Integrations with such wallets MUST implement custom plugins to handle this deviation.</li> </ul> Simplified Path for Smaller Entities</h3> For entities without subsidiaries:</p> m/44'/60' / department_id' /0/ account_index</span></span></code></pre> Compatibility Guarantee</strong></p> This structure SHOULD ensure compatibility with mainstream BIP 44 wallets.</li> </ul> Key Derivation Algorithm</h3> Implementations MUST adhere to:</p> E = Map<entity, List<Department>></span></span> n = Layer2 curve order</span></span> path = m/44'/60'/entity_id' / department_id' / account_index</span></span> BIP32() = Official BIP-0032 derivation function on secp256k1</span></span> hash = SHA256</span></span> root_key = BIP32(path)</span></span> for each E:</span></span> key = hash(root_key\|hierarchical_hash_to_index(entity,department))</span></span> return key</span></span></code></pre> Cryptographic Requirements</strong>:</p> SHALL use BIP 32</a> with secp256k1</code> for HD derivation.</li> MUST concatenate hashes with root keys to prevent cross-layer key leakage.</li> </ul> Compatibility Considerations</strong></h3> This specification is inspired by BIP 44 (m/purpose'/coin_type'/account'/change/address_index</code>), but:</p> SHALL NOT use the change</code> layer for Ethereum-based systems.</li> MAY extend the hierarchy beyond BIP 44’s 5-layer structure for organizational needs.</li> </ul> Rationale</h2> The scenarios for which the proposal applies are:</p> Company and Department Isolation</strong>: Different subsidiaries within the group, as well as different departments within each subsidiary, can create isolated on-chain accounts. Enhanced derivation is used to isolate exposure risks.</li> Group Unified Management Authority</strong>: The group administrator holds the master private key, which can derive all subsidiary private keys, granting the highest authority to view and initiate transactions across the entire group, facilitating unified management by the group administrator.</li> Shared Department Private Key</strong>: If subsidiary A's administrator, Alice, needs to share accounts under subsidiary A with a new administrator, Bob, she only needs to share the master private key of subsidiary A. Accounts from various departments can then be derived from this key.</li> Shared Audit Public Key</strong>: If the audit department needs to audit transactions under a specific department, the extended public key of the specified department can be shared with the audit department. Through this extended public key, all subordinate public keys under the department can be derived, allowing the audit department to track all transactions associated with these public key addresses.</li> </ol> Backwards Compatibility</h2> This standard complies with BIP 39, BIP 32, and BIP 44.</p> Reference Implementation</h2> """</span></span> Secure Treasury Management System</span></span> Enterprise-grade hierarchical deterministic wallet implementation compliant with BIP-44</span></span> """</span></span> </span> import</span> hashlib</span></span> import</span> logging</span></span> from</span> typing</span> import</span> Tuple</span>,</span> Dict</span></span> from</span> bip32utils</span> import</span> BIP32Key</span></span> from</span> eth_account</span> import</span> Account</span></span> from</span> mnemonic</span> import</span> Mnemonic</span> #</span> Add BIP39 support</span></span> </span> #</span> Configure logging</span></span> logging</span>.</span>basicConfig</span>(</span>level</span>=</span>logging</span>.</span>INFO</span>)</span></span> logger</span> =</span> logging</span>.</span>getLogger</span>(</span>"</span>TreasurySystem</span>"</span>)</span></span> </span> class</span> TreasurySystem</span>:</span></span> def</span> __init__</span>(</span>self</span>,</span> mnemonic</span>:</span> str</span>)</span>:</span></span> """</span></span> Initialize the treasury system</span></span> :param mnemonic: BIP-39 mnemonic (12/24 words)</span></span> """</span></span> if</span> not</span> Mnemonic</span>(</span>"</span>english</span>"</span>)</span>.</span>check</span>(</span>mnemonic</span>)</span>:</span></span> raise</span> ValueError</span>(</span>"</span>Invalid BIP-39 mnemonic</span>"</span>)</span></span> </span></span> #</span> Generate seed using standard BIP-39</span></span> self</span>.</span>seed</span> =</span> Mnemonic</span>.</span>to_seed</span>(</span>mnemonic</span>,</span> passphrase</span>=</span>"</span>"</span>)</span></span> self</span>.</span>root_key</span> =</span> BIP32Key</span>.</span>fromEntropy</span>(</span>self</span>.</span>seed</span>)</span></span> </span></span> logger</span>.</span>info</span>(</span>"</span>Treasury system initialized. Master key fingerprint: </span>%s</span>"</span>,</span> </span></span> self</span>.</span>root_key</span>.</span>Fingerprint</span>(</span>)</span>.</span>hex</span>(</span>)</span>)</span></span> </span> @</span>staticmethod</span></span> def</span> _hierarchical_hash</span>(</span>entity</span>:</span> str</span>,</span> department</span>:</span> str</span>)</span> -></span> Tuple</span>[</span>int</span>,</span> int</span>]</span>:</span></span> """</span></span> Hierarchical hash calculation (compliant with proposal spec)</span></span> Returns: (entity_index, department_index)</span></span> """</span></span> #</span> Entity hash</span></span> entity_hash</span> =</span> hashlib</span>.</span>sha256</span>(</span>f</span>"</span>ENTITY:</span>{</span>entity</span>}</span>"</span>.</span>encode</span>(</span>)</span>)</span>.</span>digest</span>(</span>)</span></span> entity_index</span> =</span> int</span>.</span>from_bytes</span>(</span>entity_hash</span>[</span>:</span>4</span>]</span>,</span> '</span>big</span>'</span>)</span> \|</span> 0x</span>80000000</span></span> </span></span> #</span> Department hash (chained)</span></span> dept_input</span> =</span> f</span>"</span>DEPT:</span>{</span>entity_hash</span>.</span>hex</span>(</span>)</span>}</span>:</span>{</span>department</span>}</span>"</span>.</span>encode</span>(</span>)</span></span> dept_hash</span> =</span> hashlib</span>.</span>sha256</span>(</span>dept_input</span>)</span>.</span>digest</span>(</span>)</span></span> dept_index</span> =</span> int</span>.</span>from_bytes</span>(</span>dept_hash</span>[</span>:</span>4</span>]</span>,</span> '</span>big</span>'</span>)</span> \|</span> 0x</span>80000000</span></span> </span></span> return</span> entity_index</span>,</span> dept_index</span></span> </span> def</span> _derive_key</span>(</span>self</span>,</span> path</span>:</span> list</span>)</span> -></span> BIP32Key</span>:</span></span> """</span>General key derivation method</span>"""</span></span> current_key</span> =</span> self</span>.</span>root_key</span></span> for</span> index</span> in</span> path</span>:</span></span> if</span> not</span> isinstance</span>(</span>index</span>,</span> int</span>)</span>:</span></span> raise</span> TypeError</span>(</span>f</span>"</span>Invalid derivation index type: </span>{</span>type</span>(</span>index</span>)</span>}</span>"</span>)</span></span> current_key</span> =</span> current_key</span>.</span>ChildKey</span>(</span>index</span>)</span></span> return</span> current_key</span></span> </span> def</span> generate_account</span>(</span>self</span>,</span> entity</span>:</span> str</span>,</span> department</span>:</span> str</span>,</span> </span></span> account_idx</span>:</span> int</span> =</span> 0</span>)</span> -></span> Dict</span>[</span>str</span>,</span> str</span>]</span>:</span></span> """</span></span> Generate department account (BIP44 5-layer structure)</span></span> Path: m/44'/60'/entity'/dept'/account_idx</span></span> """</span></span> e_idx</span>,</span> d_idx</span> =</span> self</span>.</span>_hierarchical_hash</span>(</span>entity</span>,</span> department</span>)</span></span> </span></span> #</span> BIP-44 standard path</span></span> derivation_path</span> =</span> [</span></span> 0x</span>8000002C</span>,</span> #</span> 44' (hardened)</span></span> 0x</span>8000003C</span>,</span> #</span> 60' (Ethereum)</span></span> e_idx</span>,</span> #</span> entity_index (hardened)</span></span> d_idx</span>,</span> #</span> department_index (hardened)</span></span> account_idx</span> #</span> address index</span></span> ]</span></span> </span></span> key</span> =</span> self</span>.</span>_derive_key</span>(</span>derivation_path</span>)</span></span> priv_key</span> =</span> key</span>.</span>PrivateKey</span>(</span>)</span>.</span>hex</span>(</span>)</span></span> </span></span> return</span> {</span></span> '</span>path</span>'</span>:</span> f</span>"</span>m/44</span>'/60</span>'/</span>{</span>e_idx</span>}</span>'/</span>{</span>d_idx</span>}</span>'/</span>{</span>account_idx</span>}</span>"</span>,</span></span> '</span>private_key</span>'</span>:</span> priv_key</span>,</span> #</span> Warning: Never expose this in production</span></span> '</span>address</span>'</span>:</span> Account</span>.</span>from_key</span>(</span>priv_key</span>)</span>.</span>address</span></span> }</span></span> </span> def</span> get_audit_xpub</span>(</span>self</span>,</span> entity</span>:</span> str</span>,</span> department</span>:</span> str</span>)</span> -></span> str</span>:</span></span> """</span></span> Retrieve department-level extended public key (for auditing)</span></span> Path: m/44'/60'/entity'/dept'</span></span> """</span></span> e_idx</span>,</span> d_idx</span> =</span> self</span>.</span>_hierarchical_hash</span>(</span>entity</span>,</span> department</span>)</span></span> path</span> =</span> [</span></span> 0x</span>8000002C</span>,</span> #</span> 44'</span></span> 0x</span>8000003C</span>,</span> #</span> 60'</span></span> e_idx</span>,</span> #</span> entity'</span></span> d_idx</span> #</span> dept'</span></span> ]</span></span> return</span> self</span>.</span>_derive_key</span>(</span>path</span>)</span>.</span>ExtendedKey</span>(</span>)</span></span> </span> def</span> get_dept_xprv</span>(</span>self</span>,</span> entity</span>:</span> str</span>,</span> department</span>:</span> str</span>)</span> -></span> str</span>:</span></span> """</span></span> Get department-level extended private key (strictly controlled)</span></span> Path: m/44'/60'/entity'/dept'</span></span> """</span></span> e_idx</span>,</span> d_idx</span> =</span> self</span>.</span>_hierarchical_hash</span>(</span>entity</span>,</span> department</span>)</span></span> path</span> =</span> [</span></span> 0x</span>8000002C</span>,</span> #</span> 44'</span></span> 0x</span>8000003C</span>,</span> #</span> 60'</span></span> e_idx</span>,</span> #</span> entity'</span></span> d_idx</span> #</span> dept'</span></span> ]</span></span> return</span> self</span>.</span>_derive_key</span>(</span>path</span>)</span>.</span>ExtendedKey</span>(</span>)</span></span> </span> </span> @</span>staticmethod</span></span> def</span> derive_addresses_from_xpub</span>(</span>xpub</span>:</span> str</span>,</span> count</span>:</span> int</span> =</span> 20</span>)</span> -></span> list</span>:</span></span> """</span>Derive addresses from extended public key (audit use)</span>"""</span></span> audit_key</span> =</span> BIP32Key</span>.</span>fromExtendedKey</span>(</span>xpub</span>)</span></span> return</span> [</span></span> Account</span>.</span>from_key</span>(</span></span> audit_key</span></span> .</span>ChildKey</span>(</span>i</span>)</span> #</span> Address index</span></span> .</span>PrivateKey</span>(</span>)</span></span> )</span>.</span>address</span></span> for</span> i</span> in</span> range</span>(</span>count</span>)</span></span> ]</span></span> </span> </span> if</span> __name__</span> ==</span> "</span>__main__</span>"</span>:</span></span> #</span> Example usage (remove private key printing in production)</span></span> try</span>:</span></span> #</span> Use standard mnemonic</span></span> mnemo</span> =</span> Mnemonic</span>(</span>"</span>english</span>"</span>)</span></span> mnemonic</span> =</span> mnemo</span>.</span>generate</span>(</span>strength</span>=</span>256</span>)</span></span> treasury</span> =</span> TreasurySystem</span>(</span>mnemonic</span>)</span></span> print</span>(</span>f</span>"</span>mnemonic: </span>{</span>mnemonic</span>}</span>"</span>)</span></span> </span></span> print</span>(</span>"</span>\n</span>=== Finance Department Account Generation ===</span>"</span>)</span></span> finance_acc1</span> =</span> treasury</span>.</span>generate_account</span>(</span>"</span>GroupA</span>"</span>,</span> "</span>Finance</span>"</span>,</span> 0</span>)</span></span> finance_acc2</span> =</span> treasury</span>.</span>generate_account</span>(</span>"</span>GroupA</span>"</span>,</span> "</span>Finance</span>"</span>,</span> 1</span>)</span></span> print</span>(</span>f</span>"</span>Account1 path: </span>{</span>finance_acc1</span>[</span>'</span>path</span>'</span>]</span>}</span>"</span>)</span></span> print</span>(</span>f</span>"</span>Account1 address: </span>{</span>finance_acc1</span>[</span>'</span>address</span>'</span>]</span>}</span>"</span>)</span></span> print</span>(</span>f</span>"</span>Account1 private key: </span>{</span>finance_acc1</span>[</span>'</span>private_key</span>'</span>]</span>}</span>"</span>)</span></span> print</span>(</span>f</span>"</span>Account2 path: </span>{</span>finance_acc2</span>[</span>'</span>path</span>'</span>]</span>}</span>"</span>)</span></span> print</span>(</span>f</span>"</span>Account2 address: </span>{</span>finance_acc2</span>[</span>'</span>address</span>'</span>]</span>}</span>"</span>)</span></span> print</span>(</span>f</span>"</span>Account2 private key: </span>{</span>finance_acc2</span>[</span>'</span>private_key</span>'</span>]</span>}</span>"</span>)</span></span> </span> print</span>(</span>"</span>\n</span>=== Audit Verification Test===</span>"</span>)</span></span> audit_xpub</span> =</span> treasury</span>.</span>get_audit_xpub</span>(</span>"</span>GroupA</span>"</span>,</span> "</span>Finance</span>"</span>)</span></span> print</span>(</span>f</span>"</span>Audit xpub: </span>{</span>audit_xpub</span>}</span>"</span>)</span></span> audit_addresses</span> =</span> TreasurySystem</span>.</span>derive_addresses_from_xpub</span>(</span>audit_xpub</span>,</span> 2</span>)</span></span> print</span>(</span>f</span>"</span>Audit-derived addresses: </span>{</span>audit_addresses</span>}</span>"</span>)</span></span> </span></span> assert</span> finance_acc1</span>[</span>'</span>address</span>'</span>]</span> in</span> audit_addresses</span>,</span> "</span>Audit verification failed</span>"</span></span> assert</span> finance_acc2</span>[</span>'</span>address</span>'</span>]</span> in</span> audit_addresses</span>,</span> "</span>Audit verification failed</span>"</span></span> print</span>(</span>"</span>✅ Audit verification successful</span>"</span>)</span></span> </span> print</span>(</span>"</span>\n</span>=== Department Isolation Test ===</span>"</span>)</span></span> other_dept_acc</span> =</span> treasury</span>.</span>generate_account</span>(</span>"</span>GroupA</span>"</span>,</span> "</span>Audit</span>"</span>,</span> 0</span>)</span></span> print</span>(</span>f</span>"</span>Account3 path: </span>{</span>other_dept_acc</span>[</span>'</span>path</span>'</span>]</span>}</span>"</span>)</span></span> print</span>(</span>f</span>"</span>Account3 address: </span>{</span>other_dept_acc</span>[</span>'</span>address</span>'</span>]</span>}</span>"</span>)</span></span> assert</span> other_dept_acc</span>[</span>'</span>address</span>'</span>]</span> not</span> in</span> audit_addresses</span>,</span> "</span>Isolation breach</span>"</span></span> print</span>(</span>"</span>✅ Department isolation effective</span>"</span>)</span></span> </span> </span> print</span>(</span>"</span>\n</span>=== Department Private Key Sharing Test ===</span>"</span>)</span></span> #</span> Gets the department layer extension private key</span></span> dept_xprv</span> =</span> treasury</span>.</span>get_audit_xpub</span>(</span>"</span>GroupA</span>"</span>,</span> "</span>Finance</span>"</span>)</span>.</span>replace</span>(</span>'</span>xpub</span>'</span>,</span> '</span>xprv</span>'</span>)</span> #</span> 实际应通过专用方法获取</span></span> print</span>(</span>f</span>"</span>Fiance xprv: </span>{</span>dept_xprv</span>}</span>"</span>)</span></span> #</span> Derive the account private key from the extension private key</span></span> dept_key</span> =</span> BIP32Key</span>.</span>fromExtendedKey</span>(</span>dept_xprv</span>)</span></span> derived_acc0_key</span> =</span> dept_key</span>.</span>ChildKey</span>(</span>0</span>)</span>.</span>PrivateKey</span>(</span>)</span>.</span>hex</span>(</span>)</span></span> derived_acc1_key</span> =</span> dept_key</span>.</span>ChildKey</span>(</span>1</span>)</span>.</span>PrivateKey</span>(</span>)</span>.</span>hex</span>(</span>)</span></span> print</span>(</span>f</span>"</span>Fiance derived_acc0_key: </span>{</span>derived_acc0_key</span>}</span>"</span>)</span></span> print</span>(</span>f</span>"</span>Fiance derived_acc1_key: </span>{</span>derived_acc1_key</span>}</span>"</span>)</span></span> #</span> Verify the private key derivation capability</span></span> assert</span> derived_acc0_key</span> ==</span> finance_acc1</span>[</span>'</span>private_key</span>'</span>]</span>,</span> \</span></span> "</span>Account 0 private key derivation failed</span>"</span></span> assert</span> derived_acc1_key</span> ==</span> finance_acc2</span>[</span>'</span>private_key</span>'</span>]</span>,</span> \</span></span> "</span>Account 1 private key derivation failed</span>"</span></span> print</span>(</span>"</span>✅ Private key derivation from department xprv successful</span>"</span>)</span></span> </span> except</span> Exception</span> as</span> e</span>:</span></span> logger</span>.</span>error</span>(</span>"</span>System error: </span>%s</span>"</span>,</span> e</span>,</span> exc_info</span>=</span>True</span>)</span></span></code></pre> run script:</p> pip</span> install</span> bip32utils</span> eth_account</span></span> </span> python</span> stms.py</span></span></code></pre> output：</p> </p> Security Considerations</h2> For treasury managers, hierarchical deterministic wallet management is more convenient, but it requires additional consideration of protective measures for the master key, such as schemes for splitting and storing mnemonic phrases or master keys.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Wallet Capabilities for Account Abstraction 2025-03-01T00:00:00+00:00 Abstract</h2> EIP-5792</a> defines a baseline JSON-RPC API for a communication between wallets and dapps, and provides an ability to extend the base protocol with "capabilities".</p> This proposal defines a set of "capabilities" the wallets may want to implement in order to provide a comprehensive support for Account Abstraction (AA).</p> These "capabilities" enable passing any data that may be required when using a Paymaster contract, allows limiting the time range during which the UserOperation is considered valid, provides a way for the dApp to manually control the semi-abstracted nonce and AA-specific gas limits of the UserOp, and even allow the dApp to take part in selecting the EIP-7702</a> account implementation.</p> Motivation</h2> ERC-4337</a> introduced Account Abstraction, enabling Smart Contract Accounts to function as first-class citizens in Ethereum. However, while ERC-4337</a> and ERC-7769</a> define a low-level RPC API for Account Abstraction, they do not specify a way for advanced AA-aware dApps to communicate their supported features and parameters to the advanced AA Wallet Applications.</p> This ERC addresses the issue by defining a structured set of capabilities tailored for AA-aware dApps and Wallet Applications.</p> It utilises the EIP-5792</a> wallet capability model to express some of the critical aspects of AA, ensuring dApps can seamlessly adapt to different AA Wallets without requiring custom solutions.</p> Specification</h2> All actions in Account Abstraction within the context of EIP-5792 must be done on a single chain and atomically.</p> We define the following list of new "capabilities" which together cover many features necessary for Account Abstraction. Note that use of Paymasters managed by a "paymaster web service" is described in ERC-7677</a>.</p> Create EIP-7702</a> Authorization Capability</h3> This capability is designed to be used with EIP-7702</a> and requests the Wallet Application to provide an EIP-7702 authorization tuple for the specified address as part of the AA transaction.</p> Identifier:</p> eip7702Auth</code></p> Interface:</p> type</span> SetCodeForEOACapabilityParams</span> =</span> Record</span><</span></span> {</span></span> account</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span> //</span> EOA address</span></span> delegation</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span> //</span> delegation address</span></span> }</span></span> ></span></span></code></pre> Supporting Wallet Applications MUST generate an EIP-7702 compatible transaction that sets a code of the account</code> EOA address to the code of delegation</code> specified in the request.</p> Static Paymaster Configuration Capability</h3> The purpose of this capability is allowing applications to integrate with Paymasters that do not require the Wallet Application to resolve any dynamic configuration.</p> The application may hard-code or resolve these parameters first and pass them with this capability.</p> Identifier:</p> staticPaymasterConfiguration</code></p> Interface:</p> type</span> StaticPaymasterConfigurationCapabilityParams</span> =</span> Record</span><</span></span> {</span></span> paymaster</span>:</span> string</span>;</span></span> paymasterData</span>:</span> string</span>;</span></span> paymasterValidationGasLimit</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>;</span></span> paymasterPostOpGasLimit</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>;</span></span> }</span></span> ></span>;</span></span></code></pre>Validity Time Range Capability</h3> The purpose of this capability is allowing the applications to explicitly specify the time range during which the requested operations will be valid after signing.</p> Identifier:</p> validityTimeRange</code></p> Interface:</p> type</span> ValidityTimeRangeCapabilityParams</span> =</span> Record</span><</span></span> {</span></span> validAfter</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span> //</span> operation valid only after this timestamp, in seconds</span></span> validUntil</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span> //</span> operation valid only before this timestamp, in seconds</span></span> }</span></span> ></span></span></code></pre> The Wallet Application MUST verify the time range [validAfter</code>..validUntil</code>] is valid and present it to the user in a human-readable way for confirmation as part of the transaction information.</p> The Smart Contract Account MUST specify the time range [validAfter</code>..validUntil</code>] as the transaction validity range.</p> Multidimensional Nonce Capability</h3> The purpose of this capability is allowing the applications to explicitly specify the components of the semi-abstracted nonce as defined in ERC-4337</a>.</p> Identifier:</p> multiDimensionalNonce</code></p> Interface:</p> type</span> MultiDimensionalNonceCapabilityParams</span> =</span> Record</span><</span></span> {</span></span> nonceKey</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span></span> nonceSequence</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span></span> }</span></span> ></span></span></code></pre> For Smart Contract Accounts that support multidimensional nonce values, the wallet must specify these parameters during the actual on-chain execution of the batch.</p> Account Abstraction Gas Parameters Override Capability</h3> The purpose of this capability is allowing the applications to override the Wallet Application's suggested values for all gas-related parameters.</p> This capability provides very low-level access to the underlying Account Abstraction protocol and should only be used by applications closely coupled to a specific version of a specific protocol. It may also prove useful in the context of development and debugging.</p> It is generally recommended that production dapps rely on higher-level features of Wallet Applications instead.</p> Identifier:</p> accountAbstractionGasParamsOverride</code></p> Interface:</p> type</span> AAGasParamsOverrideCapabilityParams</span> =</span> Record</span><</span></span> {</span></span> preVerificationGas</span>?</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span></span> verificationGasLimit</span>?</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span></span> callGasLimit</span>?</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span></span> paymasterVerificationGasLimit</span>?</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span></span> paymasterPostOpGasLimit</span>?</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span></span> maxFeePerGas</span>?</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span></span> maxPriorityFeePerGas</span>?</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span></span> }</span></span> ></span></span></code></pre> Notice that all fields in the AAGasParamsOverrideCapabilityParams</code> are optional. Only the values that callers want to override must be provided.</p> Wallet Applications should warn the users about the overrides being supplied by the call and use these values instead.</p> Wallet Applications may choose to reject calls with conflicting configurations.</p> Rationale</h2> Security Considerations</h2> eip7702Auth</code></h3> This is by far the most sensitive capability in the document. There is no limit to the damage that can be done by signing the wrong capability.</p> Wallet Applications MUST take extreme care when working with EIP-7702</a>.</p> Wallet Applications MUST maintain a strict shortlist of well-known and publicly audited Smart Contract Account implementations that are acceptable as delegation</code>.</p> Authorization is an extremely sensitive operation and any vulnerability or malicious code in delegation</code> will result in complete draining of the account</code>.</p> staticPaymasterConfiguration</code></h3> This capability has an opportunity to provide the paymaster</code> and paymasterData</code> values for the call. Incorrect or malicious values can be an attack vector. For example, a Paymaster contract may hold approvals for ERC-20</a> tokens which may be drained this way.</p> The Wallet Applications MUST make sure the provided values correspond to user intent. Fundamentally, this is not very different to how regular transactions' calldata</code> must be verified.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Cancelation for ERC-7540 Tokenized Vaults 2025-02-18T00:00:00+00:00 Abstract</h2> The following standard extends ERC-7540</a> by adding support for asynchronous cancelation flows.</p> New methods are added to asynchronously cancel a deposit or redeem Request, view the status of the cancelation Request, and claim the assets or shares as a result of the cancelation Request.</p> Motivation</h2> Shares or assets locked for Requests can be stuck in the Pending state. For some use cases, such as redeeming from a pool of long-dated real-world assets, this can take a considerable amount of time.</p> This standard expands the scope of Asynchronous ERC-7540 Vaults by adding cancelation support.</p> Specification</h2> 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.</p> Definitions</h3> The existing definitions from ERC-7540</a> apply.</p> Cancelation Lifecycle</h3> After submission, cancelation Requests go through Pending, Claimable, and Claimed stages. An example lifecycle for a deposit cancelation Request is visualized in the table below.</p> State</strong></th> User</strong></th> Vault</strong></th></tr></thead> Pending</td> cancelDepositRequest(requestId, controller)</code></td> pendingCancelDepositRequest[controller] = true</code></td></tr> Claimable</td> </td> Internal cancelation fulfillment</em>: pendingCancelDepositRequest[controller] = false</code>; claimableCancelDepositRequest[controller] = assets</code></td></tr> Claimed</td> claimCancelDepositRequest(requestId, receiver, controller)</code></td> claimableDepositRequest[controller] -= assets</code>; asset.balanceOf[receiver] += assets</code></td></tr> </tbody></table> pendingCancelDepositRequest</code> and claimableCancelDepositRequest</code> are defined in the Methods</a> section.</p> Requests MUST NOT skip or otherwise short-circuit the Claim state. In other words, to initiate and claim a Request, a user MUST call both cancel and the corresponding Claim function separately, even in the same block. Vaults MUST NOT "push" tokens onto the user after a Request, users MUST "pull" the tokens via the Claim function.</p> Requests MAY skip straight from the Pending to the Claimable stage, in the case of synchronous cancelation flows.</p> While a deposit cancelation Request is Pending, new deposit Requests are blocked. Likewise, while a redeem cancelation Request is Pending, new redeem Requests are blocked.</p> Methods</h3> cancelDepositRequest</code></h4> Submits a Request for asynchronous deposit cancelation. This places the Request in Pending state, with a corresponding increase in pendingCancelDepositRequest</code> for the full amount of the pending deposit Request.</p> When the cancelation is Pending, new deposit Requests are blocked and requestDeposit</code> MUST revert.</p> When the cancelation is Claimable, claimableCancelDepositRequest</code> will be increased for the controller</code>. claimCancelDepositRequest</code> can subsequently be called by controller</code> to receive assets</code>. A Request MAY transition straight to Claimable state but MUST NOT skip the Claimable state.</p> controller</code> MUST equal msg.sender</code> unless the controller</code> has approved the msg.sender</code> as an operator.</p> MUST emit the CancelDepositRequest</code> event.</p> -</span> n</span>ame</span>:</span> c</span>ancelDepositRequest</span></span> t</span>ype</span>:</span> f</span>unction</span></span> s</span>tateMutability</span>:</span> n</span>onpayable</span></span> </span> i</span>nputs</span>:</span></span> -</span> n</span>ame</span>:</span> r</span>equestId</span></span> t</span>ype</span>:</span> u</span>int256</span></span> -</span> n</span>ame</span>:</span> c</span>ontroller</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> o</span>utputs</span>:</span></span></code></pre>pendingCancelDepositRequest</code></h4> Whether the given requestId</code> and controller</code> have a pending deposit cancelation Request.</p> MUST NOT show any variations depending on the caller.</p> MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</p> -</span> n</span>ame</span>:</span> p</span>endingCancelDepositRequest</span></span> t</span>ype</span>:</span> f</span>unction</span></span> s</span>tateMutability</span>:</span> v</span>iew</span></span> </span> i</span>nputs</span>:</span></span> -</span> n</span>ame</span>:</span> r</span>equestId</span></span> t</span>ype</span>:</span> u</span>int256</span></span> -</span> n</span>ame</span>:</span> c</span>ontroller</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> </span> o</span>utputs</span>:</span></span> -</span> n</span>ame</span>:</span> i</span>sPending</span></span> t</span>ype</span>:</span> b</span>ool</span></span></code></pre>claimableCancelDepositRequest</code></h4> The amount of assets</code> in Claimable cancelation state for the controller</code> to claim.</p> MUST NOT show any variations depending on the caller.</p> MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</p> -</span> n</span>ame</span>:</span> c</span>laimableCancelDepositRequest</span></span> t</span>ype</span>:</span> f</span>unction</span></span> s</span>tateMutability</span>:</span> v</span>iew</span></span> </span> i</span>nputs</span>:</span></span> -</span> n</span>ame</span>:</span> r</span>equestId</span></span> t</span>ype</span>:</span> u</span>int256</span></span> -</span> n</span>ame</span>:</span> c</span>ontroller</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> </span> o</span>utputs</span>:</span></span> -</span> n</span>ame</span>:</span> a</span>ssets</span></span> t</span>ype</span>:</span> u</span>int256</span></span></code></pre>claimCancelDepositRequest</code></h4> Claims the deposit cancelation Request with requestId</code> and controller</code>.</p> Transfers assets</code> to receiver</code>.</p> controller</code> MUST equal msg.sender</code> unless the controller</code> has approved the msg.sender</code> as an operator.</p> MUST emit the ClaimCancelDepositRequest</code> event.</p> -</span> n</span>ame</span>:</span> c</span>laimCancelDepositRequest</span></span> t</span>ype</span>:</span> f</span>unction</span></span> s</span>tateMutability</span>:</span> n</span>onpayable</span></span> </span> i</span>nputs</span>:</span></span> -</span> n</span>ame</span>:</span> r</span>equestId</span></span> t</span>ype</span>:</span> u</span>int256</span></span> -</span> n</span>ame</span>:</span> r</span>eceiver</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> -</span> n</span>ame</span>:</span> c</span>ontroller</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> o</span>utputs</span>:</span></span></code></pre>cancelRedeemRequest</code></h4> Submits a Request for asynchronous redeem cancelation. This places the Request in Pending state, with a corresponding increase in pendingCancelRedeemRequest</code> for the full amount of the pending redeem Request.</p> When the cancelation is Pending, new redeem Requests are blocked and requestRedeem</code> MUST revert.</p> When the cancelation is Claimable, claimableCancelRedeemRequest</code> will be increased for the controller</code>. claimCancelRedeemRequest</code> can subsequently be called by controller</code> to receive shares</code>. A Request MAY transition straight to Claimable state but MUST NOT skip the Claimable state.</p> controller</code> MUST equal msg.sender</code> unless the controller</code> has approved the msg.sender</code> as an operator.</p> MUST emit the CancelRedeemRequest</code> event.</p> -</span> n</span>ame</span>:</span> c</span>ancelRedeemRequest</span></span> t</span>ype</span>:</span> f</span>unction</span></span> s</span>tateMutability</span>:</span> n</span>onpayable</span></span> </span> i</span>nputs</span>:</span></span> -</span> n</span>ame</span>:</span> r</span>equestId</span></span> t</span>ype</span>:</span> u</span>int256</span></span> -</span> n</span>ame</span>:</span> c</span>ontroller</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> o</span>utputs</span>:</span></span></code></pre>pendingCancelRedeemRequest</code></h4> Whether the given requestId</code> and controller</code> have a pending redeem cancelation Request.</p> MUST NOT show any variations depending on the caller.</p> MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</p> -</span> n</span>ame</span>:</span> p</span>endingCancelRedeemRequest</span></span> t</span>ype</span>:</span> f</span>unction</span></span> s</span>tateMutability</span>:</span> v</span>iew</span></span> </span> i</span>nputs</span>:</span></span> -</span> n</span>ame</span>:</span> r</span>equestId</span></span> t</span>ype</span>:</span> u</span>int256</span></span> -</span> n</span>ame</span>:</span> c</span>ontroller</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> </span> o</span>utputs</span>:</span></span> -</span> n</span>ame</span>:</span> i</span>sPending</span></span> t</span>ype</span>:</span> b</span>ool</span></span></code></pre>claimableCancelRedeemRequest</code></h4> The amount of shares</code> in Claimable cancelation state for the controller</code> to claim.</p> MUST NOT show any variations depending on the caller.</p> MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</p> -</span> n</span>ame</span>:</span> c</span>laimableCancelRedeemRequest</span></span> t</span>ype</span>:</span> f</span>unction</span></span> s</span>tateMutability</span>:</span> v</span>iew</span></span> </span> i</span>nputs</span>:</span></span> -</span> n</span>ame</span>:</span> r</span>equestId</span></span> t</span>ype</span>:</span> u</span>int256</span></span> -</span> n</span>ame</span>:</span> c</span>ontroller</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> </span> o</span>utputs</span>:</span></span> -</span> n</span>ame</span>:</span> s</span>hares</span></span> t</span>ype</span>:</span> u</span>int256</span></span></code></pre>claimCancelRedeemRequest</code></h4> Claims the redeem cancelation Request with requestId</code> and controller</code>.</p> Transfers assets</code> to receiver</code>.</p> controller</code> MUST equal msg.sender</code> unless the controller</code> has approved the msg.sender</code> as an operator.</p> MUST emit the ClaimCancelRedeemRequest</code> event.</p> -</span> n</span>ame</span>:</span> c</span>laimCancelRedeemRequest</span></span> t</span>ype</span>:</span> f</span>unction</span></span> s</span>tateMutability</span>:</span> n</span>onpayable</span></span> </span> i</span>nputs</span>:</span></span> -</span> n</span>ame</span>:</span> r</span>equestId</span></span> t</span>ype</span>:</span> u</span>int256</span></span> -</span> n</span>ame</span>:</span> r</span>eceiver</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> -</span> n</span>ame</span>:</span> o</span>wner</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> o</span>utputs</span>:</span></span></code></pre>Events</h3> CancelDepositRequest</code></h4> controller</code> has requested cancelation of their deposit Request with request ID requestId</code>. sender</code> is the caller of the cancelDepositRequest</code> which may not be equal to the controller</code>.</p> MUST be emitted when a deposit cancelation Request is submitted using the cancelDepositRequest</code> method.</p> -</span> n</span>ame</span>:</span> C</span>ancelDepositRequest</span></span> t</span>ype</span>:</span> e</span>vent</span></span> </span> i</span>nputs</span>:</span></span> -</span> n</span>ame</span>:</span> c</span>ontroller</span></span> i</span>ndexed</span>:</span> true</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> -</span> n</span>ame</span>:</span> r</span>equestId</span></span> i</span>ndexed</span>:</span> true</span></span> t</span>ype</span>:</span> u</span>int256</span></span> -</span> n</span>ame</span>:</span> s</span>ender</span></span> i</span>ndexed</span>:</span> false</span></span> t</span>ype</span>:</span> a</span>ddress</span></span></code></pre>CancelDepositClaim</code></h4> controller</code> has claimed their deposit cancelation Request with request ID requestId</code>. receiver</code> is the destination of the assets</code>. sender</code> is the caller of the claimCancelDepositRequest</code> which may not be equal to the controller</code>.</p> MUST be emitted when a deposit cancelation Request is submitted using the claimCancelDepositRequest</code> method.</p> -</span> n</span>ame</span>:</span> C</span>ancelDepositClaim</span></span> t</span>ype</span>:</span> e</span>vent</span></span> </span> i</span>nputs</span>:</span></span> -</span> n</span>ame</span>:</span> c</span>ontroller</span></span> i</span>ndexed</span>:</span> true</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> -</span> n</span>ame</span>:</span> r</span>eceiver</span></span> i</span>ndexed</span>:</span> true</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> -</span> n</span>ame</span>:</span> r</span>equestId</span></span> i</span>ndexed</span>:</span> true</span></span> t</span>ype</span>:</span> u</span>int256</span></span> -</span> n</span>ame</span>:</span> s</span>ender</span></span> i</span>ndexed</span>:</span> false</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> -</span> n</span>ame</span>:</span> a</span>ssets</span></span> i</span>ndexed</span>:</span> false</span></span> t</span>ype</span>:</span> u</span>int256</span></span></code></pre>CancelRedeemRequest</code></h4> controller</code> has requested cancelation of their deposit Request with request ID requestId</code>. sender</code> is the caller of the cancelRedeemRequest</code> which may not be equal to the controller</code>.</p> MUST be emitted when a redeem cancelation Request is submitted using the cancelRedeemRequest</code> method.</p> -</span> n</span>ame</span>:</span> C</span>ancelRedeemRequest</span></span> t</span>ype</span>:</span> e</span>vent</span></span> </span> i</span>nputs</span>:</span></span> -</span> n</span>ame</span>:</span> c</span>ontroller</span></span> i</span>ndexed</span>:</span> true</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> -</span> n</span>ame</span>:</span> r</span>equestId</span></span> i</span>ndexed</span>:</span> true</span></span> t</span>ype</span>:</span> u</span>int256</span></span> -</span> n</span>ame</span>:</span> s</span>ender</span></span> i</span>ndexed</span>:</span> false</span></span> t</span>ype</span>:</span> a</span>ddress</span></span></code></pre>CancelRedeemClaim</code></h4> controller</code> has claimed their redeem cancelation Request with request ID requestId</code>. receiver</code> is the destination of the shares</code>. sender</code> is the caller of the claimCancelRedeemRequest</code> which may not be equal to the controller</code>.</p> MUST be emitted when a redeem cancelation Request is submitted using the claimCancelRedeemRequest</code> method.</p> -</span> n</span>ame</span>:</span> C</span>ancelRedeemClaim</span></span> t</span>ype</span>:</span> e</span>vent</span></span> </span> i</span>nputs</span>:</span></span> -</span> n</span>ame</span>:</span> c</span>ontroller</span></span> i</span>ndexed</span>:</span> true</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> -</span> n</span>ame</span>:</span> r</span>eceiver</span></span> i</span>ndexed</span>:</span> true</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> -</span> n</span>ame</span>:</span> r</span>equestId</span></span> i</span>ndexed</span>:</span> true</span></span> t</span>ype</span>:</span> u</span>int256</span></span> -</span> n</span>ame</span>:</span> s</span>ender</span></span> i</span>ndexed</span>:</span> false</span></span> t</span>ype</span>:</span> a</span>ddress</span></span> -</span> n</span>ame</span>:</span> s</span>hares</span></span> i</span>ndexed</span>:</span> false</span></span> t</span>ype</span>:</span> u</span>int256</span></span></code></pre>ERC-165</a> support</h3> Smart contracts implementing this Vault standard MUST implement the ERC-165</a> supportsInterface</code> function.</p> Asynchronous deposit Vaults with cancelation support MUST return the constant value true</code> if 0x8bf840e3</code> is passed through the interfaceID</code> argument.</p> Asynchronous redemption Vaults with cancelation support MUST return the constant value true</code> if 0xe76cffc7</code> is passed through the interfaceID</code> argument.</p> Rationale</h2> Blocking Requests during Cancelation</h3> When cancelDepositRequest</code> is called by a controller</code>, new deposit Requests are blocked for this controller</code>, and the equivalent applies to the redeem flow.</p> This requirement simplifies the possible states of vaults implementing asynchronous cancelation flows.</p> The alternative would create possible states where a cancelation is pending and a new deposit Request is triggered, leading to the current state being complex to read for integrators.</p> Mandated Support for ERC-165</a></h3> Implementing support for ERC-165</a> is mandated because of the optionality of flows as defined in ERC-7540</a>. Integrations can use the supportsInterface</code> method to check whether a vault is fully asynchronous, partially asynchronous, or fully synchronous (for which it is just following the ERC-4626</a>), and use a single contract to support all cases.</p> Backwards Compatibility</h2> The interface is fully backwards compatible with ERC-7540</a>.</p> Security Considerations</h2> Existing security considerations from ERC-7540</a> apply.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p> Crosschain Broadcaster 2025-02-18T00:00:00+00:00 Abstract</h2> This ERC defines a protocol for cross-rollup messaging using state commitments. Users can broadcast messages on a source chain, and those messages can be verified on any other chain that shares a common ancestor with the source chain.</p> A state commitment is a bytes32</code> hash that commits to a chain's state (e.g., block hash or state root). The protocol supports different types of state commitments depending on what the rollup commits to its parent chain. Block hashes are the recommended state commitment, but state roots or other commitments may be used, such as batch hashes (since some rollups don't commit single blocks, but batches of blocks instead).</p> Each chain deploys a singleton Receiver and Broadcaster contract. Broadcasters store messages; Receivers verify the Broadcasters' state on remote chains. To do this, a Receiver first verifies a chain of state commitment proofs to recover a remote state commitment, then verifies the Broadcaster's state at that commitment.</p> Critically, the logic for verifying state commitment proofs is not hardcoded in the Receiver. Instead, it delegates this to a user specified list of StateProver contracts. Each StateProver defines how to verify a state commitment proof for a specific home chain to recover the state commitment of a specific target chain. Because the state commitment schemes and layouts of rollup contracts can change over time, the state commitment proof verification process itself must also be upgradeable—hence the StateProvers are upgradeable. This flexible, upgradeable proof verification model is the core contribution of this standard.</p> Motivation</h2> The Ethereum ecosystem is experiencing a rapid growth in the number of rollup chains. As the number of chains grows, the experience becomes more fragmented for users, creating a need for trustless "interop" between rollup chains. These rollup chains, hosted on different rollup stacks, have heterogeneous properties, and as yet there does not exist a simple, trustless, unified mechanism for sending messages between these diverse chains.</p> Many classes of applications could benefit from a unified system for broadcasting messages across chains. Some examples include:</p> Intent-Based Protocols:</strong> These protocols enable "fillers" to quickly execute crosschain actions on behalf of users, followed by slower, trustless messaging to settle these actions. However, due to the lack of a simple, unified interface for sending settlement messages, intent protocols often develop proprietary methods. This raises adoption barriers for fillers, integrators, and new protocols. A pluggable, standardized messaging solution that works across rollup stacks would allow developers and standards authors to focus on other components of the intent stack, such as fulfillment constraints, order formats, and escrow.</li> Governance of multichain apps:</strong> Multichain apps often have a single chain where core governance contracts are located. A standardized broadcast messaging system simplifies the dissemination of proposal results to all instances of a multichain app.</li> Multichain Oracles:</strong> Some classes of oracles may benefit from being able to post their data to a single chain, while having that same data easily accessible across many other chains.</li> </ul> Specification</h2> 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.</p> Compatibility Requirements</h3> Chains must satisfy the following conditions to be compatible with the system:</p> Must store finalized state commitments on the parent chain</li> Must store parent chain state commitments in child chain state</li> Must be EVM equivalent with L1. StateProvers are deployed as copies on many chains, so need to behave the same on all those chains</li> </ul> Constants</h3> uint256</span> constant</span> STATE_PROVER_POINTER_SLOT </span>=</span> uint256</span>(</span>keccak256</span>(</span>"eip7888.pointer.slot"</span>)</span>)</span> -</span> 1</span>;</span></span></code></pre>State Commitments</h3> A state commitment</strong> is a bytes32</code> hash that commits to the state of a chain at a particular point in time. This commitment is produced by the rollup and serves as a cryptographic representation of the chain's state. The most common state commitments are:</p> Block hash</strong>: A hash of the block header, which is the recommended state commitment for most implementations</li> State root</strong>: The root of the state tree (e.g., Merkle-Patricia Trie) or other state commitment structure</li> Batch hash</strong>: A hash of a batch of blocks, used by some rollups that commit batches of blocks rather than individual blocks</li> </ul> The choice of state commitment depends on what the rollup commits to its parent chain. Different rollups may use different state commitments, and the StateProver is responsible for verifying proofs that recover these commitments from the parent chain's state.</p> Broadcaster</h3> The Broadcaster is responsible for storing messages in state to be read by Receivers on other chains. Callers of the Broadcaster are known as Publishers. The Broadcaster stores only 32 byte messages.</p> The Broadcaster does not accept duplicate messages from the same publisher.</p> Figure 1: A Publisher at address 0x4 calling a Broadcaster at address 0x3</em> </div> ///</span> @notice</span> Broadcasts messages to receivers.</span></span> interface</span> IBroadcaster</span> {</span></span> ///</span> @notice</span> Emitted when a message is broadcast.</span></span> ///</span> @param</span> message</span> The message that was broadcast by the publisher.</span></span> ///</span> @param</span> publisher</span> The address of the publisher.</span></span> event</span> MessageBroadcast</span>(</span>bytes32</span> indexed</span> message</span>, </span>address</span> indexed</span> publisher</span>)</span>;</span></span> </span> ///</span> @notice</span> Broadcasts a message. Callers are called "publishers".</span></span> ///</span> @dev</span> MUST revert if the publisher has already broadcast the message.</span></span> ///</span> MUST emit MessageBroadcast.</span></span> ///</span> MUST store block.timestamp in slot keccak(message, msg.sender).</span></span> ///</span> MAY use additional transmission mechanisms (e.g., child-to-parent native bridges) to make messages visible.</span></span> ///</span> @param</span> message</span> The message to broadcast.</span></span> function</span> broadcastMessage</span>(</span>bytes32</span> message</span>)</span> external</span>;</span></span> }</span></span></code></pre>StateProvers</h3> StateProvers prove a unidirectional link between two chains that have direct access to each other's finalized state commitments. The chains in this link are called the home chain</strong> and the target chain</strong>. StateProvers are responsible for verifying state commitment proofs to prove the existence of finalized target state commitments in the state of the home chain. Block hashes are the recommended state commitment, but implementations may use other commitments (e.g., state roots, batch hashes).</p> Since the StateProvers are unidirectional, each chain needs to have two:</p> One whose home is the child chain and target is the parent chain.</li> One whose home is the parent chain and target is the child chain.</li> </ul> StateProvers MUST ensure that they will have the same deployed code hash on all chains.</p> Figure 2: A StateProver with home chain L and target chain M</em> </div> ///</span> @notice</span> The IStateProver is responsible for retrieving the state commitment of its target chain given its home chain's state.</span></span> ///</span> The home chain's state is given either by a state commitment and proof, or by the StateProver executing on the home chain.</span></span> ///</span> A single home and target chain are fixed by the logic of this contract.</span></span> interface</span> IStateProver</span> {</span></span> ///</span> @notice</span> Verify the state commitment of the target chain given the state commitment of the home chain and a proof.</span></span> ///</span> @dev</span> MUST revert if called on the home chain.</span></span> ///</span> MUST revert if the input is invalid or the input is not sufficient to determine the state commitment.</span></span> ///</span> MUST return a target chain state commitment.</span></span> ///</span> MUST be pure, with 1 exception: MAY read address(this).code.</span></span> ///</span> @param</span> homeStateCommitment</span> The state commitment of the home chain.</span></span> ///</span> @param</span> input</span> Any necessary input to determine a target chain state commitment from the home chain state commitment.</span></span> ///</span> @return</span> targetStateCommitment</span> The state commitment of the target chain.</span></span> function</span> verifyTargetStateCommitment</span>(</span>bytes32</span> homeStateCommitment</span>,</span> bytes</span> calldata</span> input</span>)</span></span> external</span></span> view</span></span> returns</span> (</span>bytes32</span> targetStateCommitment</span>)</span>;</span></span> </span> ///</span> @notice</span> Get the state commitment of the target chain. Does so by directly accessing state on the home chain.</span></span> ///</span> @dev</span> MUST revert if not called on the home chain.</span></span> ///</span> MUST revert if the target chain's state commitment cannot be determined.</span></span> ///</span> MUST return a target chain state commitment.</span></span> ///</span> SHOULD use the input to determine a specific state commitment to return. (e.g. input could be a block number)</span></span> ///</span> SHOULD NOT read from its own storage. This contract is not meant to have state.</span></span> ///</span> MAY make external calls.</span></span> ///</span> @param</span> input</span> Any necessary input to fetch a target chain state commitment.</span></span> ///</span> @return</span> targetStateCommitment</span> The state commitment of the target chain.</span></span> function</span> getTargetStateCommitment</span>(</span>bytes</span> calldata</span> input</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span> targetStateCommitment</span>)</span>;</span></span> </span> ///</span> @notice</span> Verify a storage slot given a target chain state commitment and a proof.</span></span> ///</span> @dev</span> This function MUST NOT assume it is being called on the home chain.</span></span> ///</span> MUST revert if the input is invalid or the input is not sufficient to determine a storage slot and its value.</span></span> ///</span> MUST return a storage slot and its value on the target chain.</span></span> ///</span> MUST be pure, with 1 exception: MAY read address(this).code.</span></span> ///</span> While messages MUST be stored in storage slots, alternative reading mechanisms may be used in some cases.</span></span> ///</span> @param</span> targetStateCommitment</span> The state commitment of the target chain.</span></span> ///</span> @param</span> input</span> Any necessary input to determine a single storage slot and its value.</span></span> ///</span> @return</span> account</span> The address of the account on the target chain.</span></span> ///</span> @return</span> slot</span> The storage slot of the account on the target chain.</span></span> ///</span> @return</span> value</span> The value of the storage slot.</span></span> function</span> verifyStorageSlot</span>(</span>bytes32</span> targetStateCommitment</span>,</span> bytes</span> calldata</span> input</span>)</span></span> external</span></span> view</span></span> returns</span> (</span>address</span> account</span>,</span> uint256</span> slot</span>,</span> bytes32</span> value</span>)</span>;</span></span> </span> ///</span> @notice</span> The version of the state commitment prover.</span></span> ///</span> @dev</span> MUST be pure, with 1 exception: MAY read address(this).code.</span></span> function</span> version</span>(</span>)</span> external</span> pure</span> returns</span> (</span>uint256</span>)</span>;</span></span> }</span></span></code></pre>StateProverPointers</h3> StateProvers can be used to get or verify target state commitments, however since their verification logic is immutable, changes to the structure of the home or target chain can break the logic in these Provers. A StateProverPointer is a Pointer to a StateProver which can be updated if proving logic needs to change.</p> StateProverPointers are used to reference StateProvers as opposed to referencing Provers directly. To that end, wherever a StateProver is deployed a StateProverPointer needs to be deployed to reference it.</p> StateProverPointers allow a permissioned party to update the Prover reference within the Pointer. Choosing which party should have the permission to update the Prover reference should be carefully considered. The general rule is that if an update to the target or home chain could break the logic in the current Prover, then the party, or mechanism, able to make that update should also be given permission to update the Prover. See Security Considerations</a> for more information on StateProverPointer ownership and updates.</p> When updating a StateProverPointer to point to a new StateProver implementation:</p> The home and target chain of the new StateProver MUST be identical to the previous StateProver.</li> The new StateProver MUST have a higher version than the previous StateProver.</li> </ul> StateProverPointers MUST store the code hash of the StateProver implementation in slot STATE_PROVER_POINTER_SLOT</code>.</p> Figure 3: A StateProverPointer at address 0xA pointing to a StateProver with home chain L and target chain M</em> </div> ///</span> @title</span> IStateProverPointer</span></span> ///</span> @notice</span> Keeps the code hash of the latest version of a state commitment prover.</span></span> ///</span> MUST store the code hash in storage slot STATE_PROVER_POINTER_SLOT.</span></span> ///</span> Different versions of the prover MUST have the same home and target chains.</span></span> ///</span> If the pointer's prover is updated, the new prover MUST have a higher IStateProver::version() than the old one.</span></span> ///</span> These pointers are always referred to by their address on their home chain.</span></span> interface</span> IStateProverPointer</span> {</span></span> ///</span> @notice</span> Return the code hash of the latest version of the prover.</span></span> function</span> implementationCodeHash</span>(</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span> </span> ///</span> @notice</span> Return the address of the latest version of the prover on the home chain.</span></span> function</span> implementationAddress</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span> }</span></span></code></pre>Routes</h3> A route is a relative path from a Receiver on a local chain to a remote chain. It is constructed of many single degree links dictated by StateProverPointers. Receivers use the StateProvers that the Pointers reference to verify a series of proofs to obtain the remote chain's state commitment. A route works with any state commitment scheme (block hashes, state roots, etc.) and is defined by the list of Pointer addresses on their home chains.</p> A valid route MUST obey the following:</p> Home chain of the route[0]</code> Pointer must equal the local chain</li> Target chain of the route[i]</code> Pointer must equal home chain of the route[i+1]</code> Pointer</li> </ul> Figure 4: A route [0xA, 0xB, 0xC] from chain L to chain R Chain L is an L2, Chain M is Ethereum Mainnet, Chain P is another L2, and Chain R is an L3 settling to Chain P</em> </div> Identifiers</h3> Accounts on remote chains are identified by the route taken from the local chain plus the address on the remote chain. The Pointer addresses used in the route, along with the remote address, are cumulatively keccak256 hashed together to form a Remote Account ID</strong>.</p> In this way any address on a remote chain, including Pointers and Broadcasters, can be uniquely identified relative to the local chain by their Remote Account ID.</p> ID's depend on a route and are therefore always relative</em> to a local chain. In other words, the same account on a given chain will have different ID's depending on the route from the local chain.</p> The Remote Account ID is defined as accumulator([...route, remoteAddress])</code></p> function</span> accumulator</span>(</span>address</span>[</span>]</span> memory</span> elems</span>)</span> pure</span> returns</span> (</span>bytes32</span> acc</span>)</span> {</span></span> for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> elems</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span> acc </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>acc</span>,</span> elems</span>[</span>i</span>]</span>)</span>)</span>;</span></span> }</span></span> }</span></span></code></pre> In Figure 4:</p> The Remote Account ID of Broadcaster at 0x3</code> is accumulator([0xA, 0xB, 0xC, 0x3])</code></li> The Remote Account ID of StateProverPointer 0xC</code> is accumulator([0xA, 0xB, 0xC])</code>.</li> </ul> StateProverCopies</h3> StateProverCopies are exact copies of StateProvers deployed on non-home chains. When a StateProver code hash is de-referenced from a Pointer, a copy of the StateProver may be used to execute its logic. Since the Pointer references the prover by code hash, a local copy of the Prover can be deployed and used to execute specific proving logic. The Receiver caches a map of mapping(bytes32 stateProverPointerId => IStateProver stateProverCopy)</code> to keep track of StateProverCopies.</p> Figure 5: A StateProverCopy of StateProver M->P on chain L</em> </div> Receiver</h3> The Receiver is responsible for verifying 32 byte messages deposited in Broadcasters on other chains. The caller provides the Receiver with a route to the remote account and proof to verify the route.</p> Figure 6: Example of a Receiver reading a message from a Broadcaster on chain R</em> </div> The calls in Figure 6 perform the following operations:</p> Subscriber calls IReceiver::verifyBroadcastMessage</code>, passing route [0xA, 0xB, 0xC]</code>, proof data, message, publisher.</li> Receiver calls IStateProverPointer(0xA)::implementationAddress</code> to get the address of StateProver L->M</li> Receiver calls IStateProver(Prover L->M)::getTargetState</code>, passing input given by Subscriber to get a state commitment of chain M.</li> Receiver calls IStateProver(Prover Copy M->P)::verifyTargetState</code>, passing chain M's state commitment and proof data by Subscriber to get a state commitment of chain P.</li> Receiver calls IStateProver(Prover Copy P->R)::verifyTargetState</code>, passing chain P's state commitment and proof data by Subscriber to get a state commitment of chain R.</li> Finally, Receiver calls IStateProver(Prover Copy P->R)::verifyStateValue</code>, passing input given by Subscriber to get a storage slot from the Broadcaster. The Receiver returns the Broadcaster's Remote Account ID and the message's timestamp to Subscriber.</li> </ol> ///</span> @notice</span> Reads messages from a broadcaster.</span></span> interface</span> IReceiver</span> {</span></span> ///</span> @notice</span> Arguments required to read state of an account on a remote chain.</span></span> ///</span> @dev</span> The proof is always for a single storage slot. If the proof is for multiple slots the IReceiver MUST revert.</span></span> ///</span> The proof format depends on the state commitment scheme used by the StateProver (e.g., storage proofs).</span></span> ///</span> While messages MUST be stored in storage slots, alternative reading mechanisms may be used in some cases.</span></span> ///</span> @param</span> route</span> The home chain addresses of the StateProverPointers along the route to the remote chain.</span></span> ///</span> @param</span> scpInputs</span> The inputs to the StateProver / StateProverCopies.</span></span> ///</span> @param</span> proof</span> Proof passed to the last StateProver / StateProverCopy</span></span> ///</span> to verify a storage slot given a target state commitment.</span></span> struct</span> RemoteReadArgs</span> {</span></span> address</span>[</span>]</span> route</span>;</span></span> bytes</span>[</span>]</span> scpInputs</span>;</span></span> bytes</span> proof</span>;</span></span> }</span></span> </span> ///</span> @notice</span> Reads a broadcast message from a remote chain.</span></span> ///</span> @param</span> broadcasterReadArgs</span> A RemoteReadArgs object:</span></span> ///</span> - The route points to the broadcasting chain</span></span> ///</span> - The account proof is for the broadcaster's account</span></span> ///</span> - The proof is for the message storage slot (MAY accept proofs of other transmission mechanisms (e.g., child-to-parent native bridges) if the broadcaster contract uses other transmission mechanisms)</span></span> ///</span> @param</span> message</span> The message to read.</span></span> ///</span> @param</span> publisher</span> The address of the publisher who broadcast the message.</span></span> ///</span> @return</span> broadcasterId</span> The broadcaster's unique identifier.</span></span> ///</span> @return</span> timestamp</span> The timestamp when the message was broadcast.</span></span> function</span> verifyBroadcastMessage</span>(</span>RemoteReadArgs</span> calldata</span> broadcasterReadArgs</span>,</span> bytes32</span> message</span>,</span> address</span> publisher</span>)</span></span> external</span></span> view</span></span> returns</span> (</span>bytes32</span> broadcasterId</span>,</span> uint256</span> timestamp</span>)</span>;</span></span> </span> ///</span> @notice</span> Updates the state commitment prover copy in storage.</span></span> ///</span> Checks that StateProverCopy has the same code hash as stored in the StateProverPointer</span></span> ///</span> Checks that the version is increasing.</span></span> ///</span> @param</span> scpPointerReadArgs</span> A RemoteReadArgs object:</span></span> ///</span> - The route points to the StateProverPointer's home chain</span></span> ///</span> - The account proof is for the StateProverPointer's account</span></span> ///</span> - The proof is for the STATE_PROVER_POINTER_SLOT</span></span> ///</span> @param</span> scpCopy</span> The StateProver copy on the local chain.</span></span> ///</span> @return</span> scpPointerId</span> The ID of the StateProverPointer</span></span> function</span> updateStateProverCopy</span>(</span>RemoteReadArgs</span> calldata</span> scpPointerReadArgs</span>,</span> IStateProver</span> scpCopy</span>)</span></span> external</span></span> returns</span> (</span>bytes32</span> scpPointerId</span>)</span>;</span></span> </span> ///</span> @notice</span> The StateProverCopy on the local chain corresponding to the scpPointerId</span></span> ///</span> MUST return 0 if the StateProverPointer does not exist.</span></span> function</span> stateProverCopy</span>(</span>bytes32</span> scpPointerId</span>)</span> external</span> view</span> returns</span> (</span>IStateProver</span> scpCopy</span>)</span>;</span></span> }</span></span></code></pre>Rationale</h2> Broadcast vs Unicast</h3> A contract on any given chain cannot dictate which other chains can and cannot inspect its state. Contracts are naturally broadcasting their state to anything capable of reading it. Targeted messaging applications can always be built on top of a broadcast messaging system.</p> See Reference Implementation</a> for an example of a unicast application.</p> Using Storage Proofs</h3> Message reading SHOULD use storage proofs to read messages from storage slots. However, an alternative method to this would be to pass messages (perhaps batched) via the canonical bridges of the chains. However storage proofs have some advantages over this method:</p> They only require gas tokens on the chains where the message is sent and received, none on the chains on the route in between.</li> Batching by default. Since storage slots share a common state root, caching the state root allows readers to open adjacent slots at lower cost. This provides a form of implicit batching, whereas canonical bridges would need to create a form of explicit batching.</li> If the common ancestor of the two chains is Ethereum, sending a message using the canonical bridges would require sending a transaction on Ethereum, which would likely incur a high cost.</li> </ul> No duplicate messages per publisher</h3> To allow publishers to send the same message multiple times, some kind of nonce system would need to exist in this ERC. Since nonces can be implemented at the Publisher / Subscriber layer, and not all Publishers / Subscribers require this feature, it is left out of this ERC.</p> Cost Comparison</h4> Here we compare the cost of using storage proofs vs sending messages via the canonical bridge, where the parent chain is Ethereum. Here, we will only consider the cost of the L1 gas as we assume it to dominate the L2 gas costs.</p> Each step along the route requires 1 storage proof. These proofs can be estimated at roughly 6.5k bytes. These proofs will likely be submitted on an L2/L3 and therefore be included in blobs on the L1, which have a fluctuating blob gas price. Since rollups can dynamically switch between calldata and blobs, we can work out a maximum amount of normal L1 gas that could be using the standard cost of calldata as an upper bound. Post Pectra, the upper bound for non-zero-byte calldata is 40 gas per byte, which for 6.5k bytes equates to 260,000 L1 gas.</p> We want to compare this to sending a single message via a canonical rollup bridge, which is either a parent->child or child->parent message. This estimate is dependent on specific implementations of the bridge for different rollup frameworks, but we estimate it to be around 150,000 gas.</p> This puts the upper bound of the storage proof to be around 2x that of the canonical bridge, but in practice this upper bound is rarely reached. On top of that, the Receiver can implement a caching policy allowing many messages to share the same storage proofs.</p> Caching</h3> This ERC does not currently describe how the Receiver can cache the results of storage proofs to improve efficiency. In brief, once a storage proof is executed it never needs to be executed again, and instead the result can be stored by the Receiver. This allows messages that share the same, or partially the same, route to share previously executed proofs and instead lookup the result. As an example we can consider the route between two L2s using storage proofs:</p> Ethereum block hash is looked up directly on L2' by the Receiver on L2'</li> The block hash of L2'' is proven using a storage proof</li> The account root of the Broadcaster on L2'' is proven using a storage proof</li> The slot value in the Broadcaster account is proven using a storage proof The result of everything up to step 4 in this process can be stored in a Receiver cache and re-used by any unread messages in the Broadcaster. The Receiver can even go further and cache individual nodes in the account trie to make step 4. cheaper for previous messages.</li> </ol> Using Routes in Identifiers</h3> Chains are often identified by chain ID's. Chain ID's are set by the chain owner so they are not guaranteed to be unique. Using the addresses of the Pointers is guaranteed to be unique as it provides a way to unwrap the nested state commitments embedded in the state roots. A storage slot on a remote chain can be identified by many different remote account ID's, but one remote account ID cannot identify more than one storage slot.</p> StateProvers, Pointers, and Copies</h3> StateProvers</h4> Each rollup implements unique logic for managing and storing state commitments. To accommodate this diversity, StateProvers implement chain-specific procedures. This flexibility allows integration with each rollup's distinct architecture and state commitment scheme.</p> The StateProver handles the final step of verifying a storage slot given a target state commitment to accommodate rollups with differing state commitment schemes and formats.</p> StateProverPointers</h4> Routes reference StateProvers through Pointers rather than directly. This indirection is crucial because:</p> Chain upgrades may require StateProver redeployments</li> Routes must remain stable and valid across these upgrades - ensuring in-flight messages are not broken</li> Pointers maintain route consistency while allowing StateProver implementations to evolve</li> </ul> StateProverCopies</h4> Since StateProverPointers reference StateProvers via their code hash, a copy of the StateProver can be deployed anywhere and reliably understood to contain the same code as that referenced by the Pointer. This allows the Receiver to locally use the code of a StateProver whose home chain is a remote chain.</p> Reference Implementation</h2> The following is an example of a one-way crosschain token migrator. The burn side of the migrator is a publisher which sends burn messages through a Broadcaster. The mint side subscribes to these burn messages through a Receiver on another chain.</p> ///</span> @notice</span> Message format for the burn and mint migrator.</span></span> struct</span> BurnMessage</span> {</span></span> address</span> mintTo</span>;</span></span> uint256</span> amount</span>;</span></span> uint256</span> nonce</span>;</span></span> }</span></span></code></pre>///</span> @notice</span> The burn side of an example one-way cross chain token migrator.</span></span> ///</span> @dev</span> This contract is considered a "publisher"</span></span> contract</span> Burner</span> {</span></span> ///</span> @notice</span> The token to burn.</span></span> IERC20 </span>public</span> immutable</span> burnToken</span>;</span></span> ///</span> @notice</span> The broadcaster to publish messages through.</span></span> IBroadcaster </span>public</span> immutable</span> broadcaster</span>;</span></span> ///</span> @notice</span> An incrementing nonce, so each burn is a unique message.</span></span> uint256</span> public</span> burnCount</span>;</span></span> </span> ///</span> @notice</span> Event emitted when tokens are burned.</span></span> ///</span> @dev</span> Publishers SHOULD emit enough information to reconstruct the message.</span></span> event</span> Burn</span>(</span>BurnMessage</span> messageData</span>)</span>;</span></span> </span> constructor</span>(</span>IERC20</span> _burnToken</span>,</span> IBroadcaster</span> _broadcaster</span>)</span> {</span></span> burnToken </span>=</span> _burnToken</span>;</span></span> broadcaster </span>=</span> _broadcaster</span>;</span></span> }</span></span> </span> ///</span> @notice</span> Burn the tokens and broadcast the event.</span></span> ///</span> The corresponding token minter will subscribe to the message on another chain and mint the tokens.</span></span> function</span> burn</span>(</span>address</span> mintTo</span>,</span> uint256</span> amount</span>)</span> external</span> {</span></span> //</span> first, pull in the tokens and burn them</span></span> burnToken</span>.</span>transferFrom</span>(</span>msg.sender</span>,</span> address</span>(</span>this</span>)</span>,</span> amount</span>)</span>;</span></span> burnToken</span>.</span>burn</span>(</span>amount</span>)</span>;</span></span> </span> //</span> next, build a unique message</span></span> BurnMessage </span>memory</span> messageData </span>=</span> BurnMessage</span>(</span>{</span>mintTo</span>:</span> mintTo</span>,</span> amount</span>:</span> amount</span>,</span> nonce</span>:</span> burnCount</span>+</span>+</span>}</span>)</span>;</span></span> bytes32</span> message </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>messageData</span>)</span>)</span>;</span></span> </span> //</span> finally, broadcast the message</span></span> broadcaster</span>.</span>broadcastMessage</span>(</span>message</span>)</span>;</span></span> </span> emit</span> Burn</span>(</span>messageData</span>)</span>;</span></span> }</span></span> }</span></span></code></pre>///</span> @notice</span> The mint side of an example one-way cross chain token migrator.</span></span> ///</span> This contract must be given minting permissions on its token.</span></span> ///</span> @dev</span> This contract is considered a "subscriber"</span></span> contract</span> Minter</span> {</span></span> ///</span> @notice</span> Address of the Burner contract on the other chain.</span></span> address</span> public</span> immutable</span> burner</span>;</span></span> ///</span> @notice</span> The BroadcasterID corresponding to the broadcaster on the other chain that the Burner uses.</span></span> ///</span> The Minter will only accept messages published by the Burner through this Broadcaster.</span></span> bytes32</span> public</span> immutable</span> broadcasterId</span>;</span></span> ///</span> @notice</span> The receiver to listen for messages through.</span></span> IReceiver </span>public</span> immutable</span> receiver</span>;</span></span> ///</span> @notice</span> A mapping to keep track of which messages have been processed.</span></span> ///</span> Subscribers SHOULD keep track of processed messages because the Receiver does not.</span></span> ///</span> The Broadcaster ensures messages are unique, so true duplicates are not possible.</span></span> mapping</span>(</span>bytes32</span> =></span> bool</span>)</span> public</span> processedMessages</span>;</span></span> ///</span> @notice</span> The token to mint.</span></span> IERC20 </span>public</span> immutable</span> mintToken</span>;</span></span> </span> constructor</span>(</span>address</span> _burner</span>,</span> bytes32</span> _broadcasterId</span>,</span> IReceiver</span> _receiver</span>,</span> IERC20</span> _mintToken</span>)</span> {</span></span> burner </span>=</span> _burner</span>;</span></span> broadcasterId </span>=</span> _broadcasterId</span>;</span></span> receiver </span>=</span> _receiver</span>;</span></span> mintToken </span>=</span> _mintToken</span>;</span></span> }</span></span> </span> ///</span> @notice</span> Mint the tokens when a message is received.</span></span> function</span> mintTokens</span>(</span>IReceiver</span>.</span>RemoteReadArgs</span> calldata</span> broadcasterReadArgs</span>,</span> BurnMessage</span> calldata</span> messageData</span>)</span></span> external</span></span> {</span></span> //</span> calculate the message from the data</span></span> bytes32</span> message </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>messageData</span>)</span>)</span>;</span></span> </span> //</span> ensure the message has not been processed</span></span> require</span>(</span>!</span>processedMessages</span>[</span>message</span>]</span>,</span> "Minter: Message already processed"</span>)</span>;</span></span> </span> //</span> verify the broadcast message</span></span> (</span>bytes32</span> actualBroadcasterId</span>,</span>)</span> =</span> receiver</span>.</span>verifyBroadcastMessage</span>(</span>broadcasterReadArgs</span>,</span> message</span>,</span> burner</span>)</span>;</span></span> </span> //</span> ensure the message is from the expected broadcaster</span></span> require</span>(</span>actualBroadcasterId </span>==</span> broadcasterId</span>,</span> "Minter: Invalid broadcaster ID"</span>)</span>;</span></span> </span> //</span> mark the message as processed</span></span> processedMessages</span>[</span>message</span>]</span> =</span> true</span>;</span></span> </span> //</span> mint tokens to the recipient</span></span> mintToken</span>.</span>mint</span>(</span>messageData</span>.</span>mintTo</span>,</span> messageData</span>.</span>amount</span>)</span>;</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> Chain Upgrades</h3> If a chain upgrades such that a StateProver's verifyTargetState</code> or getTargetState</code> functions might return data besides a finalized target state commitment, then invalid messages could be read by a Receiver</code>. For instance, if a chain stores its state commitments on the parent chain in a specific mapping, and that storage slot is later repurposed, then an old StateProver might be able to pass along an invalid state commitment. It is therefore important that either:</p> the StateProver is written in such a way to detect changes like this</li> the owner who is able to repurpose these storage slots is aware of the StateProver and ensures they don't break it</li> </ul> StateProverPointer Ownership / Updates</h3> A malicious StateProverPointer owner can DoS or forge messages. However, so can the chain owner responsible for setting the slot of historical parent/child state commitments. Therefore it is expected that this chain owner be the same as the owner of the StateProverPointer so as not to introduce additional risks.</p> If the target chain of the referenced StateProver is the parent chain, the home chain owner is expected to be the StateProverPointer's owner.</li> If the target chain of the referenced StateProver is the child chain, the target chain owner is expected to be the StateProverPointer's owner.</li> </ul> If an owner neglects their responsibility to update the Pointer with new StateProver implementations when necessary, messages could fail to reach their destinations.</p> If an owner maliciously updates a Pointer to point to a StateProver that produces fraudulent results, messages can be forged.</p> If there is confidence that a chain along the route connecting them will not upgrade to break a StateProver, an unowned StateProverPointer can be deployed in the absence of a properly owned one.</p> Message guarantees</h3> This ERC describes a protocol for ensuring that messages from remote chains CAN be read, but not that they WILL be read. It is the responsibility of the Receiver caller to choose which messages they wish to read.</p> Since the ERC only uses finalized blocks, messages may take a long time to propagate between chains. Finalisation occurs sequentially in the route, therefore time to read a message is the sum of the finalisation of each of the state commitments at each step in the route.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p>

Bound Signatures

2025-12-23T00:00:00+00:00

Abstract</h2>
Recoverable ECDSA signatures can flip `s</code> and v</code> while remaining valid, so they can be compressed to 64 bytes by restricting v</code>.</p>`

Motivation</h2>
ECDSA signatures are often encoded with three parameters: v</code>, r</code>, and s</code>.
In the Solidity ABI encoding, this is 96 bytes.
By eliminating the degree of freedom, v</code>, the encoded size of a recoverable signature can be reduced to 64 bytes.
Additionally, such signatures are not malleable.</p>

Specification</h2>
Smart contracts accepting bound signatures MUST supply 27</code> for v</code>.</p>

address</span> signer </span>=</span> ecrecover</span>(</span>digest</span>,</span> 27</span>,</span> r</span>,</span> s</span>)</span>;</span></span>
require</span>(</span>signer </span>!=</span> address</span>(</span>0</span>)</span>)</span>;</span></span></code></pre>
ECDSA signatures MUST be bound before supplied to such contracts.</p>
const</span> SECP256K1_N</span>:</span> bigint</span> =</span> 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141</span>n</span></span>
</span>
function</span> bind</span>(</span>sig</span>:</span> Signature</span>,</span> v</span>:</span> 27</span> |</span> 28</span> =</span> 27</span>)</span>:</span> Signature</span> {</span></span>
    if</span> (</span>sig</span>.</span>v</span> ===</span> v</span>)</span> {</span></span>
        return</span> sig</span></span>
    }</span></span>
    const</span> s</span> =</span> SECP256K1_N</span> -</span> sig</span>.</span>s</span></span>
    return</span> new</span> Signature</span>(</span>sig</span>.</span>r</span>,</span> s</span>,</span> v</span>)</span></span>
}</span></span></code></pre>Rationale</h2>
Another signature compression approach, ERC-2098</a>, stores the y-parity bit in the most-significant bit of the low s</code>.
Bound signatures are preferable because they are valid inputs to the ecrecover</code> precompile.
They require less gas because they do not need to be unpacked by the smart contract.</p>
27</code> was chosen over 28</code> to make the y-parity falsy.</p>
Backwards Compatibility</h2>
Bound signatures are compatible with ecrecover</code> if 27 is supplied for the v</code> parameter.
They cannot be used for transaction signatures because they permit high s</code>, in violation of EIP-2</a>.</p>
Test Cases</h2>
Signer</th> Digest</th> r</code></th> s</code></th></tr></thead>

0x4a6f6B9fF1fc974096f9063a45Fd12bD5B928AD1</code></td> 0xb0922c37cafd247fe3ada4eb1d1e3735b7d2837437c1178e9af120d535214270</code></td> 0xdb7f75635124c807ec1f8b03e34cd76b633dc3a189e3c85fc5aee7e7d71df38c</code></td> 0x5f1e6c6edf21cacfc2acba2815b253b9048b894eec5aaf70343389bb596c48bc</code></td></tr>
0x4a6f6B9fF1fc974096f9063a45Fd12bD5B928AD1</code></td> 0xd92ff06caae7253883627416a425414d79e9003b91d6208add30e73735ef13c3</code></td> 0xaa40efd534ac7f96b85babd7df9228fa131e8523115ca1ebc025698c37f3867d</code></td> 0xa4b8d3c650fe62e46a563aed681bfdd44d50452fa7712bd139f2bfba3aed59c9</code></td></tr>
0x6B93E3bB9C0780C0f9042346Ffc379530a5882c1</code></td> 0xfa75eba87f076cf22489da7c53a651bb3869473f78d09d4814afb7ab2d54ed45</code></td> 0xaf4a877600ab6d14ebac626830cf1063d624487932b3cc73a7cd98ae7fbf337f</code></td> 0xbc41d29acfcd3a1e7b5cb2dde1b85fe8882739312639b5f16d476a87584c040f</code></td></tr>
</tbody></table>
Reference Implementation</h2>
pragma</span> solidity</span> ^0.8.30</span>;</span></span>
</span>
library</span> BoundSignatures</span> {</span></span>
    function</span> recover</span>(</span>bytes32</span> digest</span>,</span> bytes32</span> r</span>,</span> bytes32</span> s</span>)</span> internal</span> pure</span> returns</span> (</span>address</span> signer</span>)</span> {</span></span>
        signer </span>=</span> ecrecover</span>(</span>digest</span>,</span> 27</span>,</span> r</span>,</span> s</span>)</span>;</span></span>
        require</span>(</span>signer </span>!=</span> address</span>(</span>0</span>)</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Security Considerations</h2>
Bound signatures are recoverable and not malleable.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Diamonds, Simplified
2025-12-21T00:00:00+00:00
Abstract</h2>
A diamond is a proxy contract that delegatecall</code>s to multiple implementation contracts called facets.</p>
</p>
Diamond contracts were originally standardized by ERC-2535</a>. This standard refines that specification by simplifying terminology, reducing the implementation complexity of introspection functions, and standardizing specific events.</p>
This standard preserves the full capabilities of diamond contracts while reducing complexity. It also specifies an optional upgrade path for existing ERC-2535 diamonds.</p>
Motivation</h2>
Motivation for Diamond Contracts</h3>
Through a single contract address, a diamond provides functionality from multiple implementation contracts (facets). Each facet is independent, yet facets can share internal functions and storage. This architecture allows large smart-contract systems to be composed from separate facets and presented as a single contract, simplifying deployment, testing, and integration with other contracts, off-chain software, and user interfaces.</p>
By decomposing large smart contracts into facets, diamonds can reduce complexity and make systems easier to reason about. Distinct areas of functionality can be isolated, organized, tested, and managed independently.</p>
Diamonds combine the single-address convenience of a monolithic contract with the modular flexibility of distinct, integrated contracts.</p>
This architecture is well suited to immutable</strong> smart-contract systems, where all functionality is composed from multiple facets at deployment time and permanently fixed thereafter.</p>
For upgradeable systems, diamonds enable incremental development: new functionality can be added, and existing functionality modified, without redeploying unaffected facets.</p>
Additional motivation and background for diamond-based smart-contract systems can be found in ERC-1538</a> and ERC-2535</a>.</p>
Motivation for this Standard</h3>
Unlike monolithic contracts, a diamond's external functions are commonly determined by runtime routing (selector → facet mapping) rather than being wholly represented in the diamond's source code or bytecode. To accurately determine or display the full set of functionality a diamond has, tooling must rely on standardized introspection functions and events.</p>
Block explorers, indexers, development tools, and user interfaces need a standard way to inspect which functions and facets a diamond possesses. Additionally, tooling can be built to reconstruct and display the full development or upgrade history of diamond contracts using event logs.</p>
ERC-2535 standardized introspection functions and events. ERC-8109</a> re-standardizes these to make diamond contracts easier to implement and easier to understand.</p>
ERC-8109 improves upon ERC-2535 Diamonds in the following ways:</p>

Simplified terminology.</li>
Fewer and simpler to implement introspection functions.</li>
Replaces a single monolithic event, with per-function events. This makes it easier to implement a variety of functions that add, replace and remove functions in a diamond. It also makes it easier for tools to search for and process events.</li>
</ol>
Specification</h2>
Terms</h3>

A diamond</strong> is a smart contract that routes external function calls to one or more implementation contracts, referred to as facets. A diamond is stateful: all persistent data is stored in the diamond’s contract storage. A diamond implements the requirements in the Implementation Requirements</a> section.</li>
A facet</strong> is a smart contract that defines one or more external functions. A facet is deployed independently, and one or more of its functions are added to one or more diamonds. A facet’s functions are executed in the diamond’s context via delegatecall</code>, so reads/writes affect the diamond’s storage. The term facet is derived from the diamond industry, referring to a flat surface of a diamond.</li>
An introspection function</strong> is a function that returns information about the facets and functions used by a diamond.</li>
For the purposes of this specification, a mapping</strong> refers to a conceptual association between two items and does not refer to a specific implementation.</li>
</ol>
Diamond Diagram</h3>
This diagram shows the structure of a diamond.</p>
It shows that a diamond has a mapping from function to facet and that facets can access the storage inside a diamond.</p>
</p>
Fallback</h3>
When an external function is called on a diamond, its fallback function is executed. The fallback function determines which facet to call based on the first four bytes of the calldata (known as the function selector) and executes the function from the facet using delegatecall</code>.</p>
A diamond’s fallback function and delegatecall</code> enable a diamond to execute a facet’s function as if it was implemented by the diamond itself. The msg.sender</code> and msg.value</code> values do not change and only the diamond’s storage is read and written to.</p>
Here is an example of how a diamond’s fallback function might be implemented:</p>
error</span> FunctionNotFound</span>(</span>bytes4</span> _selector</span>)</span>;</span></span>
</span>
//</span> Executes function call on facet using `delegatecall`.</span></span>
//</span> Returns function call return data or revert data.</span></span>
fallback</span>(</span>)</span> external</span> payable</span> {</span></span>
    //</span> Get facet address from function selector</span></span>
    address</span> facet </span>=</span> selectorToFacet</span>[</span>msg</span>.</span>sig</span>]</span>;</span></span>
    if</span> (</span>facet </span>==</span> address</span>(</span>0</span>)</span>)</span> {</span></span>
        revert</span> FunctionNotFound</span>(</span>msg</span>.</span>sig</span>)</span>;</span></span>
    }</span></span>
    //</span> Execute external function on facet using `delegatecall` and return any value.</span></span>
    assembly</span> {</span></span>
        //</span> Copy function selector and any arguments from calldata to memory.</span></span>
        calldatacopy</span>(</span>0</span>,</span> 0</span>,</span> calldatasize</span>(</span>)</span>)</span></span>
        //</span> Execute function call using the facet.</span></span>
        let</span> result </span>:=</span> delegatecall</span>(</span>gas</span>(</span>)</span>,</span> facet</span>,</span> 0</span>,</span> calldatasize</span>(</span>)</span>,</span> 0</span>,</span> 0</span>)</span></span>
        //</span> Copy all return data from the previous call into memory.</span></span>
        returndatacopy</span>(</span>0</span>,</span> 0</span>,</span> returndatasize</span>(</span>)</span>)</span></span>
        //</span> Return any return value or error back to the caller.</span></span>
        switch result</span></span>
        case </span>0</span> {</span>revert</span>(</span>0</span>,</span> returndatasize</span>(</span>)</span>)</span>}</span></span>
        default </span>{</span>return</span> (</span>0</span>,</span> returndatasize</span>(</span>)</span>)</span>}</span></span>
    }</span></span>
}</span></span></code></pre>Function Not Found</h4>
If the fallback function cannot find a facet for a function selector, and there is no default function or other mechanism to handle the call, the fallback MUST revert with the error FunctionNotFound(bytes4 _selector)</code>.</p>
Events</h3>
Adding/Replacing/Removing Functions</h4>
These events are REQUIRED.</p>
For each function selector that is added, replaced, or removed, the corresponding event MUST be emitted.</p>
/**</span></span>
* </span>@notice</span> Emitted when a function is added to a diamond.</span></span>
*</span></span>
* </span>@param</span> _selector</span> The function selector being added.</span></span>
* </span>@param</span> _facet</span>    The facet address that will handle calls to `_selector`.</span></span>
*/</span></span>
event</span> DiamondFunctionAdded</span>(</span>bytes4</span> indexed</span> _selector</span>, </span>address</span> indexed</span> _facet</span>)</span>;</span></span>
</span>
/**</span></span>
* </span>@notice</span> Emitted when changing the facet that will handle calls to a function.</span></span>
* </span></span>
* </span>@param</span> _selector</span> The function selector being affected.</span></span>
* </span>@param</span> _oldFacet</span> The facet address previously responsible for `_selector`.</span></span>
* </span>@param</span> _newFacet</span> The facet address that will now handle calls to `_selector`.</span></span>
*/</span></span>
event</span> DiamondFunctionReplaced</span>(</span></span>
    bytes4</span> indexed</span> _selector</span>,</span></span>
    address</span> indexed</span> _oldFacet</span>,</span></span>
    address</span> indexed</span> _newFacet</span></span>
)</span>;</span></span>
</span>
/**</span></span>
* </span>@notice</span> Emitted when a function is removed from a diamond.</span></span>
*</span></span>
* </span>@param</span> _selector</span> The function selector being removed.</span></span>
* </span>@param</span> _oldFacet</span> The facet address that previously handled `_selector`.</span></span>
*/</span></span>
event</span> DiamondFunctionRemoved</span>(</span></span>
    bytes4</span> indexed</span> _selector</span>, </span></span>
    address</span> indexed</span> _oldFacet</span></span>
)</span>;</span></span></code></pre>Recording Non-Fallback delegatecall</code>s</h4>
This event is OPTIONAL.</p>
This event can be used to record delegatecall</code>s made by a diamond.</p>
This event MUST NOT be emitted for delegatecall</code>s made by a diamond’s fallback function when routing calls to facets. It is only intended for delegatecall</code>s made by functions in facets or a diamond’s constructor.</p>
This event enables tracking of changes to a diamond’s contract storage caused by delegatecall</code> execution.</p>
/**</span></span>
* </span>@notice</span> Emitted when a diamond's constructor function or function from a</span></span>
*         facet makes a `delegatecall`. </span></span>
* </span></span>
* </span>@param</span> _delegate</span>         The contract that was the target of the `delegatecall`.</span></span>
* </span>@param</span> _delegateCalldata</span> The function call, including function selector and </span></span>
*                          any arguments.</span></span>
*/</span></span>
event</span> DiamondDelegateCall</span>(</span>address</span> indexed</span> _delegate</span>, </span>bytes</span> _delegateCalldata</span>)</span>;</span></span></code></pre>Diamond Metadata</h4>
This event is OPTIONAL.</p>
This event can be used to record versioning or other information about diamonds.</p>
It can be used to record information about diamond upgrades.</p>
/**</span></span>
* </span>@notice</span> Emitted to record information about a diamond.</span></span>
* </span>@dev</span>    This event records any arbitrary metadata. </span></span>
*         The format of `_tag` and `_data` are not specified by the </span></span>
*         standard.</span></span>
*</span></span>
* </span>@param</span> _tag</span>   Arbitrary metadata, such as a release version.</span></span>
* </span>@param</span> _data</span>  Arbitrary metadata.</span></span>
*/</span></span>
event</span> DiamondMetadata</span>(</span>bytes32</span> indexed</span> _tag</span>, </span>bytes</span> _data</span>)</span>;</span></span></code></pre>Inspecting Diamonds</h3>
Diamond introspection functions return information about what functions and facets are used in a diamond.</p>
These functions MUST be implemented and are required by the standard:</p>
/**</span> @notice</span> Gets the facet that handles the given selector.</span></span>
 *</span></span>
 *  </span>@dev</span> If facet is not found return address(0).</span></span>
 *  </span>@param</span> _functionSelector</span> The function selector.</span></span>
 *  </span>@return</span> The</span> facet address associated with the function selector.</span></span>
 */</span></span>
function</span> facetAddress</span>(</span>bytes4</span> _functionSelector</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
</span>
struct</span> FunctionFacetPair</span> {</span></span>
    bytes4</span> selector</span>;</span></span>
    address</span> facet</span>;</span></span>
}</span></span>
</span>
/**</span></span>
* </span>@notice</span> Returns an array of all function selectors and their </span></span>
*         corresponding facet addresses.</span></span>
*</span></span>
* </span>@dev</span>    Iterates through the diamond's stored selectors and pairs</span></span>
*         each with its facet.</span></span>
* </span>@return</span> pairs</span> An array of `FunctionFacetPair` structs, each containing</span></span>
*         a selector and its facet address.</span></span>
*/</span></span>
function</span> functionFacetPairs</span>(</span>)</span> external</span> view</span> returns</span>(</span>FunctionFacetPair</span>[</span>]</span> memory</span> pairs</span>)</span>;</span></span></code></pre>
The essence of a diamond is its function -> facet</code> mapping. functionFacetPairs()</code> returns that mapping as an array of (selector, facet)</code> pairs.</p>
These functions were chosen because they provide all necessary facet and function data about a diamond. They are very simple to implement and are computationally efficient.</p>
Block explorers, GUIs, tests, and other tools may rely on their presence.</p>
A reference implementation exists for these introspection functions here: DiamondInspectFacet.sol</a></p>
Other introspection functions may be added to a diamond. The above two functions are the only ones required by this standard.</p>
Implementation Requirements</h3>
A diamond MUST implement the following:</p>

Diamond Structure</strong>

A diamond MUST implement a fallback()</code> function.</li>
</ul>
</li>
Function Association</strong>

A diamond MUST associate function selectors with facet addresses.</li>
</ul>
</li>
Function Execution</strong>

When an external function is called on a diamond:

The diamond’s fallback function is executed.</li>
The fallback function MUST find the facet associated with the function selector.</li>
The fallback function MUST execute the function on the facet using delegatecall</code>.</li>
If no facet is associated with the function selector, the diamond MAY execute a default function or apply another handling mechanism.</li>
If no facet, default function, or other handling mechanism exists, execution MUST revert with the error FunctionNotFound(bytes4 _selector)</code>.</li>
</ul>
</li>
</ul>
</li>
Events</strong>

The following events MUST be emitted:

DiamondFunctionAdded</code> — when a function is added to a diamond.</li>
DiamondFunctionReplaced</code> — when a function is replaced in a diamond.</li>
DiamondFunctionRemoved</code> — when a function is removed from a diamond.</li>
</ul>
</li>
</ul>
</li>
Introspection</strong>

A diamond MUST implement the following introspection functions:

facetAddress(bytes4 _functionSelector)</code></li>
functionFacetPairs()</code></li>
</ul>
</li>
</ul>
</li>
</ol>
receive()</code> function</h3>
A diamond MAY have a receive()</code> function.</p>
Immutable Functions</h3>
Definition:</p>

An immutable function is an external or public function defined directly in a diamond contract, not in a facet.

This definition does not apply to a diamond's constructor or the special fallback()</code> and receive()</code> functions.</p>
</blockquote>
A diamond can have zero or more immutable functions.</p>
A diamond with immutable functions has the following additional requirements that MUST be followed:</p>

The DiamondFunctionAdded</code> event MUST be emitted for each immutable function.</li>
Immutable functions MUST be returned by the introspection functions facetAddress(bytes4 _functionSelector)</code> and functionFacetPairs()</code>, where the facet address is the diamond’s own address.</li>
Any upgrade function MUST revert on an attempt to replace or remove an immutable function.</li>
</ol>
Rationale</h2>
This standard provides standard events and introspection functions so that GUIs, block explorers, command line programs, and other tools and software can detect and interoperate with diamond contracts.</p>
Software can retrieve function selectors and facet addresses from a diamond in order to use and show what functions a diamond has. Function selectors and facet addresses, combined with contract ABIs and verified source code, provide sufficient information for tooling and user interfaces.</p>
ERC-8109 Diamonds vs ERC-2535 Diamonds</h3>
This standard is a simplification and refinement of ERC-2535 Diamonds.</p>
A diamond compliant with ERC-8109 is NOT required to implement ERC-2535.</p>
Here are changes in ERC-8109 Diamonds:</p>

Simplified terminology.</li>
Simplified introspection functions.</li>
Standardized events that are simpler to use and consume.</li>
Optional upgrade path for existing ERC-2535 diamonds.</li>
</ul>
Diamond Upgrades</h3>
This standard does not specify an upgrade function.</p>
This means several things:</p>
1. Diamonds Can Be Immutable</h4>
A Diamond does not have to have an upgrade function.</p>


A diamond can be fully constructed within its constructor function without adding any upgrade function, making it immutable upon deployment.</p>
</li>

A large immutable diamond can be built using well organized facets.</p>
</li>

A diamond can initially be upgradeable, and later made immutable by removing its upgrade function.</p>
</li>
</ul>
2. Other Standards Can Build on ERC-8109</h4>
Other standards can build on ERC-8109 by specifying an upgrade function(s), while remaining compliant with this standard.</p>
3. You Can Create Your Own Upgrade Functions</h4>
You can design and create your own upgrade functions and remain compliant with this standard. All that is required is that you emit the appropriate add/replace/remove required events specified in the events section</a>, and that the introspection functions defined in the Inspecting Diamonds section</a> continue to accurately return function and facet information.</p>
Gas Considerations</h3>
Routing calls via delegatecall</code> introduces a small amount of gas overhead. In practice, this cost is mitigated by several architectural and tooling advantages enabled by diamonds:</p>


Optional, gas-optimized functionality</strong>

By structuring functionality across multiple facets, diamonds make it straightforward to include specialized, gas-optimized features without increasing the complexity of core logic.

For example, an ERC-721</a> diamond may implement batch transfer functions in a dedicated facet, improving both gas efficiency and usability while keeping the base ERC-721 implementation simple and well-scoped.</p>
</li>

Reduced external call overhead</strong>

Some contract architectures require multiple external calls within a single transaction. By consolidating related functionality behind a single diamond address, these interactions can execute internally with shared storage and shared authorization, reducing gas costs from external calls and repeated access-control checks.</p>
</li>

Selective optimization per facet</strong>

Because facets are compiled and deployed independently, they may be built with different compiler optimizer settings. This allows gas-critical facets to use aggressive optimization configurations to reduce execution costs, without increasing bytecode size or compilation complexity for unrelated functionality.</p>
</li>
</ol>
functionFacetPairs()</code> Gas Usage</h3>
The functionFacetPairs()</code> function is meant to be called off-chain. At this time major RPC providers have a maximum gas limit of about 550 million gas. Gas benchmark tests show that the functionFacetPairs()</code> function can return 60,000 (selector, facet)</code> pairs using less gas than that.</p>
ERC-8109 implementations are free to add iteration or pagination-based introspection functions, but they are not required by this standard.</p>
Storage Layout</h3>
Diamonds and facets need to use a storage layout organizational pattern because Solidity’s default storage layout doesn’t support proxy contracts or diamonds. The storage layout technique or pattern to use is not specified in this ERC. However, examples of storage layout patterns that work with diamonds are ERC-8042 Diamond Storage</a> and ERC-7201 Namespaced Storage Layout</a>.</p>
Facets Sharing Storage & Functionality</h3>
Facets are separately deployed, independent units, but can share state and functionality in the following ways:</p>

Facets can share state variables by using the same structs at the same storage positions.</li>
Facets can share internal functions by importing them or inheriting contracts.</li>
</ul>
On-chain Facets can be Reused and Composed</h3>
A deployed facet can be used by many diamonds.</p>
It is possible to create and deploy a set of facets that are reused by different diamonds.</p>
The ability to use the same deployed facets for many diamonds has the potential to reduce development time, increase reliability and security, and reduce deployment costs.</p>
It is possible to implement facets in a way that makes them usable/composable/compatible with other facets.</p>
Function Signature Limitation</h3>
A function signature is the name of a function and its parameter types. Example function signature: myfunction(uint256)</code>. A limitation is that two external functions with the same function signature can’t be added to the same diamond at the same time because a diamond, or any contract, cannot have two external functions with the same function signature.</p>
Immutable Functions Considerations</h3>
Immutable functions offer minor gas savings by avoiding fallback logic and a delegatecall</code>. However, they introduce a second implementation alongside facets, resulting in two ways to provide similar functionality. This increases implementation complexity and cognitive overhead.</p>
A diamond is simpler to implement and understand without immutable functions.</p>
In upgradeable diamonds, immutable functions reduce flexibility, as they cannot be replaced or removed. This limits the ability to evolve, fix, or improve functionality over time.</p>
Immutable functions that read from or write to storage are not isolated from upgrades. Other functions, including upgrade logic, may modify the same storage relied upon by immutable functions.</p>
Backwards Compatibility</h2>
Existing, deployed ERC-2535 Diamonds implementations MAY upgrade to this standard by performing an upgrade that does the following:</p>

Removes the existing upgrade function and adds a new upgrade function that uses the new events.</li>
Adds the new functionFacetPairs()</code> introspection function.</li>
Emits a DiamondFunctionAdded</code> event for every function currently in the diamond, including the new upgrade function and the new functionFacetPairs()</code> function.</li>
</ol>
Any other upgrade details are implementation specific.</p>
After this upgrade, the diamond is considered compliant with this standard and SHOULD be indexed and treated as a diamond of this standard going forward.</p>
This upgrade acts as a 'state snapshot'. Indexers only interested in the current state of the diamond can start indexing from this transaction onwards, without needing to parse the legacy DiamondCut</code> history.</p>
To reconstruct the complete upgrade history requires retrieving all the past DiamondCut</code> events as well as all new events defined in this standard.</p>
ERC-2535 Diamonds with Immutable Functions</h3>
An ERC-2535 diamond that upgrades to this standard and has immutable functions MUST comply with the Immutable Functions</a> section of the Specification.</p>
If the ERC-2535 diamond upgrade function is immutable, then it can't be removed. If possible, disable the upgrade function by making its authentication always fail.</p>
Reference Implementation</h2>

The reference implementation for the facetAddress(bytes4 _functionSelector)</code> and functionFacetPairs()</code> introspection functions is here: DiamondInspectFacet.sol</a></li>
An example implementation of an ERC-8109 diamond is here: DiamondExample.sol</a></li>
</ul>
Security Considerations</h2>
Ownership and Authentication</h3>
The design and implementation of diamond ownership/authentication is not part of this standard.</p>
It is possible to create many different authentication or ownership schemes with diamonds. Authentication schemes can be very simple or complex, fine grained or coarse. This proposal does not limit it in any way. For example ownership/authentication could be as simple as a single account address having the authority to add/replace/remove functions. Or a decentralized autonomous organization could have the authority to add/replace/remove certain functions.</p>
The development of standards and implementations of ownership, control and authentication of diamonds is encouraged.</p>
Transparency</h3>
A diamond emits an event every time a function is added, replaced or removed. Source code can be verified. This enables people and software to monitor changes to a diamond.</p>
Security and domain experts can review a diamond's upgrade history.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Domain Architecture for Diamonds
2025-12-20T00:00:00+00:00
Abstract</h2>
This standard introduces a domain-based architectural pattern</strong> for contracts implementing the Diamond execution model defined by ERC-2535 (Diamond Standard)</a> or
ERC-8109 (Diamond, Simplified)</a>, together with the storage identifier mechanism defined by ERC-8042 (Diamond Storage Identifier)</a>.</p>
It defines a domain-centric storage management architecture, providing consistent storage identifiers and a structured directory model that decouples storage ownership from facet logic.</p>
This pattern helps reduce storage collisions and human error while enabling better tooling for multi-facet systems.</p>
Motivation</h2>
ERC-2535 provides a flexible foundation for modular smart contracts through facets, but it intentionally leaves storage organization and architectural conventions open to implementation.

While this flexibility encourages creativity, it can sometimes lead to inconsistency.

Each developer or team may structure storage differently, making it harder to design robust and easy-to-use tooling for storage management.</p>
Without a shared structural framework, storage identifiers may be inconsistently verified or reused across facets, which can result in unexpected collisions or subtle upgrade issues between facets sharing the same state.</p>
ERC-8042 introduced human-readable storage identifiers to improve clarity, but it does not define how those identifiers should be structured or grouped in larger projects.</p>
This EIP proposes a domain-centric architectural pattern that establishes a consistent framework for managing storage independently of facet implementation.</p>
By introducing clear domain boundaries and deterministic naming rules for storage identifiers, the pattern maintains the openness of the Diamond Standard while providing a shared foundation for collaboration, tooling support, and long-term upgrade safety across complex systems.</p>
Specification</h2>
1. Domain Definition</h3>


A domain</strong> represents the conceptual ownership of a storage space.</p>
</li>

Each domain</strong> corresponds to exactly one storage struct and one identifier.</p>
</li>

A domain</strong> has a one-to-many relationship with the group of function selectors that access it.</p>
</li>

A domain</strong> is independent of facets, multiple facets MAY read or modify the same domain.</p>
</li>

Domains</strong> SHOULD be defined according to business or system responsibility, not by facet name.</p>
</li>
</ul>
2. Storage Identifier Naming Convention</h3>
A storage identifier is the human-readable string whose keccak256 hash defines a Diamond Storage position.</p>
    bytes32</span> constant</span> STORAGE_POSITION </span>=</span> keccak256</span>(</span>"meaningful.string"</span>)</span>;</span></span></code></pre>
It represents the domain that owns and manages a specific storage layout.

To ensure uniqueness and clarity, at a minimum, a storage identifier SHOULD include the following components:</p>
    {project}.{domain-name}.{version}</span></span></code></pre>
To improve readability, namespace separation, and tooling support, additional contextual components MAY be included, resulting in the following extended format:</p>
    {org}.{project}.{domain-type}.{domain-name}.{version}</span></span></code></pre>Identifier Components</h3>


org</code>

Optional organization or author prefix (e.g., eth</code>, vag</code>, safe</code>)</p>
</li>

project</code>

Project or protocol name</p>
</li>

domain-type</code>

Optional classification of the domain. If present, it SHOULD be one of:</p>


diamond</code> — core Diamond protocol domains, such as upgrade, introspection, and ownership.</p>
</li>

system</code> — shared system-level domains providing cross-cutting functionality. (e.g.,  reentrancy, pause, access control)</p>
</li>

business</code> — application-specific domains. (tokens, guards, modules)</p>
</li>
</ul>
</li>

domain-name</code>

Lowercase keyword identifying the storage domain</p>
</li>

version</code>

Optional storage layout version identifier</p>


The initial storage layout is conceptually treated as v1</code>.</p>
</li>

If omitted, the identifier refers to this initial (v1</code>) storage layout for backward compatibility.</p>
</li>

v2</code>, v3</code>, … MUST be used for layout-breaking changes.</p>
</li>

The version MUST be incremented only when the storage layout is no longer append-only.</p>
</li>
</ul>
</li>
</ul>
Each domain:</strong></p>


MUST have one</strong> storage struct and one</strong> identifier.</p>
</li>

SHOULD be implemented in a dedicated directory named after the domain.</p>
</li>

If new fields are added to a storage struct, they MUST be added only at the end, and the struct MUST remain append-only.</p>
</li>
</ul>
Sub-domain Components</h3>
A sub-domain represents a storage-isolated vertical extension of an existing domain.</p>
A sub-domain is used when new functionality belongs conceptually to an existing domain, but its required state can be cleanly isolated without modifying or appending to the original domain’s storage layout.</p>
If present, the sub-domain's identifier format becomes:</p>
    {project}.{domain-name}.{version}.{sub-domain}</span></span></code></pre>
or, when using the extended format:</p>
    {org}.{project}.{domain-type}.{domain-name}.{version}.{sub-domain}</span></span></code></pre>
The version component indicates the domain version in which the sub-domain was introduced.

It serves as a historical and organizational reference, not as an independent versioning lifecycle for the sub-domain.</p>
Definition and Rules</strong></p>
A sub-domain:</p>


MUST define its own ERC-8042 storage identifier.</p>
</li>

MUST define its own storage layout</p>
</li>

MUST NOT modify or append to the parent domain’s storage.</p>
</li>

MUST remain conceptually subordinate to the parent domain.</p>
</li>

MUST share the same version context as the parent domain.</p>
</li>

SHOULD be placed alongside the parent domain’s storage definitions.</p>
</li>
</ul>
Sub-domains exist as a safety-oriented design choice to isolate newly introduced state, while preserving the original domain layout unchanged.</p>
Choosing between evolving the existing domain storage or introducing a sub-domain depends on the project’s complexity, the team’s discipline, and long-term maintenance goals.</p>
3. Storage Declaration Requirements</h3>
To support reliable tooling and explicit storage ownership, each domain defined by this proposal MUST declare its storage location using the ERC-8042 NatSpec annotation.</p>
Specifically, the domain-owned storage struct MUST be annotated with:</p>
    ///</span>@custom:storage</span>-location erc8042:<NAMESPACE_ID></span></span></code></pre>
This proposal does not redefine the storage location formula, but requires the use of this annotation to ensure that domain storage is discoverable, unambiguous, and machine-readable.</p>
Example Identifiers</h3>
The extended identifier format is recommended for global uniqueness.
It is especially useful when integrating shared libraries, predefined facets, or other standards, where namespace collisions are more likely.</p>
For application-specific systems, teams may choose a minimal identifier format to reduce naming complexity, as long as the identifier remains stable and unique within the project.</p>
Equipment Identifier</strong></p>
Represents a business domain responsible for equipment state.
This domain has undergone a layout-breaking change, therefore uses an explicit v2 identifier.</p>
    ///</span> @custom:storage</span>-location erc8042:org.project.business.equipment.v2</span></span>
    ///</span> @dev</span> Minimal form: project.equipment.v2</span></span>
    bytes32</span> constant</span> EQUIPMENT_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.business.equipment.v2"</span>)</span>;</span></span></code></pre>
Character Identifier</strong></p>
Represents a business domain responsible for character state and progression.
This example also demonstrates how a domain can be extended using a storage-isolated sub-domain.</p>
    ///</span> @custom:storage</span>-location erc8042:org.project.business.character.v1</span></span>
    ///</span> @dev</span> Minimal form: project.character.v1</span></span>
    ///</span> @dev</span> Main character domain.</span></span>
    bytes32</span> constant</span> CHARACTER_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.business.character.v1"</span>)</span>;</span></span>
</span>
    ///</span> @custom:storage</span>-location erc8042:org.project.business.character.v1.mounted</span></span>
    ///</span> @dev</span> Minimal form: project.character.v1.mounted</span></span>
    ///</span> @dev</span> Sub-domain for global character mounted state.</span></span>
    bytes32</span> constant</span> CHARACTER_MOUNTED_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.business.character.v1.mounted"</span>)</span>;</span></span></code></pre>
Game Setting Identifier</strong></p>
Defines a system-level domain for game-wide configuration shared across multiple facets.</p>
    ///</span> @custom:storage</span>-location erc8042:org.project.system.gamesettings</span></span>
    ///</span> @dev</span> Minimal form: project.gamesettings</span></span>
    bytes32</span> constant</span> GAME_SETTING_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.system.gamesettings"</span>)</span>;</span></span></code></pre>4. Directory Convention</h3>
In line with Domain-Driven Design principles, the directory layout SHOULD reflect domain ownership.</p>


Each domain defines a logical namespace for storage ownership</strong>.

Directories are named after this namespace and serve as its physical representation in the codebase.</p>
</li>

Facets act as logic containers and do not own storage</strong>.

They MAY reside alongside domain directories or reference domain-owned logic.</p>
</li>

Both directory names and storage identifiers SHOULD include domain information</strong>.

This consistency allows tooling and precompilers to automatically associate selectors, domains, and storage layouts.</p>
</li>

Each domain SHOULD be represented by a dedicated directory</strong>.

Within this directory, domain-owned logic such as storage layout definitions, internal helper logic, and any facets primarily associated with the domain MAY be organized under subdirectories as needed.</p>
</li>

This structure reduces the risk of storage collisions by design</strong>.

The alignment of domain namespaces, directory layout, and storage identifiers allows file system constraints and static analysis tools to surface conflicts early and reason about upgrades proactively.</p>
</li>
</ul>
Example Directory</h3>
This directory structure is illustrative and does not mandate a specific naming convention.</em>

Subdirectory names such as storage/</code> are illustrative and may contain both storage layout definitions and internal domain logic.</em></p>
contracts/</span></span>
├── diamond/</span></span>
│   └── Diamond.sol</span></span>
│</span></span>
├── character/</span></span>
│   ├── storage/</span></span>
│   │   └── CharacterStorage.sol</span></span>
│   └── facets/</span></span>
│       └── CharacterFacet.sol</span></span>
│</span></span>
├── equipment/</span></span>
│   ├── storage/</span></span>
│   │   └── EquipmentStorage.sol</span></span>
│   └── facets/</span></span>
│       └── EquipmentFacet.sol</span></span>
│</span></span>
└── gamesettings/</span></span>
    ├── storage/</span></span>
    │   └── GameSettingsStorage.sol</span></span>
    └── facets/</span></span>
        └── GameSettingsFacet.sol</span></span></code></pre>5. Upgrade Scenarios</h3>
This architecture defines upgrade behavior based on the effect new selectors introduce to domains and storage</strong>, rather than on facets themselves.</p>
Upgrades fall into one of the following cases.</p>
Case 1: No new storage required</strong></p>
If new selectors do not require any additional storage:</p>

The selectors MAY be added to existing facets or new facets</li>
The facet SHOULD be placed under an appropriate existing domain</li>
No storage changes are required</li>
</ul>
This is the simplest and safest upgrade path, as it introduces no new state and does not affect existing storage layouts.</p>
Case 2: New domain required (horizontal upgrade)</strong></p>
If new functionality introduces state that does not logically belong to any existing domain:</p>

A new domain MUST be defined</li>
A new ERC-8042 storage identifier MUST be introduced</li>
A new storage layout MUST be defined for that domain</li>
The facet implementing this functionality SHOULD be placed under the new domain</li>
</ul>
This represents a horizontal expansion of the system, allowing new features to be introduced without impacting existing domains or storage layouts.</p>
Case 3: New variables within an existing domain (vertical upgrade)</strong></p>
If new selectors require additional state that logically belongs to an existing domain, and the existing storage layout is not broken, this becomes a design trade-off.</p>
Two common approaches MAY be used:</p>
Option A — Evolve the existing domain</strong></p>

Append new variables to the end of the existing storage layout</li>
Add new selectors to interact with the evolved domain</li>
</ul>
This keeps the domain unified and works well for tightly coupled or complex business logic.

It requires strict discipline when managing storage layout.</p>
Option B — Introduce a sub-domain</strong></p>

Define a sub-domain under the existing domain</li>
Introduce a new storage identifier and layout for the new variables</li>
Leave the original domain storage unchanged</li>
</ul>
This approach reduces risk and cognitive load by isolating newly introduced state, while keeping the original domain layout stable.</p>
The choice between these approaches depends on project complexity, team discipline, and long-term maintenance goals.</p>
Case 4: Layout-breaking change</strong></p>
If new selectors require a change that breaks the existing storage layout of a domain

(for example, changing the inner structure of nested structs or struct arrays</em>)</p>

A new, versioned storage identifier MUST be introduced</li>
A new storage layout MUST be defined under that identifier</li>
Any required data migration MUST be handled explicitly by the project</li>
</ul>
This architecture does not attempt to automate or abstract storage migration.

The goal is to keep schema changes intentional, visible, and auditable.</p>
If the layout-breaking change is partial</strong>, and the newly required state can be cleanly isolated and defined independently, developers MAY also consider introducing a sub-domain</strong> instead of versioning the entire domain.</p>
Rationale</h2>
From the beginning, the Diamond Standard (ERC-2535) was designed around the relationship between function selectors</strong> and storage positions</strong>, not around facets themselves.

Facets are replaceable units of logic — the diamondCut</code> operation only replaces, removes or adds code — but the storage layout persists</strong> and defines the actual state continuity of the contract.</p>
ERC-8109 itself only defines introspection mechanisms for querying the Diamond and deliberately leaves the upgrade mechanism to implementations or to other standards.

This flexibility is achieved because both introspection facets and upgrade facets interact with the same underlying domain (8109.diamond</code>).</p>
This demonstrates that storage belongs to the domain</strong>, not the facet, facets merely provide interfaces for logic to read or mutate that domain.</p>
Over time, many implementations have treated facets as the primary boundary of responsibility, grouping logic and storage together without recognizing that storage domains</strong> are the true architectural anchors.

This misunderstanding leads to inconsistent storage management, overlapping identifiers and fragile upgrade paths where one facet unintentionally corrupts another’s state.</p>
The domain-centric approach</strong> restores the original intent of the Diamond:

Selectors (facets) operate through</em> domains, not as</em> domains.

Each domain defines its own persistent storage struct and identifier, while facets merely act as interfaces that execute logic against it.</p>
This shift decouples storage from logic when separation is desired, while still allowing tightly coupled designs when intentional.

It enables:</p>

Independent evolution of business logic without rewriting storage.</li>
Clear separation between reusable system components and app-specific domains.</li>
A deterministic mapping between identifiers and state.</li>
</ul>
By formalizing this pattern, Diamond Architecture becomes safer, more transparent and easier to extend — re-aligning practice with its original design philosophy.</p>
Special Case: Domain–Facet Overlap</h3>
There is a special case within the separation principle where a domain (or sub-domain) and its facet are intentionally designed to represent the same logical entity.</p>
In this scenario, the facet implements all functions belonging to its domain.
This reduces flexibility, but improves encapsulation and self-containment, making the facet behave like a reusable application module rather than a low-level primitive.</p>
A concrete example of this approach can be found in the Compose project</code>.

In Compose, a facet and its associated sub-domain are explicitly mapped into a single entity, enabling the creation of predefined, plug-and-play standard facets.</p>
This approach is suitable for systems that prioritize modular composition and standardized functionality, allowing developers to safely integrate common features with predictable behavior.

However, when implementing custom or project-specific logic, domains and facets SHOULD still be treated as separate entities.</p>
Maintaining this separation preserves clarity of ownership, supports future upgrades, and supports the long-term evolution of application-level Diamond architectures.</p>
Sub-domains and Layout-Sensitive State</h3>
Sub-domains can also serve as a practical way to isolate layout-sensitive state.</p>
Projects that need to move quickly may choose to place complex or layout-unstable data (such as mappings or dynamic arrays) in a primary domain, while isolating smaller or more compact state in sub-domains.</p>
As development progresses, additional state can either be appended to an existing domain or introduced via a sub-domain, depending on data shape and evolution needs.</p>
This allows projects to start with a simple structure while preserving flexibility to refine storage organization as the system scales.</p>
Isolated Domain</h3>
An isolated domain describes a conceptual separation between a domain and function- or facet-level logic.</p>
In this model, a domain defines its own storage access helpers.
Facets and their functions interact with domain-owned state through these helpers, rather than accessing storage layouts directly.</p>
This approach makes data access logic explicit at the domain level, while allowing facets to focus on business logic and coordination.</p>
A domain may be fully isolated, partially isolated, or not isolated, depending on project needs.</p>
This concept is particularly useful when functions or facets need to coordinate state across multiple domains or sub-domains, as it helps keep cross-domain interactions consistent and easier to reason about.</p>
Backwards Compatibility</h2>
This proposal is fully backward-compatible with ERC-2535 (Diamond Standard), ERC-8042 (Diamond Storage Identifier) and ERC-8109 (Diamond, Simplified).
It introduces no breaking changes, no new opcodes, and no modifications to existing protocol mechanics.</p>
It does not alter the execution model defined by ERC-2535 or ERC-8109.
The relationships between facets, selectors, and shared storage remain unchanged and fully compatible across all three standards.</p>
Instead, this proposal defines an architectural convention that complements existing Diamond standards by:</p>

Reinforcing modularity and upgrade safety established by ERC-2535 and ERC-8109</li>
Extending the human-readable storage identifier design introduced by ERC-8042</li>
Providing a domain-based approach to storage ownership and organization</li>
</ul>
This architecture may be applied to contracts implementing either ERC-2535 or ERC-8109, as both share the same fundamental facet and selector architecture.</p>
Developers are encouraged to continue following all applicable standards to maintain interoperability while benefiting from clearer state ownership, reduced storage collision risk, and lower architectural complexity.</p>
Adoption for Deployed Systems</h3>
For already deployed systems, adoption can be done incrementally.</p>
The Domain Architecture does not require projects to modify, rename, or refactor existing libraries or other standards in order to adopt it.
If a library or standard already follows ERC-2535, ERC-8042, or uses its own established storage identifiers, that code SHOULD remain unchanged.</p>
Adoption MAY begin at the application layer, without touching shared libraries or standardized components.
Existing storage identifiers MAY be treated conceptually as pre-v1 domains.</p>
In practice, projects typically start by:</p>

Defining clear domain boundaries</li>
Organizing directories around domain responsibility</li>
Grouping facets and their related storage by domain</li>
Explicitly declaring storage ownership using the ERC-8042 @custom:storage-location</code> annotation</li>
</ul>
Adopting the Domain Architecture does not require migrating existing state.
It primarily affects how new storage is introduced and how future upgrades are structured.</p>
When a layout-breaking change is required, a new versioned storage identifier can be introduced explicitly,
allowing existing storage layouts to remain untouched.
Any data migration, if needed, MUST be handled explicitly by the project.</p>
The primary consideration during adoption is identifier uniqueness.
New storage identifiers MUST NOT collide with existing identifiers from shared libraries or from within the project itself.</p>
Reference Implementation</h2>
Minimal implementation examples demonstrating the convention:</p>
Business Domain (Equipment)</strong></p>
    ///</span> @custom:storage</span>-location erc8042:org.project.business.equipment.v2</span></span>
    ///</span> @dev</span> Minimal form: project.equipment.v2</span></span>
    bytes32</span> constant</span> EQUIPMENT_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.business.equipment.v2"</span>)</span>;</span></span>
</span>
    struct</span> Equipment</span> </span></span>
    {</span></span>
        uint8</span> itemType</span>;</span>        </span></span>
        uint16</span> power</span>;</span></span>
        uint8</span> rarity</span>;</span></span>
        address</span> effectOwner</span>;</span>   </span></span>
    }</span></span>
</span>
    struct</span> EquipmentStorage</span> </span></span>
    {</span></span>
        mapping</span>(</span>uint256</span> =></span> Equipment</span>)</span> items</span>;</span> //</span> itemId => Equipment</span></span>
    }</span></span>
</span>
    function</span> equipmentStorage</span>(</span>)</span> pure</span> returns</span> (</span>EquipmentStorage</span> storage</span> s</span>)</span> </span></span>
    {</span></span>
        bytes32</span> position </span>=</span> EQUIPMENT_STORAGE_POSITION</span>;</span></span>
        assembly</span> {</span></span>
            s</span>.</span>slot </span>:=</span> position</span></span>
        }</span></span>
    }</span></span></code></pre>
Business Domain (Character)</strong></p>
    ///</span> @custom:storage</span>-location erc8042:org.project.business.character.v1</span></span>
    ///</span> @dev</span> Minimal form: project.character.v1</span></span>
    ///</span> @dev</span> Main character domain.</span></span>
    bytes32</span> constant</span> CHARACTER_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.business.character.v1"</span>)</span>;</span></span>
</span>
    struct</span> Character</span> </span></span>
    {</span></span>
        uint32</span> level</span>;</span></span>
        uint256</span> hp</span>;</span></span>
</span>
        //</span> equipment slot => itemId</span></span>
        //</span> e.g. slot: head, chest, weapon, boots...</span></span>
        mapping</span>(</span>uint8</span> =></span> uint256</span>)</span> equippedItemId</span>;</span></span>
    }</span></span>
</span>
    struct</span> CharacterStorage</span> </span></span>
    {</span></span>
        mapping</span>(</span>uint256</span> =></span> Character</span>)</span> characters</span>;</span></span>
    }</span></span>
</span>
    function</span> characterStorage</span>(</span>)</span> pure</span> returns</span> (</span>CharacterStorage</span> storage</span> s</span>)</span></span>
    {</span></span>
        bytes32</span> position </span>=</span> CHARACTER_STORAGE_POSITION</span>;</span></span>
        assembly</span> {</span></span>
            s</span>.</span>slot </span>:=</span> position</span></span>
        }</span></span>
    }</span></span>
</span>
    ///</span> @custom:storage</span>-location erc8042:org.project.business.character.v1.mounted</span></span>
    ///</span> @dev</span> Minimal form: project.character.v1.mounted</span></span>
    ///</span> @dev</span> Sub-domain for global character mounted state.</span></span>
    bytes32</span> constant</span> CHARACTER_MOUNTED_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.business.character.v1.mounted"</span>)</span>;</span></span>
</span>
    struct</span> CharacterMountedStorage</span> {</span></span>
        //</span> Global character state, persists across character switches</span></span>
        bool</span> isMounted</span>;</span></span>
    }</span></span>
</span>
    function</span> characterMountedStorage</span>(</span>)</span> pure</span> returns</span> (</span>CharacterMountedStorage</span> storage</span> s</span>)</span></span>
    {</span></span>
        bytes32</span> position </span>=</span>  CHARACTER_MOUNTED_STORAGE_POSITION</span>;</span></span>
        assembly</span> {</span></span>
            s</span>.</span>slot </span>:=</span> position</span></span>
        }</span></span>
    }</span></span></code></pre>
System Domain (Game Settings)</strong></p>
    ///</span> @custom:storage</span>-location erc8042:org.project.system.gamesettings</span></span>
    ///</span> @dev</span> Minimal form: project.gamesettings</span></span>
    bytes32</span> constant</span> GAME_SETTING_STORAGE_POSITION </span>=</span> keccak256</span>(</span>"org.project.system.gamesettings"</span>)</span>;</span></span>
</span>
    struct</span> GameSettingStorage</span> {</span></span>
        uint256</span> balancePatchBlock</span>;</span></span>
        bytes32</span> rulesetHash</span>;</span></span>
        uint32</span> gameVersion</span>;</span></span>
        uint32</span> seasonId</span>;</span></span>
        bool</span> tradingEnabled</span>;</span></span>
        bool</span> craftingEnabled</span>;</span></span>
        bool</span> pvpEnabled</span>;</span></span>
    }</span></span>
</span>
    function</span> gameSettingsStorage</span>(</span>)</span> pure</span> returns</span> (</span>GameSettingStorage</span> storage</span> s</span>)</span> {</span></span>
        bytes32</span> position </span>=</span> GAME_SETTING_STORAGE_POSITION</span>;</span></span>
        assembly</span> {</span></span>
            s</span>.</span>slot </span>:=</span> position</span></span>
        }</span></span>
    }</span></span></code></pre>
Each domain defines and owns its storage independently.
Facets interact with domain-owned storage definitions, supporting safe upgrades and avoiding unintended storage overlap.</p>
Security Considerations</h2>
This pattern strengthens the security model of Diamond-based systems by introducing explicit and deterministic storage identifiers.</p>
By separating domains and enforcing consistent naming rules, it reduces the risk of:</p>

Storage collisions between unrelated facets or upgrades.</li>
Human errors caused by inconsistent or reused identifiers.</li>
State corruption during upgrades or extensions.</li>
</ul>
Each domain owns its ERC-8042 storage identifier.
When combined with append-only storage layout upgrades, this allows storage evolution without interfering with existing state.</p>
This clarity also improves auditability and supports static analysis tooling when analyzing storage safety across upgrades.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


RWA Event-based Compliance Framework
2025-12-16T00:00:00+00:00
Abstract</h2>
This standard defines an event-based compliance framework for Real World Asset (RWA) tokens on ERC-20</a>, providing:</p>

A standardized entity classification system distinguishing between Compliance Entities (CE) and Decentralized Entities (DE)</li>
Event-driven compliance observation enabling auditability through standardized events and actual value flows, without enforcing hard transaction reverts</li>
</ol>
This standard is intentionally minimal and does not prescribe business-specific RWA workflows, off-chain settlement mechanisms, minting policies, or specific transfer patterns.</p>
Motivation</h2>
Real World Asset tokenization requires compliance observability that existing ERC-20</a> tokens do not provide:</p>
Missing Capabilities</h3>

Entity Classification</strong>: No standardized way to distinguish regulated corporate entities from decentralized participants</li>
Compliance Observability</strong>: No uniform event semantics for tracking compliance-relevant transfers</li>
Flexible Enforcement</strong>: Existing standards use hard reverts, making them incompatible with diverse regulatory frameworks</li>
</ol>
Why Event-Based?</h3>
This standard adopts an event-driven approach rather than enforcement through reverts:</p>

Regulatory Flexibility</strong>: Different jurisdictions can interpret the same events differently</li>
Adaptability</strong>: Compliance rules can evolve without contract upgrades</li>
Lower Costs</strong>: Events are cheaper than state-based enforcement</li>
</ul>
Specification</h2>
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.</p>
Definitions</h3>

Compliance Entity (CE)</strong>: An address representing a regulated legal entity (e.g., corporate treasury, custody account)</li>
Decentralized Entity (DE)</strong>: An address representing a decentralized participant (e.g., end users, routers, settlement contracts)</li>
BizID</strong>: A business correlation identifier (hash) linking related transfers to a single workflow</li>
Soft Policy</strong>: Compliance policy expressed through event labeling, not transaction reversion</li>
</ul>
Entity Registry</h3>
Compliant implementations MUST provide an entity classification registry that assigns each address to one of three categories.</p>
interface</span> IERC8106EntityRegistry</span> {</span></span>
    enum</span> EntityType</span> {</span> DECENTRALIZED_ENTITY</span>,</span> COMPLIANCE_ENTITY</span> }</span></span>
</span>
    event</span> EntityTypeUpdated</span>(</span></span>
        address</span> indexed</span> entity</span>,</span></span>
        EntityType</span> entityType</span>,</span></span>
        bytes32</span> indexed</span> reasonHash</span>,</span></span>
        address</span> indexed</span> operator</span></span>
    )</span>;</span></span>
</span>
    ///</span> @notice</span> Returns the entity type of an address</span></span>
    ///</span> @dev</span> MUST return DECENTRALIZED_ENTITY for addresses not explicitly registered as COMPLIANCE_ENTITY</span></span>
    function</span> entityTypeOf</span>(</span>address</span> entity</span>)</span> external</span> view</span> returns</span> (</span>EntityType</span>)</span>;</span></span>
}</span></span></code></pre>Registry Requirements</h4>
Implementations MUST satisfy the following requirements:</p>

Default Classification</strong>: The entityTypeOf</code> function MUST return DECENTRALIZED_ENTITY</code> for any address not explicitly registered as COMPLIANCE_ENTITY</code></li>
Explicit Registration</strong>: Only addresses explicitly registered SHOULD return COMPLIANCE_ENTITY</code></li>
Update Events</strong>: Entity type changes MUST emit EntityTypeUpdated</code> events</li>
Reason Tracking</strong>: The reasonHash</code> parameter MUST reference off-chain documentation (e.g., KYC records, legal entity registration)</li>
Operator Accountability</strong>: The operator</code> parameter MUST identify the address that authorized the update</li>
</ol>
Implementation Note</h4>
The registry MAY be:</p>

Embedded within the token contract itself</li>
Implemented as a separate contract referenced by the token</li>
Shared across multiple tokens within an ecosystem</li>
</ul>
Compliance Events</h3>
Compliant implementations MUST emit standardized events that capture compliance-relevant transfer information, including entity classifications, compliance flags, and business correlation identifiers.</p>
interface</span> IERC8106ComplianceEvents</span> is</span> IERC8106EntityRegistry</span> {</span></span>
    enum</span> ComplianceFlag</span> {</span></span>
        OK</span>,</span></span>
        DIRECT_DE_TO_CE</span>,</span>           //</span> DE -> CE observed</span></span>
        DIRECT_CE_TO_DE</span>,</span>           //</span> CE -> DE observed</span></span>
        POLICY_CUSTOM</span>              //</span> project-defined policy</span></span>
    }</span></span>
</span>
    event</span> ComplianceObserved</span>(</span></span>
        bytes32</span> indexed</span> bizId</span>,</span></span>
        address</span> indexed</span> token</span>,     </span>// </span>the</span> ERC</span>-</span>20</span> token</span> contract</span> address</span></span>
        address</span> indexed</span> from</span>,</span></span>
        address</span> to</span>,</span></span>
        uint256</span> amount</span>,</span></span>
        EntityType</span> fromType</span>,</span></span>
        EntityType</span> toType</span>,</span></span>
        ComplianceFlag</span> flag</span>,</span></span>
        bytes32</span> policyTag</span>          // </span>project</span>-</span>defined</span> categorization</span> tag</span></span>
    )</span>;</span></span>
}</span></span></code></pre>Event Requirements</h4>
Implementations MUST satisfy the following requirements:</p>

Complete Information</strong>: Each ComplianceObserved</code> event MUST include all specified parameters</li>
Accurate Classification</strong>: The fromType</code> and toType</code> MUST reflect the actual entity types at the time of the transfer</li>
Consistent BizID</strong>: All legs of a multi-leg transfer MUST use the same bizId</code> value</li>
Token Identification</strong>: The token</code> parameter MUST be the address of the ERC-20</a> token contract</li>
</ol>
Recommended Flagging Policy (Non-normative)</h4>
Implementations SHOULD apply the following flagging heuristics:</p>

DIRECT_DE_TO_CE</code>: When fromType == DECENTRALIZED_ENTITY</code> and toType == COMPLIANCE_ENTITY</code></li>
DIRECT_CE_TO_DE</code>: When fromType == COMPLIANCE_ENTITY</code> and toType == DECENTRALIZED_ENTITY</code></li>
OK</code>: When transfer does not cross compliance boundaries (DE↔DE or CE↔CE)</li>
POLICY_CUSTOM</code>: For project-specific compliance scenarios</li>
</ul>
Event-Based Compliance</h4>
Implementations SHOULD NOT revert transactions solely based on compliance flags. This event-based approach enables:</p>

Off-chain compliance review and decision-making</li>
Flexible interpretation across different regulatory jurisdictions</li>
Time-delayed enforcement where appropriate (e.g., 24-hour review periods)</li>
</ul>
Compliance actions (transaction reversals, account freezes, regulatory reporting) SHOULD be handled through separate mechanisms such as:</p>

Off-chain monitoring systems</li>
On-chain governance modules</li>
Dedicated compliance management contracts</li>
</ul>
Rationale</h2>
Event-Driven Model</h3>
Events rather than reverts because:</p>

Different jurisdictions can interpret events differently</li>
Cheaper than state-based enforcement (~2000 gas per event vs state writes)</li>
Enables time-delayed enforcement where appropriate</li>
</ul>
Soft Policy Flags</h3>
Compliance flags are informational, not enforced:</p>

Projects decide whether to revert based on flags</li>
Off-chain systems can alert, review, or freeze post-transaction</li>
Supports evolving regulations without contract changes</li>
</ul>
Auditability Design</h3>
Auditors reconstruct transaction flows using:</p>

Value Flows</strong>: Every ComplianceObserved</code> event corresponds to a real ERC-20</a> balance change</li>
Standardized Events</strong>: Uniform event structure for machine-readable compliance data</li>
BizID Correlation</strong>: Link multiple transfers to a single business transaction</li>
</ol>
For a given bizId</code>, auditors can query all ComplianceObserved</code> events, build directed graphs from from</code>/to</code>/amount</code> fields, check for direct CE/DE transfers using the flag</code> field, and cross-reference reasonHash</code> with off-chain KYC/AML systems.</p>
Reference Implementation</h2>
Implementation Patterns</h3>
Embedded Registry</strong>: Store entity types in the token contract itself</p>
contract</span> RWAToken</span> is</span> ERC20</span>, </span>IERC8106ComplianceEvents</span> {</span></span>
    mapping</span>(</span>address</span> =></span> bool</span>)</span> private</span> _isComplianceEntity</span>;</span></span>
    </span></span>
    function</span> entityTypeOf</span>(</span>address</span> entity</span>)</span> public</span> view</span> returns</span> (</span>EntityType</span>)</span> {</span></span>
        return</span> _isComplianceEntity</span>[</span>entity</span>]</span> </span></span>
            ?</span> EntityType</span>.</span>COMPLIANCE_ENTITY </span></span>
            :</span> EntityType</span>.</span>DECENTRALIZED_ENTITY</span>;</span></span>
    }</span></span>
    //</span> ...</span></span>
}</span></span></code></pre>
Separate Registry</strong>: Share registry across multiple tokens</p>
contract</span> EntityRegistry</span> is</span> IERC8106EntityRegistry</span> {</span></span>
    mapping</span>(</span>address</span> =></span> bool</span>)</span> private</span> _isComplianceEntity</span>;</span></span>
    </span></span>
    function</span> entityTypeOf</span>(</span>address</span> entity</span>)</span> external</span> view</span> returns</span> (</span>EntityType</span>)</span> {</span></span>
        return</span> _isComplianceEntity</span>[</span>entity</span>]</span></span>
            ?</span> EntityType</span>.</span>COMPLIANCE_ENTITY</span></span>
            :</span> EntityType</span>.</span>DECENTRALIZED_ENTITY</span>;</span></span>
    }</span></span>
    </span></span>
    function</span> registerComplianceEntity</span>(</span>address</span> entity</span>,</span> bytes32</span> reasonHash</span>)</span> external</span> onlyAdmin</span> {</span></span>
        _isComplianceEntity</span>[</span>entity</span>]</span> =</span> true</span>;</span></span>
        emit</span> EntityTypeUpdated</span>(</span>entity</span>,</span> EntityType</span>.</span>COMPLIANCE_ENTITY</span>,</span> reasonHash</span>,</span> msg.sender</span>)</span>;</span></span>
    }</span></span>
    //</span> ...</span></span>
}</span></span></code></pre>
Policy Tag Conventions</strong>: Use consistent hashes for interoperability</p>
bytes32</span> constant</span> TAG_PAYMENT </span>=</span> keccak256</span>(</span>"PAYMENT"</span>)</span>;</span></span>
bytes32</span> constant</span> TAG_TREASURY </span>=</span> keccak256</span>(</span>"TREASURY"</span>)</span>;</span></span>
bytes32</span> constant</span> TAG_REFUND </span>=</span> keccak256</span>(</span>"REFUND"</span>)</span>;</span></span></code></pre>Example Use Cases</h3>
Compliance Monitoring:</strong> A regulated stablecoin tracks all CE↔DE flows for monthly regulatory reports without blocking transactions.</p>
Atomic Multi-Leg Transfers:</strong> While not part of this standard, projects can build on these primitives to implement atomic multi-hop transfers:</p>
//</span> User pays → Treasury → Operational account (single transaction)</span></span>
function</span> purchaseRWA</span>(</span>bytes32</span> orderId</span>,</span> uint256</span> amount</span>)</span> external</span> {</span></span>
    //</span> Leg 1: DE → CE</span></span>
    token</span>.</span>transferFrom</span>(</span>msg.sender</span>,</span> treasury</span>,</span> amount</span>)</span>;</span></span>
    emit</span> ComplianceObserved</span>(</span>orderId</span>,</span> token</span>,</span> msg.sender</span>,</span> treasury</span>,</span> amount</span>,</span> </span></span>
                           DE</span>,</span> CE</span>,</span> DIRECT_DE_TO_CE</span>,</span> TAG_PAYMENT</span>)</span>;</span></span>
    </span></span>
    //</span> Leg 2: CE → CE</span></span>
    token</span>.</span>transferFrom</span>(</span>treasury</span>,</span> operational</span>,</span> amount</span>)</span>;</span></span>
    emit</span> ComplianceObserved</span>(</span>orderId</span>,</span> token</span>,</span> treasury</span>,</span> operational</span>,</span> amount</span>,</span></span>
                           CE</span>,</span> CE</span>,</span> OK</span>,</span> TAG_TREASURY</span>)</span>;</span></span>
}</span></span></code></pre>
This pattern enables single user-facing transactions, unified bizId</code> for audit correlation, and per-leg compliance events.</p>
Time-Delayed Enforcement:</strong> Detect suspicious patterns in events, then freeze accounts off-chain or via governance after review.</p>
Security Considerations</h2>
Event Integrity:</strong> Implementations MUST emit ComplianceObserved</code> events only after actual ERC-20</a> balance changes. Emitting events without value movement compromises auditability.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


ENS Trust Registry for Agent Coordination
2025-12-16T00:00:00+00:00
Abstract</h2>
This ERC defines a Trust Registry</strong> that enables agents to establish and query transitive trust relationships using ENS names as identifiers. Trust is expressed at four levels (Unknown, None, Marginal, Full) and propagates through signature chains following the GNU Privacy Guard (GnuPG) web of trust model.</p>
The registry serves as the trust and delegation module</strong> anticipated by ERC-8001</a>, enabling coordinators to gate participation based on trust graph proximity. An agent is considered valid from a coordinator's perspective if sufficient trust paths exist between them.</p>
This standard specifies trust attestation structures, the path verification algorithm, ENS integration semantics, and ERC-8001</a> coordination hooks.</p>
Motivation</h2>
ERC-8001</a> defines minimal primitives for multi-party agent coordination but explicitly defers trust to modules:</p>

"Privacy, thresholds, bonding, and cross-chain are left to modules."</p>
</blockquote>
And in Security Considerations:</p>

"Equivocation: A participant can sign conflicting intents. Mitigate with module-level slashing or reputation."</p>
</blockquote>
This ERC provides that trust and delegation module. Before coordinating, agents need answers to:</p>

"Should I include this agent in my coordination?"</strong> — Participant selection</li>
"Can I trust this agent's judgment about other agents?"</strong> — Transitive trust</li>
"How do I update trust based on coordination outcomes?"</strong> — Trust maintenance</li>
</ol>
Why Web of Trust?</h3>
The web of trust model, proven over 25+ years in GnuPG, solves the bootstrap problem: how do you establish trust with unknown agents without a centralised registrar?</p>
GnuPG Concept</th> This Standard</th></tr></thead>

Public key</td> ENS name</td></tr>
Key signing</td> Trust attestation</td></tr>
Owner trust levels</td> TrustLevel</code> enum</td></tr>
Key validity</td> Agent validity for coordination</td></tr>
Certification path</td> Trust chain through agents</td></tr>
</tbody></table>
Why ENS?</h3>
ENS provides a battle-tested, finalized identity layer:</p>

Stable identifiers</strong> that survive key rotation</li>
Ownership semantics</strong> via owner()</code> and isApprovedForAll()</code></li>
Human readable</strong> names (alice.agents.eth</code> not 0x742d...</code>)</li>
Subdomain delegation</strong> for protocol-issued agent identities</li>
</ul>
Using ENS avoids dependency on draft identity standards while remaining compatible with future standards through adapter patterns.</p>
Deployment note</strong>: This standard requires access to an ENS registry. On Ethereum mainnet, use the canonical ENS deployment. On other networks, use network-specific ENS deployments or bridges. CCIP-Read is a client-side mechanism and cannot be used for on-chain validation.</p>
Identity Continuity</h3>
ENS names are the identity. When an ENS name is transferred, the new owner inherits existing trust relationships where that name is the trustee. The new owner can manage trust where they are the trustor.</p>
Implementations SHOULD use short expiries (RECOMMENDED: 90 days maximum) for high-stakes scopes to limit exposure from name transfers. Agents SHOULD monitor Transfer</code> events on ENS names they trust and re-evaluate trust accordingly.</p>
Specification</h2>
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.</p>
Overview</h3>
This ERC specifies:</p>

Trust levels and their semantics</li>
ENS-indexed trust attestation structures with scope as key</li>
EIP-712</a> typed data for signing attestations</li>
EIP-1271</a> support for contract controllers</li>
The ITrustRegistry</code> interface</li>
Path verification algorithm</li>
ERC-8001</a> integration hooks</li>
</ul>
Trust Levels</h3>
Implementations MUST use the canonical enum:</p>
enum</span> TrustLevel</span> {</span></span>
   Unknown</span>,</span>   //</span> 0: No trust relationship established</span></span>
   None</span>,</span>      //</span> 1: Explicitly distrusted</span></span>
   Marginal</span>,</span>  //</span> 2: Partial trust — multiple required for validation</span></span>
   Full</span>       //</span> 3: Complete trust — single attestation sufficient</span></span>
}</span></span></code></pre>
Semantic definitions:</strong></p>
Level</th> Meaning</th> Validation Contribution</th></tr></thead>

Unknown</code></td> Default state; no data about agent</td> Cannot contribute to validation</td></tr>
None</code></td> Agent known to behave improperly</td> Explicitly excluded; voids trust paths containing this agent</td></tr>
Marginal</code></td> Agent generally trustworthy</td> Contributes to validation when minEdgeTrust <= Marginal</code></td></tr>
Full</code></td> Agent's judgment equals own verification</td> Always contributes to validation</td></tr>
</tbody></table>
Level transitions:</strong></p>

Any level MAY transition to any other level via a valid attestation with a higher nonce</li>
Transitioning from None</code> to Marginal</code> or Full</code> requires a new attestation (revocation is not permanent)</li>
</ul>
ENS Integration</h3>
The Trust Registry uses ENS namehashes as agent identifiers.</p>
//</span> ENS namehash computation (per ERC-137)</span></span>
bytes32</span> node </span>=</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span></span>
   keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>bytes32</span>(</span>0</span>)</span>,</span> keccak256</span>(</span>"eth"</span>)</span>)</span>)</span>,</span></span>
   keccak256</span>(</span>"alice"</span>)</span></span>
)</span>)</span>;</span></span>
//</span> node = namehash("alice.eth")</span></span></code></pre>Signature Authority</h3>
Trust attestations MUST be signed by an address with signing authority for the ENS name.</p>
Signing authority</strong> is limited to:</p>

The ENS name owner (ens.owner(node)</code>), OR</li>
For contract owners: any signer the contract validates via EIP-1271</a></li>
</ul>
Transaction submission</strong> (calling setTrust</code>, revokeTrust</code>, etc.) MAY be performed by:</p>

Any address holding a valid signature</li>
An approved operator (ens.isApprovedForAll(owner, operator)</code>) for revokeTrust</code> only</li>
</ul>
This separation ensures:</p>

Attestations are cryptographically bound to the ENS owner/controller</li>
Transaction submission can be delegated (relayers, operators)</li>
Approvals cannot be used to forge signatures</li>
</ul>
///</span> @dev</span> Verify signature - signing authority is ENS owner only</span></span>
   function</span> verifySignature</span>(</span></span>
      bytes32</span> node</span>,</span></span>
      bytes32</span> digest</span>,</span></span>
      bytes</span> calldata</span> signature</span></span>
   )</span> internal</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span>
      address</span> owner </span>=</span> ens</span>.</span>owner</span>(</span>node</span>)</span>;</span></span>
      if</span> (</span>owner </span>==</span> address</span>(</span>0</span>)</span>)</span> return</span> false</span>;</span></span>
</span>
      //</span> EOA owner</span></span>
      if</span> (</span>owner</span>.</span>code</span>.</span>length </span>==</span> 0</span>)</span> {</span></span>
         return</span> ECDSA</span>.</span>recover</span>(</span>digest</span>,</span> signature</span>)</span> ==</span> owner</span>;</span></span>
      }</span></span>
</span>
      //</span> Contract owner - delegate to EIP-1271</span></span>
      try</span> IERC1271</span>(</span>owner</span>)</span>.</span>isValidSignature</span>(</span>digest</span>,</span> signature</span>)</span> returns</span> (</span>bytes4</span> magic</span>)</span> {</span></span>
         return</span> magic </span>==</span> IERC1271</span>.</span>isValidSignature</span>.</span>selector</span>;</span></span>
      }</span> catch</span> {</span></span>
         return</span> false</span>;</span></span>
      }</span></span>
   }</span></span>
</span>
///</span> @dev</span> Check if caller can submit revokeTrust transaction</span></span>
   function</span> canSubmitRevocation</span>(</span>bytes32</span> node</span>,</span> address</span> caller</span>)</span> internal</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span>
      address</span> owner </span>=</span> ens</span>.</span>owner</span>(</span>node</span>)</span>;</span></span>
      return</span> caller </span>==</span> owner </span>||</span> ens</span>.</span>isApprovedForAll</span>(</span>owner</span>,</span> caller</span>)</span>;</span></span>
   }</span></span></code></pre>EIP-712 Domain</h3>
Implementations MUST use the following EIP-712</a> domain:</p>
EIP712Domain</span>(</span>{</span></span>
   name</span>:</span> "TrustRegistry"</span>,</span></span>
   version</span>:</span> "1"</span>,</span></span>
   chainId</span>:</span> block</span>.</span>chainid</span>,</span></span>
   verifyingContract</span>:</span> address</span>(</span>this</span>)</span></span>
}</span>)</span></span></code></pre>
Implementations SHOULD expose the domain via EIP-5267</a>.</p>
Primary Types</h3>
struct</span> TrustAttestation</span> {</span></span>
   bytes32</span> trustorNode</span>;</span>       //</span> ENS namehash of trustor</span></span>
   bytes32</span> trusteeNode</span>;</span>       //</span> ENS namehash of trustee</span></span>
   TrustLevel level</span>;</span>          //</span> Trust level assigned</span></span>
   bytes32</span> scope</span>;</span>             //</span> Scope restriction; bytes32(0) = universal</span></span>
   uint64</span> expiry</span>;</span>             //</span> Unix timestamp; 0 = no expiry</span></span>
   uint64</span> nonce</span>;</span>              //</span> Per-trustor monotonic nonce</span></span>
}</span></span>
</span>
   struct</span> ValidationParams</span> {</span></span>
      uint8</span> maxPathLength</span>;</span>       //</span> Maximum trust chain depth (1-10)</span></span>
      TrustLevel minEdgeTrust</span>;</span>   //</span> Minimum trust level required on each edge</span></span>
      bytes32</span> scope</span>;</span>             //</span> Required scope; bytes32(0) = any</span></span>
      bool</span> enforceExpiry</span>;</span>        //</span> Check expiry on all chain elements</span></span>
      bytes32</span>[</span>]</span> requiredAnchors</span>;</span> //</span> Path MUST traverse at least one anchor; empty = no requirement</span></span>
   }</span></span>
</span>
   struct</span> TrustPath</span> {</span></span>
      bytes32</span>[</span>]</span> nodes</span>;</span>           //</span> [validator, ...intermediaries..., target]</span></span>
   }</span></span></code></pre>
Path length definition</strong>: Path length is the number of edges (trust relationships) in the path. A direct trust relationship has path length 1. A path [A, B, C]</code> has length 2.</p>
Default Validation Parameters</h4>
When not specified, implementations SHOULD use:</p>
ValidationParams</span>(</span>{</span></span>
   maxPathLength</span>:</span> 5</span>,</span></span>
   minEdgeTrust</span>:</span> TrustLevel</span>.</span>Marginal</span>,</span></span>
   scope</span>:</span> bytes32</span>(</span>0</span>)</span>,</span></span>
   enforceExpiry</span>:</span> true</span>,</span></span>
   requiredAnchors</span>:</span> new</span> bytes32</span>[](</span>0</span>)</span></span>
}</span>)</span></span></code></pre>Validation Parameters Constraints</h4>
Implementations MUST reject ValidationParams</code> where:</p>

maxPathLength == 0</code> or maxPathLength > 10</code></li>
minEdgeTrust == TrustLevel.Unknown</code> or minEdgeTrust == TrustLevel.None</code></li>
requiredAnchors.length > 10</code></li>
</ul>
Typed Data Hashes</h3>
bytes32</span> constant</span> TRUST_ATTESTATION_TYPEHASH </span>=</span> keccak256</span>(</span></span>
   "TrustAttestation(bytes32 trustorNode,bytes32 trusteeNode,uint8 level,bytes32 scope,uint64 expiry,uint64 nonce)"</span></span>
)</span>;</span></span>
</span>
   function</span> hashAttestation</span>(</span>TrustAttestation</span> calldata</span> att</span>)</span> internal</span> pure</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
      return</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span>
         TRUST_ATTESTATION_TYPEHASH</span>,</span></span>
         att</span>.</span>trustorNode</span>,</span></span>
         att</span>.</span>trusteeNode</span>,</span></span>
         uint8</span>(</span>att</span>.</span>level</span>)</span>,</span></span>
         att</span>.</span>scope</span>,</span></span>
         att</span>.</span>expiry</span>,</span></span>
         att</span>.</span>nonce</span></span>
      )</span>)</span>;</span></span>
   }</span></span></code></pre>Interface</h3>
Implementations MUST expose the following interface:</p>
interface</span> ITrustRegistry</span> {</span></span>
   //</span> ═══════════════════════════════════════════════════════════════════</span></span>
   //</span> Events</span></span>
   //</span> ═══════════════════════════════════════════════════════════════════</span></span>
</span>
   ///</span> @notice</span> Emitted when trust is set or updated</span></span>
   event</span> TrustSet</span>(</span></span>
      bytes32</span> indexed</span> trustorNode</span>,</span></span>
      bytes32</span> indexed</span> trusteeNode</span>,</span></span>
      TrustLevel</span> level</span>,</span></span>
      bytes32</span> indexed</span> scope</span>,</span></span>
      uint64</span> expiry</span></span>
   )</span>;</span></span>
</span>
   ///</span> @notice</span> Emitted when trust is explicitly revoked</span></span>
   event</span> TrustRevoked</span>(</span></span>
      bytes32</span> indexed</span> trustorNode</span>,</span></span>
      bytes32</span> indexed</span> trusteeNode</span>,</span></span>
      bytes32</span> indexed</span> scope</span>,</span></span>
      bytes32</span> reasonCode</span></span>
   )</span>;</span></span>
</span>
   ///</span> @notice</span> Emitted when an identity gate is configured</span></span>
   event</span> IdentityGateSet</span>(</span></span>
      bytes32</span> indexed</span> coordinationType</span>,</span></span>
      bytes32</span> indexed</span> gatekeeperNode</span>,</span></span>
      uint8</span> maxPathLength</span>,</span></span>
      TrustLevel</span> minEdgeTrust</span></span>
   )</span>;</span></span>
</span>
   ///</span> @notice</span> Emitted when an identity gate is removed</span></span>
   event</span> IdentityGateRemoved</span>(</span>bytes32</span> indexed</span> coordinationType</span>)</span>;</span></span>
</span>
   //</span> ═══════════════════════════════════════════════════════════════════</span></span>
   //</span> Trust Management</span></span>
   //</span> ═══════════════════════════════════════════════════════════════════</span></span>
</span>
   ///</span> @notice</span> Set trust level for another agent in a specific scope</span></span>
   ///</span> @dev</span> Signature MUST be from ENS owner (EOA) or validate via EIP-1271 (contract)</span></span>
   ///</span> @param</span> attestation</span> The trust attestation</span></span>
   ///</span> @param</span> signature</span> EIP-712 signature from trustor's ENS owner</span></span>
   function</span> setTrust</span>(</span></span>
      TrustAttestation</span> calldata</span> attestation</span>,</span></span>
      bytes</span> calldata</span> signature</span></span>
   )</span> external</span>;</span></span>
</span>
   ///</span> @notice</span> Batch set multiple trust relationships</span></span>
   ///</span> @dev</span> All attestations MUST share the same trustorNode</span></span>
   ///</span> @param</span> attestations</span> Array of trust attestations</span></span>
   ///</span> @param</span> signatures</span> Corresponding signatures</span></span>
   function</span> setTrustBatch</span>(</span></span>
      TrustAttestation</span>[</span>]</span> calldata</span> attestations</span>,</span></span>
      bytes</span>[</span>]</span> calldata</span> signatures</span></span>
   )</span> external</span>;</span></span>
</span>
   ///</span> @notice</span> Revoke trust (sets level to None)</span></span>
   ///</span> @dev</span> Caller MUST be ENS owner or approved operator</span></span>
   ///</span> @param</span> trustorNode</span> The trustor's ENS namehash</span></span>
   ///</span> @param</span> trusteeNode</span> The agent to revoke trust from</span></span>
   ///</span> @param</span> scope</span> The scope to revoke trust in</span></span>
   ///</span> @param</span> reasonCode</span> Reason code for revocation</span></span>
   function</span> revokeTrust</span>(</span></span>
      bytes32</span> trustorNode</span>,</span></span>
      bytes32</span> trusteeNode</span>,</span></span>
      bytes32</span> scope</span>,</span></span>
      bytes32</span> reasonCode</span></span>
   )</span> external</span>;</span></span>
</span>
   ///</span> @notice</span> Get trust record between two agents in a specific scope</span></span>
   ///</span> @param</span> trustorNode</span> The trusting agent</span></span>
   ///</span> @param</span> trusteeNode</span> The trusted agent</span></span>
   ///</span> @param</span> scope</span> The trust scope (bytes32(0) for universal)</span></span>
   ///</span> @return</span> level</span> Current trust level</span></span>
   ///</span> @return</span> expiry</span> Expiration timestamp (0 = never)</span></span>
   function</span> getTrust</span>(</span></span>
      bytes32</span> trustorNode</span>,</span></span>
      bytes32</span> trusteeNode</span>,</span></span>
      bytes32</span> scope</span></span>
   )</span> external</span> view</span> returns</span> (</span>TrustLevel</span> level</span>,</span> uint64</span> expiry</span>)</span>;</span></span>
</span>
   ///</span> @notice</span> Get current nonce for a trustor</span></span>
   ///</span> @param</span> trustorNode</span> The agent's ENS namehash</span></span>
   ///</span> @return</span> Current</span> nonce value</span></span>
   function</span> getNonce</span>(</span>bytes32</span> trustorNode</span>)</span> external</span> view</span> returns</span> (</span>uint64</span>)</span>;</span></span>
</span>
   //</span> ═══════════════════════════════════════════════════════════════════</span></span>
   //</span> Path Verification</span></span>
   //</span> ═══════════════════════════════════════════════════════════════════</span></span>
</span>
   ///</span> @notice</span> Verify a pre-computed trust path</span></span>
   ///</span> @param</span> path</span> The trust path to verify</span></span>
   ///</span> @param</span> params</span> Validation parameters</span></span>
   ///</span> @return</span> valid</span> Whether the path satisfies validation requirements</span></span>
   ///</span> @return</span> anchorSatisfied</span> Whether requiredAnchors constraint is met</span></span>
   function</span> verifyPath</span>(</span></span>
      TrustPath</span> calldata</span> path</span>,</span></span>
      ValidationParams</span> calldata</span> params</span></span>
   )</span> external</span> view</span> returns</span> (</span>bool</span> valid</span>,</span> bool</span> anchorSatisfied</span>)</span>;</span></span>
</span>
   //</span> ═══════════════════════════════════════════════════════════════════</span></span>
   //</span> ERC-8001 Integration</span></span>
   //</span> ═══════════════════════════════════════════════════════════════════</span></span>
</span>
   ///</span> @notice</span> Set identity gate for a coordination type</span></span>
   ///</span> @param</span> coordinationType</span> The ERC-8001 coordination type</span></span>
   ///</span> @param</span> gatekeeperNode</span> Agent whose trust graph gates entry</span></span>
   ///</span> @param</span> params</span> Validation parameters for the gate</span></span>
   function</span> setIdentityGate</span>(</span></span>
      bytes32</span> coordinationType</span>,</span></span>
      bytes32</span> gatekeeperNode</span>,</span></span>
      ValidationParams</span> calldata</span> params</span></span>
   )</span> external</span>;</span></span>
</span>
   ///</span> @notice</span> Remove identity gate for a coordination type</span></span>
   ///</span> @param</span> coordinationType</span> The ERC-8001 coordination type</span></span>
   function</span> removeIdentityGate</span>(</span>bytes32</span> coordinationType</span>)</span> external</span>;</span></span>
</span>
   ///</span> @notice</span> Get identity gate configuration</span></span>
   ///</span> @param</span> coordinationType</span> The ERC-8001 coordination type</span></span>
   ///</span> @return</span> gatekeeperNode</span> The gatekeeper agent</span></span>
   ///</span> @return</span> params</span> Validation parameters</span></span>
   ///</span> @return</span> enabled</span> Whether the gate is active</span></span>
   function</span> getIdentityGate</span>(</span></span>
      bytes32</span> coordinationType</span></span>
   )</span> external</span> view</span> returns</span> (</span></span>
      bytes32</span> gatekeeperNode</span>,</span></span>
      ValidationParams</span> memory</span> params</span>,</span></span>
      bool</span> enabled</span></span>
   )</span>;</span></span>
</span>
   ///</span> @notice</span> Validate participant using pre-computed path</span></span>
   ///</span> @param</span> coordinationType</span> The ERC-8001 coordination type</span></span>
   ///</span> @param</span> path</span> Pre-computed trust path from gatekeeper to participant</span></span>
   ///</span> @return</span> isValid</span> Whether participant passes the gate</span></span>
   function</span> validateParticipantWithPath</span>(</span></span>
      bytes32</span> coordinationType</span>,</span></span>
      TrustPath</span> calldata</span> path</span></span>
   )</span> external</span> view</span> returns</span> (</span>bool</span> isValid</span>)</span>;</span></span>
}</span></span></code></pre>OPTIONAL Interface Extensions</h3>
The following functions are OPTIONAL. Implementations MAY include them but they are not required for compliance:</p>
interface</span> ITrustRegistryExtended</span> is</span> ITrustRegistry</span> {</span></span>
   ///</span> @notice</span> Get agents trusted by a given agent (paginated)</span></span>
   ///</span> @dev</span> OPTIONAL - useful for indexing but not required</span></span>
   function</span> getTrustees</span>(</span></span>
      bytes32</span> trustorNode</span>,</span></span>
      TrustLevel</span> minLevel</span>,</span></span>
      bytes32</span> scope</span>,</span></span>
      uint256</span> offset</span>,</span></span>
      uint256</span> limit</span></span>
   )</span> external</span> view</span> returns</span> (</span>bytes32</span>[</span>]</span> memory</span> trustees</span>,</span> uint256</span> total</span>)</span>;</span></span>
</span>
   ///</span> @notice</span> Get agents that trust a given agent (paginated)</span></span>
   ///</span> @dev</span> OPTIONAL - useful for indexing but not required</span></span>
   function</span> getTrustors</span>(</span></span>
      bytes32</span> trusteeNode</span>,</span></span>
      TrustLevel</span> minLevel</span>,</span></span>
      bytes32</span> scope</span>,</span></span>
      uint256</span> offset</span>,</span></span>
      uint256</span> limit</span></span>
   )</span> external</span> view</span> returns</span> (</span>bytes32</span>[</span>]</span> memory</span> trustors</span>,</span> uint256</span> total</span>)</span>;</span></span>
</span>
   ///</span> @notice</span> Validate an agent through on-chain graph traversal</span></span>
   ///</span> @dev</span> OPTIONAL - expensive, prefer off-chain computation with verifyPath</span></span>
   ///</span> @param</span> validatorNode</span> The validating agent's perspective</span></span>
   ///</span> @param</span> targetNode</span> The agent to validate</span></span>
   ///</span> @param</span> params</span> Validation parameters</span></span>
   ///</span> @param</span> marginalThreshold</span> Number of marginal attestations required (for accumulation)</span></span>
   ///</span> @param</span> fullThreshold</span> Number of full attestations required</span></span>
   function</span> validateAgent</span>(</span></span>
      bytes32</span> validatorNode</span>,</span></span>
      bytes32</span> targetNode</span>,</span></span>
      ValidationParams</span> calldata</span> params</span>,</span></span>
      uint8</span> marginalThreshold</span>,</span></span>
      uint8</span> fullThreshold</span></span>
   )</span> external</span> view</span> returns</span> (</span></span>
      bool</span> isValid</span>,</span></span>
      uint8</span> pathLength</span>,</span></span>
      uint8</span> marginalCount</span>,</span></span>
      uint8</span> fullCount</span></span>
   )</span>;</span></span>
</span>
   ///</span> @notice</span> Check if any trust path exists</span></span>
   ///</span> @dev</span> OPTIONAL - expensive, prefer off-chain computation</span></span>
   function</span> pathExists</span>(</span></span>
      bytes32</span> fromNode</span>,</span></span>
      bytes32</span> toNode</span>,</span></span>
      uint8</span> maxDepth</span></span>
   )</span> external</span> view</span> returns</span> (</span>bool</span> exists</span>,</span> uint8</span> depth</span>)</span>;</span></span>
</span>
   ///</span> @notice</span> Validate participant without pre-computed path</span></span>
   ///</span> @dev</span> OPTIONAL - expensive, prefer validateParticipantWithPath</span></span>
   function</span> validateParticipant</span>(</span></span>
      bytes32</span> coordinationType</span>,</span></span>
      bytes32</span> participantNode</span>,</span></span>
      uint8</span> marginalThreshold</span>,</span></span>
      uint8</span> fullThreshold</span></span>
   )</span> external</span> view</span> returns</span> (</span>bool</span> isValid</span>)</span>;</span></span>
}</span></span></code></pre>Semantics</h3>
setTrust</code></h4>
setTrust</code> MUST revert if:</p>

attestation.trustorNode == attestation.trusteeNode</code> (self-trust prohibited)</li>
attestation.nonce <= getNonce(attestation.trustorNode)</code></li>
attestation.expiry != 0 && attestation.expiry <= block.timestamp</code></li>
The signature does not verify per the Signature Authority section</li>
The ENS name for trustorNode</code> does not exist (owner is zero address)</li>
</ul>
If valid:</p>

The trust record MUST be stored, keyed by (trustorNode, trusteeNode, scope)</code></li>
getNonce(trustorNode)</code> MUST return the attestation's nonce</li>
TrustSet</code> MUST be emitted</li>
</ul>
setTrustBatch</code></h4>
setTrustBatch</code> MUST revert if:</p>

attestations.length != signatures.length</code></li>
Any attestation has a different trustorNode</code> than the first attestation</li>
Any individual attestation would fail setTrust</code> validation</li>
</ul>
Nonces within the batch MUST be strictly increasing.</p>
revokeTrust</code></h4>
revokeTrust</code> MUST revert if:</p>

Caller is not the ENS owner or an approved operator for trustorNode</code></li>
No existing trust relationship exists for (trustorNode, trusteeNode, scope)</code> (level is Unknown</code>)</li>
</ul>
If valid:</p>

Trust level MUST be set to None</code></li>
TrustRevoked</code> MUST be emitted</li>
The relationship MUST remain in storage (not deleted) to preserve the explicit distrust</li>
</ul>
verifyPath</code> — Path Verification Algorithm</h4>
verifyPath</code> validates a pre-computed trust path.</p>
Algorithm:</strong></p>
function</span> verifyPath</span>(</span></span>
   TrustPath</span> calldata</span> path</span>,</span></span>
   ValidationParams</span> calldata</span> params</span></span>
)</span> external</span> view</span> returns</span> (</span>bool</span> valid</span>,</span> bool</span> anchorSatisfied</span>)</span> {</span></span>
   //</span> Path must have at least 2 nodes (validator and target)</span></span>
   if</span> (</span>path</span>.</span>nodes</span>.</span>length </span><</span> 2</span>)</span> return</span> (</span>false</span>,</span> false</span>)</span>;</span></span>
</span>
   //</span> Path length constraint (edges = nodes - 1)</span></span>
   if</span> (</span>path</span>.</span>nodes</span>.</span>length </span>-</span> 1</span> ></span> params</span>.</span>maxPathLength</span>)</span> return</span> (</span>false</span>,</span> false</span>)</span>;</span></span>
</span>
   //</span> Track anchor satisfaction</span></span>
   bool</span> foundAnchor </span>=</span> params</span>.</span>requiredAnchors</span>.</span>length </span>==</span> 0</span>;</span></span>
</span>
   //</span> Verify each edge</span></span>
   for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> path</span>.</span>nodes</span>.</span>length </span>-</span> 1</span>;</span> i</span>+</span>+</span>)</span> {</span></span>
      //</span> Try scoped trust first, fall back to universal</span></span>
      (</span>TrustLevel level</span>,</span> uint64</span> expiry</span>)</span> =</span> getTrust</span>(</span></span>
         path</span>.</span>nodes</span>[</span>i</span>]</span>,</span></span>
         path</span>.</span>nodes</span>[</span>i </span>+</span> 1</span>]</span>,</span></span>
         params</span>.</span>scope</span></span>
      )</span>;</span></span>
</span>
      //</span> Fall back to universal scope if scoped trust not found</span></span>
      if</span> (</span>level </span>==</span> TrustLevel</span>.</span>Unknown </span>&&</span> params</span>.</span>scope </span>!=</span> bytes32</span>(</span>0</span>)</span>)</span> {</span></span>
         (</span>level</span>,</span> expiry</span>)</span> =</span> getTrust</span>(</span></span>
            path</span>.</span>nodes</span>[</span>i</span>]</span>,</span></span>
            path</span>.</span>nodes</span>[</span>i </span>+</span> 1</span>]</span>,</span></span>
            bytes32</span>(</span>0</span>)</span></span>
         )</span>;</span></span>
      }</span></span>
</span>
      //</span> Edge must meet minimum trust level</span></span>
      if</span> (</span>level </span><</span> params</span>.</span>minEdgeTrust</span>)</span> return</span> (</span>false</span>,</span> foundAnchor</span>)</span>;</span></span>
</span>
      //</span> None explicitly voids (even if minEdgeTrust is somehow None)</span></span>
      if</span> (</span>level </span>==</span> TrustLevel</span>.</span>None</span>)</span> return</span> (</span>false</span>,</span> foundAnchor</span>)</span>;</span></span>
</span>
      //</span> Expiry check</span></span>
      if</span> (</span>params</span>.</span>enforceExpiry </span>&&</span> expiry </span>!=</span> 0</span> &&</span> expiry </span><</span>=</span> block</span>.</span>timestamp</span>)</span> {</span></span>
         return</span> (</span>false</span>,</span> foundAnchor</span>)</span>;</span></span>
      }</span></span>
</span>
      //</span> Anchor check (intermediate nodes only, not first or last)</span></span>
      if</span> (</span>!</span>foundAnchor </span>&&</span> i </span>></span> 0</span>)</span> {</span></span>
         for</span> (</span>uint256</span> j </span>=</span> 0</span>;</span> j </span><</span> params</span>.</span>requiredAnchors</span>.</span>length</span>;</span> j</span>+</span>+</span>)</span> {</span></span>
            if</span> (</span>path</span>.</span>nodes</span>[</span>i</span>]</span> ==</span> params</span>.</span>requiredAnchors</span>[</span>j</span>]</span>)</span> {</span></span>
               foundAnchor </span>=</span> true</span>;</span></span>
               break</span>;</span></span>
            }</span></span>
         }</span></span>
      }</span></span>
   }</span></span>
</span>
   return</span> (</span>true</span>,</span> foundAnchor</span>)</span>;</span></span>
}</span></span></code></pre>
Scope fallback semantics:</strong></p>
When validating an edge, implementations MUST:</p>

First check for trust at the specified params.scope</code></li>
If not found and params.scope != bytes32(0)</code>, check for trust at universal scope bytes32(0)</code></li>
Universal trust applies to all scopes</li>
</ol>
validateParticipantWithPath</code></h4>
This function gates ERC-8001</a> coordination participation.</p>
function</span> validateParticipantWithPath</span>(</span></span>
   bytes32</span> coordinationType</span>,</span></span>
   TrustPath</span> calldata</span> path</span></span>
)</span> external</span> view</span> returns</span> (</span>bool</span> isValid</span>)</span> {</span></span>
   (</span>bytes32</span> gatekeeperNode</span>,</span> ValidationParams </span>memory</span> params</span>,</span> bool</span> enabled</span>)</span> =</span></span>
               getIdentityGate</span>(</span>coordinationType</span>)</span>;</span></span>
</span>
   if</span> (</span>!</span>enabled</span>)</span> return</span> true</span>;</span> //</span> No gate = open participation</span></span>
</span>
   //</span> Verify path starts at gatekeeper and ends at participant</span></span>
   if</span> (</span>path</span>.</span>nodes</span>.</span>length </span><</span> 2</span>)</span> return</span> false</span>;</span></span>
   if</span> (</span>path</span>.</span>nodes</span>[</span>0</span>]</span> !=</span> gatekeeperNode</span>)</span> return</span> false</span>;</span></span>
</span>
   (</span>bool</span> valid</span>,</span> bool</span> anchorOk</span>)</span> =</span> verifyPath</span>(</span>path</span>,</span> params</span>)</span>;</span></span>
   return</span> valid </span>&&</span> anchorOk</span>;</span></span>
}</span></span></code></pre>Errors</h3>
Implementations MUST revert with these errors:</p>
error</span> SelfTrustProhibited</span>(</span>)</span>;</span></span>
   error</span> NonceTooLow</span>(</span>uint64</span> provided</span>,</span> uint64</span> required</span>)</span>;</span></span>
   error</span> AttestationExpired</span>(</span>uint64</span> expiry</span>,</span> uint64</span> currentTime</span>)</span>;</span></span>
   error</span> InvalidSignature</span>(</span>)</span>;</span></span>
   error</span> NotAuthorized</span>(</span>bytes32</span> node</span>,</span> address</span> actor</span>)</span>;</span></span>
   error</span> ENSNameNotFound</span>(</span>bytes32</span> node</span>)</span>;</span></span>
   error</span> TrustNotFound</span>(</span>bytes32</span> trustorNode</span>,</span> bytes32</span> trusteeNode</span>,</span> bytes32</span> scope</span>)</span>;</span></span>
   error</span> GateNotFound</span>(</span>bytes32</span> coordinationType</span>)</span>;</span></span>
   error</span> InvalidValidationParams</span>(</span>string</span> reason</span>)</span>;</span></span>
   error</span> BatchTrustorMismatch</span>(</span>)</span>;</span></span>
   error</span> BatchNonceNotIncreasing</span>(</span>)</span>;</span></span></code></pre>Recommended Reason Codes</h3>
For TrustRevoked</code> events, the following reason codes are RECOMMENDED:</p>
Reason Code</th> Value</th> Meaning</th></tr></thead>

Unspecified</td> bytes32(0)</code></td> No specific reason</td></tr>
Misbehavior</td> keccak256("MISBEHAVIOR")</code></td> Agent acted improperly</td></tr>
Compromised</td> keccak256("COMPROMISED")</code></td> Key or account compromised</td></tr>
Inactive</td> keccak256("INACTIVE")</code></td> Agent no longer active</td></tr>
Transfer</td> keccak256("TRANSFER")</code></td> ENS name transferred</td></tr>
</tbody></table>
Recommended Scopes</h3>
For interoperability, the following scope values are RECOMMENDED:</p>
Scope</th> Value</th> Use Case</th></tr></thead>

Universal</td> bytes32(0)</code></td> Trust applies to all contexts</td></tr>
DeFi</td> keccak256("DEFI")</code></td> DeFi coordination</td></tr>
Gaming</td> keccak256("GAMING")</code></td> Gaming/metaverse</td></tr>
MEV</td> keccak256("MEV")</code></td> MEV protection</td></tr>
Commerce</td> keccak256("COMMERCE")</code></td> Agentic commerce</td></tr>
</tbody></table>
Recommended Coordination Types</h3>
For ERC-8001</a> identity gates:</p>
Coordination Type</th> Value</th></tr></thead>

MEV Coordination</td> keccak256("MEV_COORDINATION")</code></td></tr>
DeFi Yield</td> keccak256("DEFI_YIELD")</code></td></tr>
Gaming Match</td> keccak256("GAMING_MATCH")</code></td></tr>
Commerce Escrow</td> keccak256("COMMERCE_ESCROW")</code></td></tr>
</tbody></table>
Rationale</h2>
Why ENS Instead of a New Identity System?</h3>
ENS is finalised EIP-137</a>, battle-tested, and widely adopted. Creating a new identity system would:</p>

Add dependency on draft standards</li>
Fragment the identity ecosystem</li>
Require new adoption efforts</li>
</ul>
ENS provides everything needed: stable identifiers, ownership semantics, and extensibility.</p>
Why Scope as Storage Key?</h3>
A trustor may have different trust levels for the same trustee in different contexts. For example:</p>

Trust bob.eth</code> fully for DeFi coordination</li>
Trust bob.eth</code> marginally for gaming</li>
</ul>
Making scope part of the storage key (trustorNode, trusteeNode, scope)</code> enables this naturally. Universal trust bytes32(0)</code> serves as a fallback when scoped trust is not specified.</p>
Why minEdgeTrust Instead of Marginal/Full Thresholds?</h3>
The marginalThreshold</code> and fullThreshold</code> parameters were designed for on-chain graph traversal with marginal accumulation logic. Since on-chain traversal is OPTIONAL (expensive, DoS-prone), and the core primitive is verifyPath</code>, we need only specify the minimum trust level each edge must have.</p>
This simplification:</p>

Reduces parameter complexity</li>
Makes path verification straightforward</li>
Leaves accumulation semantics to OPTIONAL extensions</li>
</ul>
For use cases requiring marginal accumulation, the OPTIONAL validateAgent</code> extension accepts threshold parameters.</p>
Why Separate Signing Authority from Transaction Submission?</h3>
ENS approvals (isApprovedForAll</code>) are designed for operators to manage names on behalf of owners. However, allowing approved operators to forge attestation signatures would break the cryptographic binding between attestations and ENS owners.</p>
By restricting signing authority to the ENS owner (or EIP-1271 for contract owners) while allowing operators to submit transactions like revokeTrust</code>, we preserve:</p>

Cryptographic integrity of attestations</li>
Operational flexibility for name management</li>
Clear security boundaries</li>
</ul>
Why verifyPath Only (No On-Chain Search)?</h3>
On-chain graph traversal is expensive and creates DoS vectors:</p>

Branching factor can explode with user-controlled adjacency lists</li>
Gas costs are unpredictable</li>
Attackers can bloat trustee lists</li>
</ul>
By requiring pre-computed paths, this standard:</p>

Keeps on-chain verification O(path length)</li>
Pushes search complexity to off-chain indexers where it belongs</li>
Enables predictable gas costs</li>
</ul>
Implementations MAY add validateAgent</code> and pathExists</code> as OPTIONAL extensions, but these are not required for compliance.</p>
Why Four Trust Levels?</h3>
The four-level model (Unknown, None, Marginal, Full) is proven by GnuPG's 25+ years of use. Finer granularity adds complexity without clear benefit; coarser granularity loses important distinctions.</p>
With minEdgeTrust</code>, applications can choose their security posture:</p>

minEdgeTrust: Full</code> — Only fully trusted paths</li>
minEdgeTrust: Marginal</code> — Accept marginal trust (default)</li>
</ul>
Why Required Anchors?</h3>
Sybil attacks are the primary threat to web of trust systems. Required anchors force trust paths to traverse established community nodes (DAOs, protocols, auditors), transforming Sybil resistance from application-layer advice into protocol-level enforcement.</p>
Backwards Compatibility</h2>
This ERC introduces new functionality and does not modify existing standards.</p>
ENS Compatibility</strong>: Uses standard ENS interfaces (owner</code>, isApprovedForAll</code>). Works with any ENS deployment. Does not rely on CCIP-Read or other off-chain mechanisms.</p>
ERC-8001 Compatibility</strong>: Designed as a module. ERC-8001 coordinators can optionally integrate identity gates.</p>
Wallet Compatibility</strong>: Uses EIP-712</a> signatures, compatible with all major wallets. Supports EIP-1271</a> for contract wallets and smart accounts.</p>
Reference Implementation</h2>
See contracts/TrustRegistry.sol</code></a> for the complete implementation.</p>
Security Considerations</h2>
Sybil Attacks</h3>
An attacker can create many ENS names and establish mutual trust between them.</p>
Protocol-level mitigations:</strong></p>

Required anchors</strong>: ValidationParams.requiredAnchors</code> forces paths through established community nodes</li>
Short path limits</strong>: maxPathLength: 2</code> requires close proximity to validators</li>
High trust requirement</strong>: minEdgeTrust: Full</code> rejects marginal trust paths</li>
</ul>
Application-level mitigations:</strong></p>

Weight trust by ENS name age or registration cost</li>
Implement additional stake requirements</li>
Monitor trust graphs for anomalous patterns off-chain</li>
</ul>
Trust Graph Manipulation</h3>
Attackers may attempt to position themselves in many trust paths.</p>
Mitigations:</strong></p>

Monitor trust graphs for anomalous patterns off-chain</li>
Use minEdgeTrust: Full</code> for high-value coordination</li>
Require multiple independent paths via OPTIONAL extensions</li>
</ul>
Key Compromise</h3>
If an ENS name's controller is compromised:</p>
Mitigations:</strong></p>

Agents SHOULD monitor for unexpected trust changes via TrustSet</code> events</li>
Use short expiries (90 days maximum recommended for high-stakes)</li>
ENS name owners can rotate controllers</li>
Affected agents can issue TrustRevoked</code> to quarantine compromised nodes</li>
</ul>
ENS Name Transfer</h3>
When an ENS name is transferred:</p>

New owner inherits trust where they are the trustee</li>
New owner can manage trust where they are the trustor</li>
Old attestations signed by old owner remain valid until expiry</li>
</ul>
Mitigations:</strong></p>

Use short expiries for high-stakes trust</li>
Monitor ENS Transfer</code> events</li>
Re-evaluate trust after transfers</li>
</ul>
Replay Protection</h3>
EIP-712</a> domain binding prevents cross-contract replay. Monotonic nonces prevent replay within the same contract. The chainId</code> in the domain prevents cross-chain replay.</p>
Stale Trust</h3>
Trust relationships may become stale if agents don't update them.</p>
Mitigations:</strong></p>

Use enforceExpiry: true</code> in validation parameters</li>
Set reasonable expiry</code> values on attestations (RECOMMENDED: 90 days maximum for high-stakes)</li>
Monitor TrustSet</code> event timestamps off-chain</li>
</ul>
Off-Chain Path Computation</h3>
This standard assumes off-chain indexers compute trust paths. Malicious indexers could:</p>

Return suboptimal paths</li>
Omit valid paths</li>
Return invalid paths (caught by verifyPath</code>)</li>
</ul>
Mitigations:</strong></p>

Users can run their own indexers</li>
Multiple independent indexers provide redundancy</li>
Invalid paths are always rejected on-chain</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Cross-Chain Function Calls via Hooks
2025-12-12T00:00:00+00:00
Abstract</h2>
This ERC introduces hooks for cross-chain function calls. A hook fully specifies what function to call, with what parameters, on which contract, on which chain. Hooks require clients to use ERC-3668</a> to resolve, enabling cross-chain and off-chain verifiable data resolution. Hooks are particularly useful for redirecting metadata to known contracts with verifiable security properties, such as credential registries for Proof-of-Personhood (PoP) or Know-Your-Agent (KYA) for AI agent identity.</p>
Motivation</h2>
There is a need to resolve data cross-chain, such as credentials like Proof-of-Personhood (PoP), for example from a dedicated identity chain. There is also a need to save these cross-chain function calls onchain, and there is currently no existing standard for saving this type of function call as a string or bytes value onchain, in a maximally human-readable way. It should also be possible for a hook to be included in plain text, for example a markdown file intended to be consumed by AI agents. Hooks allow for a specific function, contract, and chain to be specified in a human-readable way. One of the most important features of hooks is that it allows clients to evaluate whether or not they trust the target contract, for example to resolve a PoP or KYC credential, before calling the function.</p>
Use Cases</h3>

Cross-Chain Metadata</strong>: Resolve metadata from contracts on other chains</li>
Credential Resolution</strong>: Redirect a Proof-of-Person (PoP) or Know-Your-Customer (KYC) record to a trusted credential registry</li>
Singleton Registries</strong>: Point to canonical registries with known security properties on any chain</li>
Shared Metadata</strong>: Multiple contracts can reference the same metadata source across chains</li>
</ul>
Specification</h2>
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.</p>
Overview</h3>
A hook is a fully specified function call containing an optional function selector, function signature with explicit types, human-readable function call with values, return type, and an ERC-7930</a> interoperable address specifying both the target contract and chain. The function selector acts as a checksum to verify the function signature, ensuring type safety and preventing ambiguity. This makes hooks completely self-describing - any client can resolve them without external documentation.</p>
Hook Function Signature</h3>
Hooks can be encoded with or without an optional function selector. When the selector is omitted, functionSignature</code> is the first parameter.</p>
With optional function selector:</strong></p>
function</span> hook</span>(</span></span>
    bytes4</span> functionSelector</span>,</span></span>
    string</span> calldata</span> functionSignature</span>,</span></span>
    string</span> calldata</span> functionCall</span>,</span></span>
    string</span> calldata</span> returnType</span>,</span></span>
    bytes</span> calldata</span> target</span></span>
)</span></span></code></pre>
Without function selector:</strong></p>
function</span> hook</span>(</span></span>
    string</span> calldata</span> functionSignature</span>,</span></span>
    string</span> calldata</span> functionCall</span>,</span></span>
    string</span> calldata</span> returnType</span>,</span></span>
    bytes</span> calldata</span> target</span></span>
)</span></span></code></pre>bytes4</span> constant</span> HOOK_SELECTOR_WITH_SELECTOR </span>=</span> 0x037f43ed</span>;</span>  //</span> When functionSelector is included</span></span>
bytes4</span> constant</span> HOOK_SELECTOR_WITHOUT_SELECTOR </span>=</span> 0x6113bfa3</span>;</span> //</span> When functionSelector is omitted</span></span></code></pre>Parameters</h4>

functionSelector</code></strong>: (OPTIONAL) The 4-byte selector of the function to call. When provided, this acts as a checksum to verify the functionSignature</code>. If omitted, the hook structure starts with functionSignature</code> as the first parameter. Clients can always derive the selector from functionSignature</code>.</li>
functionSignature</code></strong>: The full function signature with explicit parameter types (e.g., "getData((string,uint256))"</code>, "getCredential(string)"</code>). This MUST match the function selector when hashed, if a selector is provided. When the selector is omitted, this is the first parameter in the hook structure.</li>
functionCall</code></strong>: A string representation of the function to call with its parameter values (human-readable, e.g., "getData(('alice', 42))"</code>, "getCredential('kyc: 0x76F1Ff...123')"</code>)</li>
returnType</code></strong>: The return type in Solidity tuple notation for ABI decoding (e.g., (string)</code>, (uint256, bytes32)</code>, ((string, uint256[], bytes32))</code>)</li>
target</code></strong>: An ERC-7930</a> interoperable address specifying both the target contract and chain</li>
</ul>
Function Call Format</h3>
The functionCall</code> parameter uses a Solidity-style syntax:</p>

String parameters are enclosed in single quotes: 'value'</code></li>
Bytes/hex parameters use the 0x</code> prefix: 0x1234abcd</code></li>
Numbers are written as literals: 42</code> or 1000000</code></li>
Arrays use square brackets: [1, 2, 3]</code> or ['a', 'b', 'c']</code></li>
Structs/tuples use parentheses: ('alice', 42, true)</code></li>
</ul>
Examples:</strong></p>
// Example with optional function selector (acts as checksum)</span></span>
hook(0xc41a360a, "getOwner(uint256)", "getOwner(42)", "(address)", 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span>
</span>
// Example with function selector omitted</span></span>
hook("getOwner(uint256)", "getOwner(42)", "(address)", 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span></code></pre>Hook Encoding</h3>
Hooks can be encoded in two formats depending on the storage type:</p>
Bytes Format</h4>
For systems that store bytes</code> values, hooks MUST be ABI-encoded. Use different hook selectors depending on whether the optional function selector is included:</p>
With optional function selector:</strong></p>
//</span> Hook selector: first 4 bytes of keccak256("hook(bytes4,string,string,string,bytes)")</span></span>
bytes4</span> constant</span> HOOK_SELECTOR_WITH_SELECTOR </span>=</span> 0x037f43ed</span>;</span></span>
</span>
//</span> Function signature with explicit types</span></span>
string</span> memory</span> functionSignature </span>=</span> "getContractMetadata(string)"</span>;</span></span>
</span>
//</span> Optional function selector as checksum (computed from signature)</span></span>
bytes4</span> functionSelector </span>=</span> bytes4</span>(</span>keccak256</span>(</span>functionSignature</span>)</span>)</span>;</span> //</span> 0x1837de7f</span></span>
</span>
//</span> Function call with values</span></span>
string</span> memory</span> functionCall </span>=</span> "getContractMetadata('kyc')"</span>;</span></span>
</span>
//</span> ERC-7930 address: Ethereum mainnet (chain 1) contract</span></span>
bytes</span> memory</span> target </span>=</span> hex</span>"000100000101141234567890abcdef1234567890abcdef12345678"</span>;</span></span>
</span>
bytes</span> memory</span> hookData </span>=</span> abi</span>.</span>encodeWithSelector</span>(</span></span>
    HOOK_SELECTOR_WITH_SELECTOR</span>,</span></span>
    functionSelector</span>,</span></span>
    functionSignature</span>,</span></span>
    functionCall</span>,</span></span>
    "(bytes)"</span>,</span>  //</span> return type</span></span>
    target</span></span>
)</span>;</span></span>
</span>
//</span> Store the hook as the value</span></span>
originatingContract</span>.</span>setContractMetadata</span>(</span>"kyc"</span>,</span> hookData</span>)</span>;</span></span></code></pre>
Without function selector:</strong></p>
//</span> Hook selector: first 4 bytes of keccak256("hook(string,string,string,bytes)")</span></span>
bytes4</span> constant</span> HOOK_SELECTOR_WITHOUT_SELECTOR </span>=</span> 0x6113bfa3</span>;</span></span>
</span>
//</span> Function signature with explicit types</span></span>
string</span> memory</span> functionSignature </span>=</span> "getContractMetadata(string)"</span>;</span></span>
</span>
//</span> Function call with values</span></span>
string</span> memory</span> functionCall </span>=</span> "getContractMetadata('kyc')"</span>;</span></span>
</span>
//</span> ERC-7930 address: Ethereum mainnet (chain 1) contract</span></span>
bytes</span> memory</span> target </span>=</span> hex</span>"000100000101141234567890abcdef1234567890abcdef12345678"</span>;</span></span>
</span>
bytes</span> memory</span> hookData </span>=</span> abi</span>.</span>encodeWithSelector</span>(</span></span>
    HOOK_SELECTOR_WITHOUT_SELECTOR</span>,</span></span>
    functionSignature</span>,</span>  //</span> First parameter when selector is omitted</span></span>
    functionCall</span>,</span></span>
    "(bytes)"</span>,</span>  //</span> return type</span></span>
    target</span></span>
)</span>;</span></span>
</span>
//</span> Store the hook as the value</span></span>
originatingContract</span>.</span>setContractMetadata</span>(</span>"kyc"</span>,</span> hookData</span>)</span>;</span></span>
//</span> Target function: function getContractMetadata(string) external view returns (bytes memory)</span></span></code></pre>String Format</h4>
For systems that store string</code> values, hooks MUST be formatted as shown below. The target is an ERC-7930</a> interoperable address.</p>
With optional function selector:</strong></p>
hook(0x9e574b14, "getContractMetadata(string)", "getContractMetadata('kyc')", "(bytes)", 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span></code></pre>
Without function selector:</strong></p>
hook("getContractMetadata(string)", "getContractMetadata('kyc')", "(bytes)", 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span></code></pre>
Parsers MUST detect the format by checking if the first parameter after hook(</code> starts with 0x</code> followed by 8 hexadecimal characters (an optional function selector) or not.</p>
Examples:</strong></p>
</span>
// Example 1: simple struct parameter</span></span>
hook(0xabcdef12, "getData((string,uint256))", "getData(('alice', 42))", "(bytes)", 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span>
</span>
// Example 2: struct parameter returning struct</span></span>
hook(0x12345678, "getCredential((string,uint256,bytes32))", "getCredential(('kyc', 12345, 0xabcd1234...))", "((string,address,uint256))", 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span>
</span>
// Example 3: nested struct (struct containing a struct)</span></span>
hook(0x9abcdef0, "getAgent((string,uint256,(address,bool,string)))", "getAgent(('alice', 42, (0x1234..., true, 'verified')))", "((string,uint256,(address,bool)))", 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span></code></pre>Detecting Hooks</h3>
Clients SHOULD be aware in advance which metadata keys may contain hooks. It is intentional that hook-enabled keys are known by clients beforehand, similar to how clients know to look for keys like "image"</code> or "description"</code>.</p>
For bytes values, hooks can be detected by checking if the value starts with either hook selector 0x037f43ed</code> (with optional function selector) or 0x6113bfa3</code> (without function selector). For string values, hooks can be detected by checking if the value starts with hook(</code>.</p>
Resolving Hooks (Read Operations)</h3>
When a client encounters a hook that it wants to use for a read operation:</p>

Detect hook format</strong>: For bytes format, check if the value starts with 0x037f43ed</code> (with selector) or 0x6113bfa3</code> (without selector). For string format, parse the first parameter after hook(</code> to determine if it's a selector (starts with 0x</code> + 8 hex chars) or not.</li>
Parse the hook</strong>: Extract the functionSelector</code> (if present), functionSignature</code>, functionCall</code>, returnType</code>, and target</code> (ERC-7930</a> address). If the selector is omitted, functionSignature</code> is the first parameter.</li>
Verify the selector</strong> (if provided): If functionSelector</code> is present, compute the expected selector from functionSignature</code> as bytes4(keccak256(functionSignature))</code> and verify it matches functionSelector</code>. Reject the hook if they don't match. This verification ensures type safety and prevents ambiguity with structs or overloaded functions. If the selector is omitted, compute it from functionSignature</code> for use in the function call.</li>
Parse the target</strong>: Decode the ERC-7930</a> address to extract the chain and contract address</li>
Verify the target</strong> (RECOMMENDED): Check that the target contract is known and trusted</li>
Parse the function call</strong>: Extract the function name and parameter values from functionCall</code>. Use functionSignature</code> to determine the parameter types for ABI encoding.</li>
Enable ERC-3668</a></strong>: Clients MUST enable ERC-3668</a> offchain data retrieval before calling the target</li>
Call the target</strong>: Execute the function on the target contract and chain. Use the provided functionSelector</code> if available, otherwise compute it from functionSignature</code> as bytes4(keccak256(functionSignature))</code>. ABI-encode the parameters according to functionSignature</code>.</li>
Get the result</strong>: Retrieve the return value from the function call.</li>
</ol>
Clients MAY choose NOT to resolve hooks if the target contract is not known to be secure and trustworthy. Some clients have ERC-3668</a> disabled by default, but clients MUST enable it before resolving the hook.</p>
Write Operations</h3>
Write operations are also possible with hooks and follow the same flow as read operations, except that the transaction needs to be signed and submitted to the blockchain. The hook specifies the function to call, parameters, target contract, and chain, but instead of reading the result, the transaction is signed and broadcast to the network for inclusion in a block.</p>
Example: Cross-Chain KYC Credential Resolution</h3>
A contract on Optimism can redirect its "kyc"</code> metadata key to a trusted KYC provider contract on Ethereum mainnet:</p>
Step 1: Store the hook in the originating contract (on Optimism)</strong></p>
bytes4</span> constant</span> HOOK_SELECTOR_WITHOUT_SELECTOR </span>=</span> 0x6113bfa3</span>;</span></span>
</span>
//</span> Function signature with explicit types</span></span>
string</span> memory</span> functionSignature </span>=</span> "getCredential(string)"</span>;</span></span>
</span>
//</span> Function call with values</span></span>
string</span> memory</span> functionCall </span>=</span> "getCredential('kyc: 0x76F1Ff0186DDb9461890bdb3094AF74A5F24a162')"</span>;</span></span>
</span>
//</span> KYCProvider on Ethereum mainnet (ERC-7930 format)</span></span>
//</span> Chain: Ethereum mainnet (chain 1), Address: 0x1234...5678</span></span>
bytes</span> memory</span> target </span>=</span> hex</span>"000100000101141234567890abcdef1234567890abcdef12345678"</span>;</span></span>
</span>
//</span> Create hook that calls getCredential('kyc: 0x76F1Ff...') on the KYC provider</span></span>
bytes</span> memory</span> hookData </span>=</span> abi</span>.</span>encodeWithSelector</span>(</span></span>
    HOOK_SELECTOR_WITHOUT_SELECTOR</span>,</span></span>
    functionSignature</span>,</span>  //</span> First parameter when selector is omitted</span></span>
    functionCall</span>,</span></span>
    "(string)"</span>,</span>  //</span> return type</span></span>
    target</span></span>
)</span>;</span></span>
</span>
//</span> Store the hook</span></span>
originatingContract</span>.</span>setContractMetadata</span>(</span>"kyc"</span>,</span> hookData</span>)</span>;</span></span></code></pre>
Step 2: Client resolves the hook</strong></p>
//</span> Client reads metadata from originating contract (on Optimism)</span></span>
const</span> value</span> =</span> await</span> originatingContract</span>.</span>getContractMetadata</span>(</span>"</span>kyc</span>"</span>)</span>;</span></span>
</span>
//</span> Client detects this is a hook (starts with HOOK_SELECTOR)</span></span>
const</span> hasSelector</span> =</span> value</span>.</span>startsWith</span>(</span>"</span>0x037f43ed</span>"</span>)</span>;</span></span>
if</span> (</span>value</span>.</span>startsWith</span>(</span>"</span>0x037f43ed</span>"</span>)</span> ||</span> value</span>.</span>startsWith</span>(</span>"</span>0x6113bfa3</span>"</span>)</span>)</span> {</span></span>
    //</span> Parse the hook (ABI decode after 4-byte selector)</span></span>
    let</span> functionSelector</span>,</span> functionSignature</span>,</span> functionCall</span>,</span> returnType</span>,</span> target</span>;</span></span>
    if</span> (</span>hasSelector</span>)</span> {</span></span>
        (</span>{</span> functionSelector</span>,</span> functionSignature</span>,</span> functionCall</span>,</span> returnType</span>,</span> target</span> }</span> =</span> decodeHook</span>(</span>value</span>)</span>)</span>;</span></span>
    }</span> else</span> {</span></span>
        (</span>{</span> functionSignature</span>,</span> functionCall</span>,</span> returnType</span>,</span> target</span> }</span> =</span> decodeHook</span>(</span>value</span>)</span>)</span>;</span></span>
        functionSelector</span> =</span> null</span>;</span></span>
    }</span></span>
</span>
    //</span> Verify selector matches the function signature (checksum verification, if provided)</span></span>
    const</span> computedSelector</span> =</span> keccak256</span>(</span>functionSignature</span>)</span>.</span>slice</span>(</span>0</span>,</span> 10</span>)</span>;</span></span>
    if</span> (</span>functionSelector</span>)</span> {</span></span>
        if</span> (</span>functionSelector</span> !==</span> computedSelector</span>)</span> {</span></span>
            throw</span> new</span> Error</span>(</span>"</span>Selector mismatch - function signature verification failed</span>"</span>)</span>;</span></span>
        }</span></span>
    }</span></span>
    //</span> Use computed selector if not provided</span></span>
    const</span> selectorToUse</span> =</span> functionSelector</span> ||</span> computedSelector</span>;</span></span>
</span>
    //</span> Decode ERC-7930 address to get chain and contract</span></span>
    const</span> {</span> chainId</span>,</span> address</span> }</span> =</span> decodeERC7930</span>(</span>target</span>)</span>;</span></span>
    //</span> chainId = 1 (Ethereum mainnet)</span></span>
    //</span> address = 0x1234567890abcdef1234567890abcdef12345678</span></span>
</span>
    //</span> Verify target is trusted (implementation-specific)</span></span>
    if</span> (</span>!</span>isTrustedResolver</span>(</span>chainId</span>,</span> address</span>)</span>)</span> {</span></span>
        throw</span> new</span> Error</span>(</span>"</span>Untrusted resolver</span>"</span>)</span>;</span></span>
    }</span></span>
</span>
    //</span> Parse the function call string to get function name and parameter values</span></span>
    const</span> {</span> functionName</span>,</span> args</span> }</span> =</span> parseFunctionCall</span>(</span>functionCall</span>)</span>;</span></span>
    //</span> functionName = "getCredential"</span></span>
    //</span> args = ["kyc: 0x76F1Ff0186DDb9461890bdb3094AF74A5F24a162"]</span></span>
</span>
    //</span> Use functionSignature to determine parameter types for ABI encoding</span></span>
    //</span> functionSignature = "getCredential(string)"</span></span>
</span>
    //</span> Get provider for target chain and enable ERC-3668 (CCIP-Read)</span></span>
    const</span> targetProvider</span> =</span> getProviderForChain</span>(</span>chainId</span>)</span>;</span></span>
    const</span> targetContract</span> =</span> new</span> ethers</span>.</span>Contract</span>(</span></span>
        address</span>,</span></span>
        [</span>`</span>function </span>${</span>functionSignature</span>}</span> view returns (bytes)</span>`</span>]</span>,</span></span>
        targetProvider</span>.</span>ccipReadEnabled</span>(</span>true</span>)</span>  //</span> Enable CCIP-Read</span></span>
    )</span>;</span></span>
</span>
    //</span> Resolve from target contract on Ethereum mainnet</span></span>
    //</span> ABI-encode parameters according to functionSignature</span></span>
    const</span> resultBytes</span> =</span> await</span> targetContract</span>[</span>functionName</span>]</span>(</span>...</span>args</span>)</span>;</span></span>
</span>
    //</span> ABI-decode using returnType: "(string)"</span></span>
    const</span> credential</span> =</span> ethers</span>.</span>utils</span>.</span>defaultAbiCoder</span>.</span>decode</span>(</span>[</span>returnType</span>]</span>,</span> resultBytes</span>)</span>;</span></span>
    //</span> credential = "Maria Garcia /0x76F1Ff.../ ID: 146-DJH-6346-25294"</span></span>
}</span></span></code></pre>Rationale</h2>
Hooks provide a complete specification for cross-chain function calls, including ERC-7930</a> interoperable address. This makes hooks entirely self-describing - any client can resolve them without external documentation or ABI files. For use cases including resolving credentials from known registries including PoP (Proof of Personhood) and KYC (Know Your Customer) credentials, the client needs to make sure the source of the credential is trustworthy and verified. Hooks allow clients to jump from a user's metadata record, for example, to a KYC credential from a known credential issuer.</p>
Why Include Both Function Selector and Function String?</h3>
Hooks include both an optional 4-byte function selector and a human-readable function call string. The selector provides type disambiguation (e.g., getData(bytes32)</code> and getData(bytes)</code> have different selectors, but 0x1234...</code> in the string is ambiguous), while the string provides human readability. Clients can verify the selector matches the function signature, rejecting mismatches as errors or tampering.</p>
Why Use ERC-7930 Interoperable Addresses?</h3>
ERC-7930</a> addresses include chain information, making hooks a complete cross-chain function call specification. A hook specifies exactly what function to call, with what parameters, on which contract, on which chain. This eliminates ambiguity and enables secure cross-chain reads when combined with ERC-3668</a>.</p>
Why Include the Return Type?</h3>
The returnType</code> parameter allows clients to predict the return values without consulting documentation. It is also possible to predict if the return data is compatible with intended metadata. For example, if a bytes value redirects using hooks, that return value may need to also be bytes, according to the specific metadata standard (not specified here). Applications can impose their own constraints (e.g., requiring (string)</code> for metadata hooks), but hooks themselves support any return type.</p>
Why Mandate ERC-3668</a>?</h3>
ERC-3668</a> (CCIP-Read) is a powerful technology that enables both cross-chain and verified offchain resolution of metadata. However, because some clients disable ERC-3668</a> by default due to security considerations, hooks explicitly mandate ERC-3668</a> support. This gives clients the opportunity to enable ERC-3668</a> specifically for hook resolution without needing to have it enabled globally. By tying ERC-3668</a> to hooks, clients can make a deliberate choice to enable it when resolving from known, trusted contracts, while keeping it disabled for general use.</p>
Backwards Compatibility</h2>
Hooks are backwards compatible; clients that are not aware of hooks will simply return the hook encoding as the raw value.</p>
Security Considerations</h2>
Target Trust</h3>
The primary use of hooks is to resolve data from known contracts with verifiable security properties. Clients SHOULD:</p>

Maintain a list of trusted target contract addresses or use a third-party registry</li>
Fail when resolving from untrusted targets</li>
</ul>
Recursive Hooks</h3>
Implementations SHOULD limit the depth of hook resolution to prevent infinite loops where a hook resolves to another hook. A reasonable limit is 3-5 levels of indirection.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Associated Accounts
2025-11-25T00:00:00+00:00
Abstract</h2>
This specification defines a standard for establishing and verifying associations between blockchain accounts. This allows addresses to publicly declare, prove and revoke a relationship with other addresses by sharing a standardized payload. For onchain applications, this payload may be signed by both parties for third-party authentication. This enables use cases like sub-account identity inheritance, authorization delegation, and reputation collation.</p>
Motivation</h2>
A key motivation is the simplification of multi-address resolution, which is essential for managing complex digital identities across multiple platforms and accounts. This simplification aims to streamline the process of locating and verifying individuals or entities by efficiently handling multiple addresses linked by Associations.
By providing a standard mechanism for signaling an association between two accounts, this standard unlocks the capability to link the activities or details of these accounts.</p>
The inclusion of arbitrary data into the specified payload ensures flexibility for various use cases such as delegation, hierarchical relationships, and authentication. By maintaining a flexible architecture that accepts an interface identifier paired with arbitrary data bytes, accounts that associate can do so with application-specific context.</p>
The system outlined in this document describes a way for two accounts to be linked by a specified data struct which describes the relationship between them. It offers the mechanism by which these parties can sign over the contents to prove validity. It focuses on the structure and process for generating, validating and revoking such records while maintaining an implementation agnostic approach.</p>
Specification</h2>
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.</p>
Core Concepts</h3>
Each Association between two accounts denotes the participating addresses as initiator</code> and approver</code>. These accounts can be on disparate chains with different architectures made possible by a combination of ERC-7930</a> Interoperable Addresses and an enumeration of signature key types. To accommodate non-EVM account types, addresses are recorded in the association as raw bytes.</p>
The specification outlines a nested structure for recording Associations:</p>

An underlying Associated Account Record (AAR) for storing accounts, timestamps and association context</li>
A wrapper Signed Association Record (SAR) structure for storing signature and validation data</li>
</ol>
Associated Account Record</h3>
The following is a Solidity implementation of an AssociatedAccountRecord</code> which contains the shared payload describing the association.</p>
///</span> @notice</span> Represents an association between two accounts.</span></span>
struct</span> AssociatedAccountRecord</span> {</span></span>
    ///</span> @dev</span> The ERC-7930 binary representation of the initiating account's address.</span></span>
    bytes</span> initiator</span>;</span></span>
    ///</span> @dev</span> The ERC-7930 binary representation of the approving account's address.</span></span>
    bytes</span> approver</span>;</span></span>
    ///</span> @dev</span> The timestamp from which the association is valid.</span></span>
    uint40</span> validAt</span>;</span></span>
    ///</span> @dev</span> The timestamp when the association expires.</span></span>
    uint40</span> validUntil</span>;</span></span>
    ///</span> @dev</span> Optional 4-byte selector for interfacing with the `data` field.</span></span>
    bytes4</span> interfaceId</span>;</span></span>
    ///</span> @dev</span> Optional additional data.</span></span>
    bytes</span> data</span>;</span></span>
}</span></span></code></pre>
Where the AssociatedAccountRecord contains:</p>

initiator</code> is the binary representation of an ERC-7930 address for the initiating account.</li>
approver</code> is the binary representation of an ERC-7930 address for the approving account.</li>
validAt</code> is the timestamp from which the association is valid.</li>
validUntil</code> is the timestamp at which the association expires (optional).</li>
interfaceId</code> is the 4-byte interface or method selector for the data</code> field (optional).</li>
data</code> is the arbitrary context data payload (optional).</li>
</ul>
Signed Association Record</h3>
When AssociatedAccountRecord</code>s will be consumed in a trustless context, integrators SHOULD require that both parties sign over the EIP-712</a> hash of the AssociatedAccountRecord</code> (see Support for EIP-712 below). The resulting signatures MUST be included in a SignedAssociationRecord</code>.</p>
    ///</span> @notice</span> Complete payload containing a finalized association.</span></span>
    struct</span> SignedAssociationRecord</span> {</span></span>
        ///</span> @dev</span> The timestamp the association was revoked.</span></span>
        uint40</span> revokedAt</span>;</span></span>
        ///</span> @dev</span> The initiator key type specifier.</span></span>
        bytes2</span> initiatorKeyType</span>;</span></span>
        ///</span> @dev</span> The approver key type specifier.</span></span>
        bytes2</span> approverKeyType</span>;</span></span>
        ///</span> @dev</span> The signature of the initiator.</span></span>
        bytes</span> initiatorSignature</span>;</span></span>
        ///</span> @dev</span> The signature of the approver.</span></span>
        bytes</span> approverSignature</span>;</span></span>
        ///</span> @dev</span> The underlying AssociatedAccountRecord.</span></span>
        AssociatedAccountRecord record</span>;</span></span>
    }</span></span></code></pre>
Where the SignedAssociationRecord contains:</p>

revokedAt</code> is the timestamp when the association was revoked, which is 0</code> unless the association has been revoked by either party.</li>
initiatorSignature</code> is the signature bytes generated by the initiator</code> by signing the EIP-712 compliant hash of the AssociatedAccountRecord.</li>
initiatorKeyType</code> is the key type designator for the initiator's signature (see Key Types below).</li>
approverSignature</code> is the signature bytes generated by the approver</code> by signing the EIP-712 compliant hash of the AssociatedAccountRecord.</li>
approverKeyType</code> is the key type designator for the approver's signature (see Key Types below).</li>
record</code> is the AssociatedAccountRecord that was signed by both parties.</li>
</ul>
Key Types</h3>
To accommodate known curves and signing protocols while providing future extensibility, this specification relies on the enumeration of cryptographic curves and signing protocols. Each signature MUST be paired with a valid "Key ID" designator.</p>
The Key IDs SHALL be identified as a 2-byte integer according to the following extensible table. We accommodate two types of keys:</p>

Applied cryptographic curves (i.e. secp256k1)</li>
Protocol integrations (i.e. WebAuthn, contract validation)</li>
</ol>
To distinguish these key types, the most significant bit in the 2-byte identifier SHALL be used as a bit flag. As such, key type protocols are constructed by bitwise OR:
0x8000 | PROTOCOL_ID</code>.</p>
The resulting table enumerates the known keys and distinguishes between the two types:</p>
Key ID</th> Type</th> Curve/Standard</th></tr></thead>

0x0000</td> Delegated</td> Delegated auth</td></tr>
0x0001</td> K1</td> secp256k1</td></tr>
0x0002</td> R1</td> secp256r1</td></tr>
0x0003</td> BLS</td> BLS12-381</td></tr>
0x0004</td> EdDSA</td> Ed25519</td></tr>
0x8001</td> WebAuthn</td> WebAuthn/Passkey</td></tr>
0x8002</td> ERC-1271</a></td> Contract validation</td></tr>
0x8003</td> ERC-6492</a></td> Predeploy contract validation</td></tr>
</tbody></table>
Delegated Auth</h4>
In some contexts it might be ergonomic to delegate authorization to another account, access control mechanism, or external protocol. Implementers leveraging the Delegated</code> key type MUST also publish how consumers can parse the application-specific delegation schema.</p>
Support for EIP-712</h3>
All signatures contained in this specification MUST comply with EIP-712 wherein the signature preimage can be generated from:</p>
keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span></span>
   hex</span>"1901"</span>,</span></span>
   DOMAIN_SEPARATOR</span>,</span></span>
   keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span>
    keccak256</span>(</span>"AssociatedAccountRecord(bytes initiator,bytes approver,uint40 validAt,uint40 validUntil,bytes4 interfaceId,bytes data)"</span>)</span>,</span></span>
    keccak256</span>(</span>initiator</span>)</span>,</span> </span></span>
    keccak256</span>(</span>approver</span>)</span>,</span></span>
    validAt</span>,</span></span>
    validUntil</span>,</span></span>
    interfaceId</span>,</span></span>
    keccak256</span>(</span>data</span>)</span></span>
    )</span>)</span></span>
)</span>)</span></span></code></pre>
Where DOMAIN_SEPARATOR</code> is defined according to EIP-712. The DOMAIN_SEPARATOR</code> for this ERC SHALL be defined as:</p>
keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span>
    keccak256</span>(</span>"EIP712Domain(string name,string version)"</span>)</span>,</span></span>
    keccak256</span>(</span>bytes</span>(</span>"AssociatedAccounts"</span>)</span>)</span>,</span></span>
    keccak256</span>(</span>bytes</span>(</span>"1"</span>)</span>)</span></span>
)</span>)</span></span></code></pre>Onchain Storage</h3>
If desired, a SignedAssociationRecord</code> MAY be stored onchain in a context-specific storage contract.</p>
An onchain storage contract SHALL comply with the following steps:</p>

The SAR MUST be validated according to the steps detailed in the Validation section.</li>
The contract MUST emit the AssociationCreated</code> event:</li>
</ol>
    event</span> AssociationCreated</span>(</span></span>
        bytes32</span> indexed</span> hash</span>, </span>bytes32</span> indexed</span> initiator</span>, </span>bytes32</span> indexed</span> approver</span>, </span>SignedAssociationRecord</span> sar</span></span>
    )</span>;</span></span></code></pre>
where:</p>

hash</code> is the indexed hash for the SignedAssociationRecord, equivalent to the EIP-712 hash of the underlying AAR.</li>
initiator</code> is the keccak256 hash of the ERC-7930 address of the account that initiated the association.</li>
approver</code> is the keccak256 hash of the ERC-7930 address of the account that accepted and completed the association.</li>
sar</code> is the completed SignedAssociationRecord.</li>
</ul>
If a SignedAssociationRecord is stored onchain, it MUST also be revokable onchain (see Revocation section below).</p>
Offchain Storage</h3>
In some contexts, it might be desirable for Signed Association Records to be stored in an offchain store. While the implementation will differ from application-to-application, the following considerations SHOULD be taken into account:</p>

Access to this data store MUST be made available to all expected consumers through publicly accessible endpoints</li>
The store MUST perform validation on incoming Associations before storage</li>
The location of this offchain store SHOULD be searchable by some standard fetching mechanism, e.g. a text record on an ENS name</li>
</ul>
Validation</h3>
Clients or contracts determining whether a SignedAssociationRecord is valid at the time of consumption MUST check all of the following validation steps:</p>

The current timestamp MUST be greater than or equal to the validAt</code> timestamp.</li>
If the validUntil</code> timestamp is nonzero, the current timestamp MUST be less than the validUntil</code> timestamp.</li>
If the revokedAt</code> timestamp is nonzero, the current timestamp MUST be less than the revokedAt</code> timestamp.</li>
If the initiatorSignature</code> field is populated, the signature MUST be valid for the EIP-712 preimage of the underlying AssociatedAccountRecord</code> using an appropriate initiatorKeyType</code> validation mechanism.</li>
If the approverSignature</code> field is populated, the signature MUST be valid for the EIP-712 preimage of the underlying AssociatedAccountRecord</code> using an appropriate approverKeyType</code> validation mechanism.</li>
</ol>
Onchain validation is possible as long as there are sufficient validation mechanisms for the various key types used by the two accounts. In the case that validation occurs onchain, implementations MUST replace "current timestamp" with block.timestamp</code>.</p>
Revocation</h3>
Onchain Association stores MUST implement a revocation method. This method MUST allow either party of an Association to revoke a valid, active association by submitting a revocation request.</p>
In such contexts, storage contracts MUST update the revokedAt</code> field of the SAR to block.timestamp</code> OR the account-specified revocation timestamp, whichever is greater. Then the implementation contract MUST emit the following event upon accepting a valid revocation request:</p>
    event</span> AssociationRevoked</span>(</span>bytes32</span> indexed</span> hash</span>, </span>bytes32</span> indexed</span> revokedBy</span>, </span>uint256</span> revokedAt</span>)</span>;</span></span></code></pre>
where:</p>

hash</code> is the indexed unique identifier for the association, equivalent to the EIP-712 hash of the underlying AAR.</li>
revokedBy</code> is the indexed keccak256 hash of the ERC-7930 address of the revoking account.</li>
revokedAt</code> is the timestamp at which the association is revoked.</li>
</ul>
Offchain stores MUST allow either account to revoke a stored association and MUST update the revokedAt</code> timestamp accordingly.</p>
If a previously revoked association is revoked again with an earlier timestamp, the earlier timestamp MUST take precedence.</p>
Rationale</h2>
Nested Structure Design</h3>
The separation of AssociatedAccountRecord</code> and SignedAssociationRecord</code> into distinct structures serves a critical functional purpose. The inner AssociatedAccountRecord</code> contains the immutable association payload that both parties must agree upon. This record can be shared, reviewed, and prepared while signatures are collected asynchronously from each party. The outer SignedAssociationRecord</code> wrapper accumulates these signatures and metadata without modifying the underlying record.</p>
Lack of Existing Standards</h3>
Currently, no standardized mechanism exists for establishing verifiable associations between blockchain accounts. Existing approaches are either application-specific or rely on proprietary schemas that limit interoperability. This specification addresses that gap by providing a common format that can be adopted across applications, enabling portability and composability of identity relationships.</p>
Supporting App-Scoped Sub Accounts</h3>
Today's blockchain ecosystem enforces a rigid one-to-one relationship between onchain identities and addresses, limiting users to a single address per identity. This specification breaks that constraint by enabling users to maintain a unified identity across multiple addresses. Users benefit from maintaining separate accounts for different contexts or applications while preserving the ability to verifiably link them to a primary identity when desired. This standard provides the mechanism for establishing these connections, enabling app-scoped sub accounts that can be provably associated with a root identity without sacrificing the flexibility and security benefits of address separation.</p>
Storage Agnosticism</h3>
Different association types have varying requirements for accessibility, cost, and decentralization. High-value associations requiring maximum trust minimization may warrant onchain storage despite higher costs, while frequent or ephemeral associations may be better suited for offchain stores. By remaining agnostic to storage location and requiring only that validation rules be consistently applied, this specification allows implementers to choose the appropriate tradeoffs for their use case without fragmenting the standard itself.</p>
Security Considerations</h2>
For onchain applications, the validation mechanisms for some key types might be gas-cost prohibitive or entirely unavailable. It is the responsibility of the integrator to ensure that unsupported key types are appropriately handled given these constraints.</p>
Offchain stores expose a trust vector to consumers. Integrators and consumers MUST take into account this centralization vector and expose the risk to users or offer mechanisms for minimizing the trust assumptions (i.e. storing some state onchain).</p>
Associations SHOULD have a canonical storage location given an application. However, in the event that the same Association data is stored both on and offchain, precedence SHOULD be given to the onchain data.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Self-Describing Bytes via EIP-712 Selectors
2025-10-30T00:00:00+00:00
Abstract</h2>
This ERC standardizes a convention for tagging ABI-encoded structures placed inside bytes</code> parameters with a compact type selector derived from the EIP-712</a> type string.
It also defines a canonical multi-payload wrapper, allowing multiple typed payloads to be carried in a single bytes</code> parameter.</p>
Motivation</h2>
Many smart contract methods use a bytes</code> parameter to support future extensibility—including common standards such as ERC-721</a> and ERC-1155</a>.
The convention of carrying extra data in a bytes</code> parameter was also codified further in ERC-5750</a>.</p>
In many practical cases, the bytes</code> payload may encode a structured type that must be ABI-decoded before it can be processed. However:</p>

Different contracts use different, ad-hoc conventions for distinguishing among possible payloads.</li>
A single contract may need to support multiple encodings.</li>
In more complex workflows, a payload may be propagated across multiple contracts, each of which may need to parse it differently.</li>
</ul>
Currently, there is no standardized convention for identifying the "type" of an encoded payload, nor for supporting multiple data items in a single bytes parameter.
This ERC defines a minimal, interoperable convention for self-describing payloads that remain compatible with existing ABI tooling.</p>
Specification</h2>
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.</p>
Terms</h3>

Type string</strong> — the canonical EIP-712 type string, e.g.
TransferNote(bytes32 reference,string comment,uint256 deadline)</code></li>
Type selector (bytes4</code>)</strong> — keccak256(typeString)[0:4]</code></li>
Single-payload</strong> — a selector followed by abi.encode</code> of that struct’s fields</li>
Multi-payload wrapper</strong> — DataList(bytes[] items)</code>; each items[i]</code> is a valid single-payload</li>
</ul>
Single-payload encoding</h3>

An ABI-encoded struct is prefixed with a 4-byte selector.</li>
The selector is defined as the first 4 bytes of the keccak256 hash of its EIP-712 type string.</li>
</ul>
typeSelector(T) = bytes4(keccak256(bytes(T)))</span></span>
encoding = typeSelector(T) ++ abi.encode(<fields of T>)</span></span></code></pre>
Example:</p>
T = "TransferNote(bytes32 reference,string comment,uint256 deadline)"</span></span>
keccak256(T) = 0xf91f3a243a886588394dfd70af07dce0ca18c55e402d76152d4cb300349c9e9d</span></span>
selector = 0xf91f3a24</span></span>
encoding = 0xf91f3a24 ++ abi.encode(reference, comment, deadline)</span></span></code></pre>
A consumer may look for a known selector before attempting to decode the data, and can easily distinguish between multiple different payloads that it knows how to accept.</p>
Multi-payload wrapper</h3>

Uses a canonical wrapper type DataList(bytes[] items)</code> with selector 0xae74f986</code>.</li>
Each element in the items array is itself a single-struct payload (with its own selector).</li>
</ul>
DataList(bytes[] items)</span></span>
selector(DataList) = bytes4(keccak256("DataList(bytes[] items)")) = 0xae74f986</span></span>
encoding = 0xae74f986 ++ abi.encode(items)</span></span></code></pre>
Each items[i]</code> MUST be a valid single-payload as above.
Consumers can look for this well-known selector, and can then decode the list to be scanned recursively for recognized items.</p>
Decoding</h3>

Read the first 4 bytes as the selector</strong>.</li>
If the selector is 0xae74f986</code>, decode the remainder as (bytes[] items)</code> and parse each item recursively.</li>
If the selector is another recognized selector, the remainder should be parsed accordingly.</li>
Unknown selectors MUST be ignored.</li>
Order is not significant; producers SHOULD avoid duplicates.</li>
</ul>
Rationale</h2>

EIP-712 reuse:</strong> avoids new schema syntax and aligns with the signing ecosystem.</li>
4-byte selectors:</strong> mirror Solidity’s function selector convention for compactness.</li>
Simple wrapper:</strong> DataList</code> provides multiplexing without special parsing or new ABI rules.</li>
</ul>
Backwards Compatibility</h2>
Existing contracts that already accept arbitrary bytes</code> remain compatible. Contracts unaware of this ERC can continue to treat the payload as opaque.</p>
Security Considerations</h2>

Payload bounds:</strong> When parsing DataList</code>, consumers should limit items.length</code> and total payload size (for example ≤ 8 items and ≤ 8 KB).</li>
Early exit:</strong> Consumers should stop scanning once all expected selectors are found.</li>
Unknown data:</strong> Unrecognized items must be ignored safely.</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Groups - Membership Tokens
2025-10-28T00:00:00+00:00
Abstract</h2>
This proposal defines a "Group" as an ERC-20</a> token where token balance represents membership level. Groups are standard ERC-20 tokens with the semantic interpretation that holding tokens means membership in the group. Unlike binary membership, this supports threshold-based membership: holding more tokens grants higher membership tiers or privileges. By being pure ERC-20, Groups inherit full compatibility with existing wallets, explorers, and tooling with no additional implementation burden.</p>
Motivation</h2>
Many applications need addressable groups of accounts with controlled membership and tiered access:</p>

DAOs</strong>: Voting power proportional to token holdings</li>
Loyalty programs</strong>: Bronze/Silver/Gold tiers based on token balance</li>
Access control</strong>: Different features unlocked at different balance thresholds</li>
Partner networks</strong>: Minimum token requirements for partnership benefits</li>
</ul>
The key insight is that any ERC-20 token can represent group membership</strong>:</p>

balanceOf(account) == 0</code> → Not a member</li>
balanceOf(account) >= threshold</code> → Member at that tier</li>
</ul>
This approach provides:</p>

Zero implementation overhead</strong>: Any ERC-20 token can be a Group</li>
Instant tooling compatibility</strong>: Wallets, explorers, DEXs work out of the box</li>
Tiered membership</strong>: Different balance thresholds unlock different privileges</li>
Transferable membership</strong>: Standard ERC-20 transfers allow membership trading/delegation</li>
</ul>
Specification</h2>
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.</p>
Requirements</h3>
A compliant Group contract:</p>

MUST</strong> implement ERC-20</a></li>
MUST</strong> implement ERC-165</a></li>
SHOULD</strong> implement the optional interface defined below for membership introspection</li>
</ol>
Membership Semantics</h3>
Token balance represents membership level:</p>

balanceOf(account) == 0</code> → Account is not</strong> a member</li>
balanceOf(account) > 0</code> → Account is</strong> a member</li>
balanceOf(account) >= threshold</code> → Account qualifies for that membership tier</li>
</ul>
Applications define their own thresholds. For example:</p>

Basic membership: balanceOf(account) >= 1</code></li>
Silver tier: balanceOf(account) >= 100 * 10**decimals</code></li>
Gold tier: balanceOf(account) >= 500 * 10**decimals</code></li>
Platinum tier: balanceOf(account) >= 1000 * 10**decimals</code></li>
</ul>
Interface (Optional)</h3>
Implementations MAY expose a convenience interface for membership checks:</p>
//</span> SPDX-License-Identifier: CC0-1.0</span></span>
pragma</span> solidity</span> ^0.8.20</span>;</span></span>
</span>
///</span> @title</span> IERC8063 — Optional membership introspection for ERC-20 tokens</span></span>
interface</span> IERC8063</span> {</span></span>
    ///</span> @notice</span> Returns true if `account` holds at least `threshold` tokens</span></span>
    ///</span> @param</span> account</span> The address to check</span></span>
    ///</span> @param</span> threshold</span> Minimum balance required for membership at this tier</span></span>
    function</span> isMember</span>(</span>address</span> account</span>,</span> uint256</span> threshold</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
}</span></span></code></pre>
If implemented:</p>

isMember(account, threshold)</code> MUST return true</code> if and only if balanceOf(account) >= threshold</code>.</li>
isMember(account, 0)</code> MUST return true</code> for any account.</li>
</ul>
ERC-165 Introspection</h3>

supportsInterface(0x36372b07)</code> (ERC-20) SHOULD return true</code></li>
If the optional interface is implemented, supportsInterface</code> for it SHOULD return true</code></li>
</ul>
Deployment Model</h3>
Following the ERC-20</a> pattern, each group is its own contract deployment:</p>

Group identity</strong>: A group is uniquely identified by its contract address.</li>
Deployment</strong>: Deploy any ERC-20 token. The token IS the group.</li>
Discovery</strong>: Applications can discover groups through Transfer events, registries, or direct address references.</li>
Naming</strong>: name()</code> and symbol()</code> follow standard ERC-20 conventions.</li>
</ul>
Minting and Burning</h3>
Minting and burning are implementation-defined</strong>. Groups MAY implement minting/burning using any approach:</p>

Standard mint(address, uint256)</code> function</li>
ERC-5679</a> compliant mint(address, uint256, bytes)</code></li>
No minting after initial supply (fixed membership)</li>
Governance-controlled minting</li>
Open minting (anyone can join by minting)</li>
</ul>
The standard does not mandate any specific minting/burning interface.</p>
Tiered Benefits Example</h3>
Applications define membership tiers externally:</p>
//</span> Example: Partner contract checking membership tiers</span></span>
contract</span> PartnerBenefits</span> {</span></span>
    IERC20 </span>public</span> membershipToken</span>;</span></span>
    </span></span>
    uint256</span> public</span> constant</span> BRONZE </span>=</span> 100</span> *</span> 10</span>*</span>*</span>18</span>;</span></span>
    uint256</span> public</span> constant</span> SILVER </span>=</span> 500</span> *</span> 10</span>*</span>*</span>18</span>;</span></span>
    uint256</span> public</span> constant</span> GOLD </span>=</span> 1000</span> *</span> 10</span>*</span>*</span>18</span>;</span></span>
    </span></span>
    function</span> getDiscount</span>(</span>address</span> user</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span> {</span></span>
        uint256</span> balance </span>=</span> membershipToken</span>.</span>balanceOf</span>(</span>user</span>)</span>;</span></span>
        if</span> (</span>balance </span>></span>=</span> GOLD</span>)</span> return</span> 30</span>;</span>   //</span> 30% off</span></span>
        if</span> (</span>balance </span>></span>=</span> SILVER</span>)</span> return</span> 20</span>;</span> //</span> 20% off</span></span>
        if</span> (</span>balance </span>></span>=</span> BRONZE</span>)</span> return</span> 10</span>;</span> //</span> 10% off</span></span>
        return</span> 0</span>;</span></span>
    }</span></span>
    </span></span>
    function</span> isMember</span>(</span>address</span> user</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span>
        return</span> membershipToken</span>.</span>balanceOf</span>(</span>user</span>)</span> ></span> 0</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Optional Extensions</h3>
Ownership (via ERC-173</a>)</h4>
Implementations that want a single-owner governance model MAY use ERC-173</a> or ERC-8023</a> for standardized ownership.</p>
Capped Membership (Balance ≤ 1)</h4>
For use cases requiring binary membership (member/non-member with no tiers), implementations MAY enforce balanceOf(account) <= 1</code> for all accounts.</p>
Rationale</h2>

Pure ERC-20</strong>: A Group is simply an ERC-20 token with membership semantics. No new token standard needed.</li>
No minting/burning mandate</strong>: Different use cases need different minting policies. The standard doesn't prescribe one.</li>
Threshold-based membership</strong>: More flexible than binary membership; supports tiered access, loyalty programs, and proportional voting naturally.</li>
Optional interface</strong>: The isMember</code> function is a convenience; applications can directly call balanceOf</code> if preferred.</li>
Maximum compatibility</strong>: Any existing ERC-20 token can be interpreted as a Group by applications.</li>
</ul>
Backwards Compatibility</h2>
This standard is fully backwards compatible with ERC-20</a>. In fact, any existing ERC-20 token can be used as a Group</strong> — the standard simply defines how to interpret token balance as membership.</p>
Reference Implementation</h2>
Reference contracts are provided in the assets/</code> directory:</p>

IERC8063.sol</code></a> — Interface definition</li>
ERC8063.sol</code></a> — Reference implementation with membership helpers</li>
</ul>
Security Considerations</h2>

Token economics</strong>: Membership is tied to token balance. Consider the implications of token transfers, trading, and price volatility on membership.</li>
Threshold manipulation</strong>: If thresholds are stored onchain, ensure they cannot be manipulated by unauthorized parties.</li>
Transfer implications</strong>: Token transfers change membership. Consider whether this is desirable for your use case.</li>
Approval risks</strong>: Standard ERC-20 approval risks apply. Approving another address grants them ability to transfer your membership tokens.</li>
Decimal handling</strong>: Ensure thresholds account for the token's decimals.</li>
Minting security</strong>: If minting is permitted, carefully control who can mint to prevent unauthorized membership grants.</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Scaled UI Amount Extension for ERC-20 Tokens
2025-10-20T00:00:00+00:00
Abstract</h2>
This EIP proposes a standard extension to ERC-20</a> tokens that enables issuers to apply an updatable multiplier to the UI (user interface) amount of tokens. This allows for efficient representation of stock splits, without requiring actual token minting or transfers. The extension provides a cosmetic layer that modifies how token balances are displayed to users while maintaining the underlying token economics.</p>
Motivation</h2>
Current ERC-20 implementations lack an efficient mechanism to handle real-world asset scenarios such as stock splits: When a company performs a 2-for-1 stock split, all shareholders should see their holdings double. Currently, this requires minting new tokens to all holders, which is gas-intensive and operationally complex. Moreover, the internal accounting in DeFi protocols would break from such a split.</p>
The inability to efficiently handle this scenario limits the adoption of tokenized real-world assets (RWAs) on Ethereum. This EIP addresses these limitations by introducing a multiplier mechanism that adjusts the displayed balance without altering the actual token supply.</p>
Specification</h2>
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.</p>
Core Interface</h3>
Compliant contracts MUST implement the IScaledUIAmount</code> interface:</p>
interface</span> IScaledUIAmount</span> {</span></span>
    //</span> Emitted when the UI multiplier is updated</span></span>
    event</span> UIMultiplierUpdated</span>(</span>uint256</span> oldMultiplier</span>, </span>uint256</span> newMultiplier</span>, </span>uint256</span> effectiveAtTimestamp</span>)</span>;</span></span>
</span>
    //</span> OPTIONAL: Emitted during a token transfer with the UI-adjusted amount</span></span>
    event</span> TransferWithUIAmount</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> amount</span>, </span>uint256</span> uiAmount</span>)</span>;</span></span>
</span>
    //</span> Returns the current UI multiplier</span></span>
    //</span> Multiplier is represented with 18 decimals (1e18 = 1.0)</span></span>
    function</span> uiMultiplier</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
}</span></span></code></pre>
Note: How the multiplier is updated is an implementation detail left to the token issuer. The reference implementation below shows one approach using a setUIMultiplier</code> function with delayed effectiveness.</p>
Optional Extension: Conversion</h3>
Contracts MAY implement the IScaledUIAmountConversion</code> extension for on-chain conversion helpers:</p>
interface</span> IScaledUIAmountConversion</span> {</span></span>
    //</span> Converts a raw token amount to UI amount</span></span>
    function</span> toUIAmount</span>(</span>uint256</span> rawAmount</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
</span>
    //</span> Converts a UI amount to raw token amount</span></span>
    function</span> fromUIAmount</span>(</span>uint256</span> uiAmount</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
}</span></span></code></pre>Optional Extension: Balances</h3>
Contracts MAY implement the IScaledUIAmountBalances</code> extension for on-chain UI balance queries:</p>
interface</span> IScaledUIAmountBalances</span> {</span></span>
    //</span> Returns the UI-adjusted balance of an account</span></span>
    function</span> balanceOfUI</span>(</span>address</span> account</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
</span>
    //</span> Returns the UI-adjusted total supply</span></span>
    function</span> totalSupplyUI</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
}</span></span></code></pre>Interface Detection</h3>
Compliant contracts MUST implement ERC-165</a> and return true</code> when queried for the IScaledUIAmount</code> interface ID.</p>
Contracts implementing optional extensions MUST also return true</code> for their respective interface IDs.</p>
The interface identifiers are:</p>

IScaledUIAmount</code>: 0xa60bf13d</code></li>
IScaledUIAmountConversion</code>: 0xTBD</code></li>
IScaledUIAmountBalances</code>: 0xd890fd71</code></li>
</ul>
Implementation Requirements:</h3>


ERC-165 Support: Compliant contracts MUST implement ERC-165</a> interface detection.</p>
</li>

Multiplier Precision: The UI multiplier MUST use 18 decimal places for precision (1e18 represents a multiplier of 1.0).</p>
</li>

Backwards Compatibility: The standard ERC-20 functions (balanceOf, transfer, transferFrom, etc.) MUST continue to work with raw amounts.</p>
</li>

Event Emission: The UIMultiplierUpdated event MUST be emitted whenever the multiplier is changed.</p>
</li>
</ol>
Reference Implementation</h3>
The following implementation includes the core interface and all optional extensions:</p>
contract</span> ScaledUIToken</span> is</span></span>
    ERC20</span>,</span></span>
    ERC165</span>,</span></span>
    IScaledUIAmount</span>,</span></span>
    IScaledUIAmountConversion</span>,</span></span>
    IScaledUIAmountBalances</span>,</span></span>
    Ownable</span></span>
{</span></span>
    uint256</span> private</span> constant</span> MULTIPLIER_DECIMALS </span>=</span> 1e18</span>;</span></span>
    uint256</span> private</span> _uiMultiplier </span>=</span> MULTIPLIER_DECIMALS</span>;</span> //</span> Initially 1.0</span></span>
    uint256</span> public</span> _nextUiMultiplier </span>=</span> MULTIPLIER_DECIMALS</span>;</span></span>
    uint256</span> public</span> _nextUiMultiplierEffectiveAt </span>=</span> 0</span>;</span></span>
</span>
    constructor</span>(</span>string</span> memory</span> name</span>,</span> string</span> memory</span> symbol</span>)</span> ERC20</span>(</span>name, symbol) </span>{</span>}</span></span>
</span>
    //</span> ERC-165 interface detection</span></span>
    function</span> supportsInterface</span>(</span>bytes4</span> interfaceId</span>)</span> public</span> view</span> virtual</span> override</span> returns</span> (</span>bool</span>)</span> {</span></span>
        return</span></span>
            interfaceId </span>==</span> type</span>(</span>IScaledUIAmount</span>)</span>.</span>interfaceId </span>||</span></span>
            interfaceId </span>==</span> type</span>(</span>IScaledUIAmountConversion</span>)</span>.</span>interfaceId </span>||</span></span>
            interfaceId </span>==</span> type</span>(</span>IScaledUIAmountBalances</span>)</span>.</span>interfaceId </span>||</span></span>
            super</span>.</span>supportsInterface</span>(</span>interfaceId</span>)</span>;</span></span>
    }</span></span>
</span>
    //</span> ============ Core Interface ============</span></span>
</span>
    function</span> uiMultiplier</span>(</span>)</span> public</span> view</span> override</span> returns</span> (</span>uint256</span>)</span> {</span></span>
        uint256</span> currentTime </span>=</span> block</span>.</span>timestamp</span>;</span></span>
        if</span> (</span>currentTime </span>></span>=</span> _nextUiMultiplierEffectiveAt</span>)</span> {</span></span>
            return</span> _nextUiMultiplier</span>;</span></span>
        }</span> else</span> {</span></span>
            return</span> _uiMultiplier</span>;</span></span>
        }</span></span>
    }</span></span>
</span>
    //</span> Implementation-specific: How the multiplier is updated</span></span>
    function</span> setUIMultiplier</span>(</span>uint256</span> newMultiplier</span>,</span> uint256</span> effectiveAtTimestamp</span>)</span> external</span> onlyOwner</span> {</span></span>
        require</span>(</span>newMultiplier </span>></span> 0</span>,</span> "Multiplier must be positive"</span>)</span>;</span></span>
</span>
        uint256</span> currentTime </span>=</span> block</span>.</span>timestamp</span>;</span></span>
        require</span>(</span>effectiveAtTimestamp </span>></span> currentTime</span>,</span> "Effective At must be in the future"</span>)</span>;</span></span>
</span>
        if</span> (</span>currentTime </span>></span> _nextUiMultiplierEffectiveAt</span>)</span> {</span></span>
            uint256</span> oldMultiplier </span>=</span> _nextUiMultiplier</span>;</span></span>
            _uiMultiplier </span>=</span> oldMultiplier</span>;</span></span>
            _nextUiMultiplier </span>=</span> newMultiplier</span>;</span></span>
            _nextUiMultiplierEffectiveAt </span>=</span> effectiveAtTimestamp</span>;</span></span>
            emit</span> UIMultiplierUpdated</span>(</span>oldMultiplier</span>,</span> newMultiplier</span>,</span> effectiveAtTimestamp</span>)</span>;</span></span>
        }</span> else</span> {</span></span>
            uint256</span> oldMultiplier </span>=</span> _uiMultiplier</span>;</span></span>
            _nextUiMultiplier </span>=</span> newMultiplier</span>;</span></span>
            _nextUiMultiplierEffectiveAt </span>=</span> effectiveAtTimestamp</span>;</span></span>
            emit</span> UIMultiplierUpdated</span>(</span>oldMultiplier</span>,</span> newMultiplier</span>,</span> effectiveAtTimestamp</span>)</span>;</span></span>
        }</span></span>
    }</span></span>
</span>
    //</span> ============ Optional: Conversion Extension ============</span></span>
</span>
    function</span> toUIAmount</span>(</span>uint256</span> rawAmount</span>)</span> public</span> view</span> override</span> returns</span> (</span>uint256</span>)</span> {</span></span>
        uint256</span> currentTime </span>=</span> block</span>.</span>timestamp</span>;</span></span>
        if</span> (</span>currentTime </span>></span>=</span> _nextUiMultiplierEffectiveAt</span>)</span> {</span></span>
            return</span> (</span>rawAmount </span>*</span> _nextUiMultiplier</span>)</span> /</span> MULTIPLIER_DECIMALS</span>;</span></span>
        }</span> else</span> {</span></span>
            return</span> (</span>rawAmount </span>*</span> _uiMultiplier</span>)</span> /</span> MULTIPLIER_DECIMALS</span>;</span></span>
        }</span></span>
    }</span></span>
</span>
    function</span> fromUIAmount</span>(</span>uint256</span> uiAmount</span>)</span> public</span> view</span> override</span> returns</span> (</span>uint256</span>)</span> {</span></span>
        uint256</span> currentTime </span>=</span> block</span>.</span>timestamp</span>;</span></span>
        if</span> (</span>currentTime </span>></span>=</span> _nextUiMultiplierEffectiveAt</span>)</span> {</span></span>
            return</span> (</span>uiAmount </span>*</span> MULTIPLIER_DECIMALS</span>)</span> /</span> _nextUiMultiplier</span>;</span></span>
        }</span> else</span> {</span></span>
            return</span> (</span>uiAmount </span>*</span> MULTIPLIER_DECIMALS</span>)</span> /</span> _uiMultiplier</span>;</span></span>
        }</span></span>
    }</span></span>
</span>
    //</span> ============ Optional: Balances Extension ============</span></span>
</span>
    function</span> balanceOfUI</span>(</span>address</span> account</span>)</span> public</span> view</span> override</span> returns</span> (</span>uint256</span>)</span> {</span></span>
        return</span> toUIAmount</span>(</span>balanceOf</span>(</span>account</span>)</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> totalSupplyUI</span>(</span>)</span> public</span> view</span> override</span> returns</span> (</span>uint256</span>)</span> {</span></span>
        return</span> toUIAmount</span>(</span>totalSupply</span>(</span>)</span>)</span>;</span></span>
    }</span></span>
</span>
    //</span> ============ Optional: TransferWithUIAmount Event ============</span></span>
</span>
    function</span> _update</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> amount</span>)</span> internal</span> virtual</span> override</span> {</span></span>
        super</span>.</span>_update</span>(</span>from</span>,</span> to</span>,</span> amount</span>)</span>;</span></span>
        uint256</span> uiAmount </span>=</span> toUIAmount</span>(</span>amount</span>)</span>;</span></span>
        emit</span> TransferWithUIAmount</span>(</span>from</span>,</span> to</span>,</span> amount</span>,</span> uiAmount</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Rationale</h2>
Design Decisions:</p>


Separate UI Functions: Rather than modifying the core ERC-20 functions, we provide separate UI-specific functions. This ensures backward compatibility and allows integrators to opt-in to the UI scaling feature.</p>
</li>

18 Decimal Precision: Using 18 decimals for the multiplier provides sufficient precision for most use cases while aligning with Ethereum's standard decimal representation.</p>
</li>

No Automatic Updates: The multiplier must be explicitly set by authorized parties, giving issuers full control over when and how adjustments are made.</p>
</li>

Raw Amount Preservation: All actual token operations continue to use raw amounts, ensuring that the multiplier is purely a display feature and doesn't affect the underlying token economics.</p>
</li>

Optional Extensions: Following the pattern established by ERC-721</a> and ERC-1155</a>, helper functions like toUIAmount</code>, fromUIAmount</code>, balanceOfUI</code>, and totalSupplyUI</code> are defined in separate optional interfaces. The TransferWithUIAmount</code> event is defined in the core interface as optional since events do not affect interface IDs. This keeps the core interface minimal while allowing contracts to opt-in to additional on-chain functionality. Integrators can detect support for these extensions using ERC-165</a> interface detection.</p>
</li>
</ol>
Alternative Approaches Considered:</p>


Rebasing Tokens: While rebasing tokens adjust supply automatically, they create complexity for integrators and can break composability with DeFi protocols.</p>
</li>

Wrapper Tokens: Creating wrapper tokens for each adjustment event adds unnecessary complexity and gas costs.</p>
</li>

Index/Exchange Rate Tokens confer similar advantages to the proposed Scaled UI approach, but is ultimately less intuitive and requires more calculations on the UI layers.</p>
</li>

Off-chain Solutions: Purely off-chain solutions lack standardization and require trust in centralized providers.</p>
</li>
</ol>
</p>
</p>
Backwards Compatibility</h3>
This EIP is fully backwards compatible with ERC-20. Existing ERC-20 functions continue to work as expected, and the UI scaling features are opt-in through additional functions.</p>
Test Cases</h3>
Example test scenarios:</p>

Initial Multiplier Test:</li>
</ol>


Verify that initial multiplier is 1.0 (1e18)</p>
</li>

Confirm balanceOf equals balanceOfUI initially</p>
</li>
</ul>

Stock Split Test:</li>
</ol>


Set multiplier to 2.0 (2e18) for 2-for-1 split</p>
</li>

Verify UI balance is double the raw balance</p>
</li>

Confirm conversion functions work correctly</p>
</li>
</ul>
Security Considerations</h2>

Multiplier Manipulation</li>
</ol>


Unauthorized changes to the UI multiplier could mislead users about their holdings</p>
</li>

Implementations MUST use robust access control mechanisms</p>
</li>

The setUIMultiplier function MUST be restricted to authorized addresses (e.g., contract owner or a designated role).</p>
</li>
</ul>

Integer Overflow</li>
</ol>


Risk of overflow when applying the multiplier</p>
</li>

Use SafeMath or Solidity 0.8.0+ automatic overflow protection</p>
</li>
</ul>

User Confusion</li>
</ol>


Clear communication is essential when UI amounts differ from raw amounts</p>
</li>

Integrators MUST clearly indicate when displaying UI-adjusted balances</p>
</li>
</ul>

Oracle Dependency</li>
</ol>


For automated multiplier updates, the system may depend on oracles</p>
</li>

Oracle failures or manipulations could affect displayed balances</p>
</li>
</ul>

Overflow Protection: Implementations MUST handle potential overflow when applying the multiplier.</li>
</ol>
Implementation Guide for Integrators</h3>
Wallet Integration</h4>
Wallets supporting this standard should:</p>


Check if a token implements IScaledUIAmount</code> interface using ERC-165</p>
</li>

Optionally check for IScaledUIAmountBalances</code> extension for on-chain balance queries</p>
</li>

Display both raw and UI amounts, clearly labeled</p>
</li>

Compute UI balance off-chain using balanceOf()</code> and uiMultiplier()</code>, or use balanceOfUI()</code> if the extension is supported</p>
</li>

Handle transfers using raw amounts (standard ERC-20 functions)</p>
</li>
</ol>
Example JavaScript integration:</strong></p>
const</span> MULTIPLIER_DECIMALS</span> =</span> BigInt</span>(</span>1e18</span>)</span>;</span></span>
</span>
//</span> Interface IDs for ERC-165 detection</span></span>
const</span> ISCALED_UI_AMOUNT_ID</span> =</span> "</span>0xa60bf13d</span>"</span>;</span></span>
const</span> ISCALED_UI_BALANCES_ID</span> =</span> "</span>0xd890fd71</span>"</span>;</span></span>
</span>
//</span> Off-chain conversion functions</span></span>
function</span> toUIAmount</span>(</span>rawAmount</span>,</span> multiplier</span>)</span> {</span></span>
    return</span> (</span>BigInt</span>(</span>rawAmount</span>)</span> *</span> BigInt</span>(</span>multiplier</span>)</span>)</span> /</span> MULTIPLIER_DECIMALS</span>;</span></span>
}</span></span>
</span>
function</span> fromUIAmount</span>(</span>uiAmount</span>,</span> multiplier</span>)</span> {</span></span>
    return</span> (</span>BigInt</span>(</span>uiAmount</span>)</span> *</span> MULTIPLIER_DECIMALS</span>)</span> /</span> BigInt</span>(</span>multiplier</span>)</span>;</span></span>
}</span></span>
</span>
async</span> function</span> displayBalance</span>(</span>tokenAddress</span>,</span> userAddress</span>)</span> {</span></span>
    const</span> token</span> =</span> new</span> ethers</span>.</span>Contract</span>(</span>tokenAddress</span>,</span> ScaledUIAmountABI</span>,</span> provider</span>)</span>;</span></span>
</span>
    //</span> Check if core scaled UI is supported</span></span>
    const</span> supportsScaledUI</span> =</span> await</span> token</span>.</span>supportsInterface</span>(</span>ISCALED_UI_AMOUNT_ID</span>)</span>;</span></span>
</span>
    if</span> (</span>!</span>supportsScaledUI</span>)</span> {</span></span>
        //</span> Fall back to standard ERC-20</span></span>
        const</span> balance</span> =</span> await</span> token</span>.</span>balanceOf</span>(</span>userAddress</span>)</span>;</span></span>
        return</span> {</span></span>
            display</span>:</span> formatUnits</span>(</span>balance</span>,</span> decimals</span>)</span>,</span></span>
            raw</span>:</span> formatUnits</span>(</span>balance</span>,</span> decimals</span>)</span>,</span></span>
            multiplier</span>:</span> "</span>1.0</span>"</span></span>
        }</span>;</span></span>
    }</span></span>
</span>
    //</span> Check if optional balances extension is supported</span></span>
    const</span> supportsBalancesExt</span> =</span> await</span> token</span>.</span>supportsInterface</span>(</span>ISCALED_UI_BALANCES_ID</span>)</span>;</span></span>
</span>
    const</span> rawBalance</span> =</span> await</span> token</span>.</span>balanceOf</span>(</span>userAddress</span>)</span>;</span></span>
    const</span> multiplier</span> =</span> await</span> token</span>.</span>uiMultiplier</span>(</span>)</span>;</span></span>
</span>
    //</span> Use on-chain balanceOfUI if available, otherwise compute off-chain</span></span>
    const</span> uiBalance</span> =</span> supportsBalancesExt</span></span>
        ?</span> await</span> token</span>.</span>balanceOfUI</span>(</span>userAddress</span>)</span></span>
        :</span> toUIAmount</span>(</span>rawBalance</span>,</span> multiplier</span>)</span>;</span></span>
</span>
    return</span> {</span></span>
        display</span>:</span> formatUnits</span>(</span>uiBalance</span>,</span> decimals</span>)</span>,</span></span>
        raw</span>:</span> formatUnits</span>(</span>rawBalance</span>,</span> decimals</span>)</span>,</span></span>
        multiplier</span>:</span> formatUnits</span>(</span>multiplier</span>,</span> 18</span>)</span></span>
    }</span>;</span></span>
}</span></span></code></pre>Exchange Integration</h4>
Exchanges should:</p>


Store and track the multiplier for each supported token</p>
</li>

Display UI amounts in user interfaces</p>
</li>

Use raw amounts for all internal accounting</p>
</li>

Provide clear documentation about the scaling mechanism</p>
</li>
</ol>
Example implementation:</p>
const</span> MULTIPLIER_DECIMALS</span> =</span> BigInt</span>(</span>1e18</span>)</span>;</span></span>
</span>
class</span> ScaledTokenHandler</span> {</span></span>
    //</span> Off-chain conversion functions</span></span>
    toUIAmount</span>(</span>rawAmount</span>,</span> multiplier</span>)</span> {</span></span>
        return</span> (</span>BigInt</span>(</span>rawAmount</span>)</span> *</span> BigInt</span>(</span>multiplier</span>)</span>)</span> /</span> MULTIPLIER_DECIMALS</span>;</span></span>
    }</span></span>
</span>
    fromUIAmount</span>(</span>uiAmount</span>,</span> multiplier</span>)</span> {</span></span>
        return</span> (</span>BigInt</span>(</span>uiAmount</span>)</span> *</span> MULTIPLIER_DECIMALS</span>)</span> /</span> BigInt</span>(</span>multiplier</span>)</span>;</span></span>
    }</span></span>
</span>
    async</span> processDeposit</span>(</span>tokenAddress</span>,</span> amount</span>,</span> isUIAmount</span>)</span> {</span></span>
        const</span> token</span> =</span> new</span> ethers</span>.</span>Contract</span>(</span>tokenAddress</span>,</span> ScaledUIAmountABI</span>,</span> provider</span>)</span>;</span></span>
</span>
        let</span> rawAmount</span>;</span></span>
        if</span> (</span>isUIAmount</span> &&</span> await</span> this</span>.</span>supportsScaledUI</span>(</span>tokenAddress</span>)</span>)</span> {</span></span>
            const</span> multiplier</span> =</span> await</span> token</span>.</span>uiMultiplier</span>(</span>)</span>;</span></span>
            rawAmount</span> =</span> this</span>.</span>fromUIAmount</span>(</span>amount</span>,</span> multiplier</span>)</span>;</span></span>
        }</span> else</span> {</span></span>
            rawAmount</span> =</span> amount</span>;</span></span>
        }</span></span>
</span>
        //</span> Process deposit with raw amount</span></span>
        return</span> this</span>.</span>recordDeposit</span>(</span>tokenAddress</span>,</span> rawAmount</span>)</span>;</span></span>
    }</span></span>
</span>
    async</span> getDisplayBalance</span>(</span>tokenAddress</span>,</span> userAddress</span>)</span> {</span></span>
        const</span> token</span> =</span> new</span> ethers</span>.</span>Contract</span>(</span>tokenAddress</span>,</span> ScaledUIAmountABI</span>,</span> provider</span>)</span>;</span></span>
        const</span> rawBalance</span> =</span> await</span> this</span>.</span>getInternalBalance</span>(</span>userAddress</span>,</span> tokenAddress</span>)</span>;</span></span>
</span>
        if</span> (</span>await</span> this</span>.</span>supportsScaledUI</span>(</span>tokenAddress</span>)</span>)</span> {</span></span>
            const</span> multiplier</span> =</span> await</span> token</span>.</span>uiMultiplier</span>(</span>)</span>;</span></span>
            return</span> this</span>.</span>toUIAmount</span>(</span>rawBalance</span>,</span> multiplier</span>)</span>;</span></span>
        }</span></span>
        return</span> rawBalance</span>;</span></span>
    }</span></span>
}</span></span>
</span></code></pre>DeFi Protocol Integration</h4>
DeFi protocols should:</p>


Continue using raw amounts for all protocol operations</p>
</li>

Provide UI helpers for displaying adjusted amounts</p>
</li>

Emit events with both raw and UI amounts where relevant</p>
</li>

Document clearly which amounts are used in calculations</p>
</li>
</ol>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Zero Knowledge Token Wrapper
2025-10-18T00:00:00+00:00
Abstract</h2>
This ERC defines a standard for the Zero Knowledge Token Wrapper, a wrapper that adds privacy to tokens — including ERC-20</a>, ERC-721</a>, ERC-1155</a> and ERC-6909</a> — while preserving all of the tokens' original properties, such as transferability, tradability, and composability. It specifies EIP-7503</a>-style provable burn-and-remint flows, enabling users to break on-chain traceability and making privacy a native feature of all tokens on Ethereum.</p>
Motivation</h2>
Most existing tokens lack native privacy due to regulatory, technical, and issuer-side neglect. Users seeking privacy must rely on dedicated privacy blockchains or privacy-focused dApps, which restrict token usability, reduce composability, limit supported token types, impose whitelists, and constrain privacy schemes.</p>
This ERC takes a different approach by introducing a zero knowledge token wrapper that preserves the underlying token’s properties while adding privacy. Its primary goals are:</p>

Pluggable privacy: the wrapper preserves all properties of the underlying token while adding privacy.</li>
Permissionless privacy: any user can wrap any token into a Zero Knowledge Wrapped Token (ZWToken).</li>
Broad token support: compatible with both fungible tokens (e.g., ETH, ERC-20) and non-fungible tokens (e.g., ERC-721).</li>
EIP-7503-style privacy: supports provable burn-and-remint flows to achieve high-level privacy.</li>
Compatibility with multiple EIP-7503 schemes: supports different provable burn address generation methods and commitment schemes (e.g., Ethereum-native MPT state tree or contract-managed commitments).</li>
</ul>
Specification</h2>
The key words MUST</strong>, MUST NOT</strong>, SHOULD</strong>, SHOULD NOT</strong>, and MAY</strong> in this document are to be interpreted as described in RFC 2119 and RFC 8174.</p>
Overview</h3>
A Zero Knowledge Wrapped Token (ZWToken) is a wrapped token minted by a Zero Knowledge Token Wrapper. It adds a commitment-based privacy layer to existing tokens, including ERC-20, ERC-721, ERC-1155, ERC-6909. This privacy layer allows private transfers without modifying the underlying token standard, while preserving full composability with existing Ethereum infrastructure.</p>
The commitment mechanism underlying this privacy layer may be implemented using Merkle trees, cryptographic accumulators, or any other verifiable cryptographic structure.</p>
A Zero Knowledge Wrapped Token (ZWToken) provides the following core functionalities:</p>
The ZWToken recipient can be a provable burn address, from which the tokens can later be reminted.</p>

Deposit: Wraps an existing token and mints ZWToken to the specified recipient.</li>
Transfer: Transfers ZWToken to the specified recipient.</li>
Remint: Mints new ZWTokens to the specified recipient after verifying a zero-knowledge proof demonstrating ownership of previously burnt tokens, without revealing the link between them.</li>
Withdraw: Burns ZWTokens to redeem the underlying tokens to the specified recipient.</li>
</ul>
Privacy Features by Token Type</h4>
For fungible tokens (FTs), e.g., ERC-20:</p>

This ERC enables breaking the traceability of fund flows through the burn and remint processes.</li>
The use of provable burn addresses hides the true holder of fungible tokens until the holder performs a withdraw operation of ZWToken.</li>
</ul>
For non-fungible tokens (NFTs), e.g., ERC-721:</p>

This ERC cannot</strong> break the traceability of fund flows through burn and remint, since each NFT is unique and cannot participate in coin-mixing.</li>
However, the use of provable burn addresses can still conceal the true holder of the NFT until the holder performs a withdraw operation of ZWToken.</li>
</ul>
ZWToken-aware Workflow</h4>
In the ZWToken-aware workflow, both the user and the system explicitly recognize and interact with ZWToken. ZWToken inherits all functional properties of the underlying token.</p>
</p>
For example, if the underlying token is ERC-20, ZWToken can be traded on DEXs, used for swaps, liquidity provision, or standard transfers. Similar to how holding WETH provides additional benefits over holding ETH directly, users may prefer to hold ZWToken rather than the underlying token.</p>
ZWToken-unaware Workflow</h4>
This ERC also supports a ZWToken-unaware workflow. In this mode, all transfers are internally handled through ZWToken, but users remain unaware of its existence.</p>
</p>
ZWToken functions transparently beneath the user interface, reducing the number of required contract interactions and improving overall user experience for those who prefer not to hold ZWToken directly.</p>
Alternative Workflows</h4>
The two workflows described above represent only a subset of the interaction patterns supported by this ERC. Additional workflows are also possible, including:</p>


Reminting by the recipient:</strong>
Alice may transfer</code> (in the ZWToken-aware workflow) or deposit</code> (in the ZWToken-unaware workflow) ZWToken to Bob’s provable burn address</strong> instead of her own. In this case, the remint operation is initiated and proven by Bob rather than Alice</strong>.</p>
</li>

Recursive reminting:</strong>

A reminted ZWToken may also be sent to another provable burn address</strong> controlled by Bob instead of his public address, allowing the privacy state to persist across multiple remint cycles.</p>
</li>
</ul>
The interface:</p>
interface</span> IERC8065</span> is</span> IERC165</span> {</span></span>
    struct</span> RemintData</span> {</span></span>
        bytes32</span> commitment</span>;</span></span>
        bytes32</span>[</span>]</span> nullifiers</span>;</span></span>
        bytes</span> proverData</span>;</span></span>
        bytes</span> relayerData</span>;</span></span>
        bool</span> redeem</span>;</span></span>
        bytes</span> proof</span>;</span></span>
    }</span></span>
</span>
    //</span> Optional</span></span>
    event</span> CommitmentUpdated</span>(</span>uint256</span> indexed</span> id</span>, </span>bytes32</span> indexed</span> commitment</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> amount</span>)</span>;</span></span>
</span>
    event</span> Deposited</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>)</span>;</span></span>
</span>
    event</span> Withdrawn</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>)</span>;</span></span>
</span>
    event</span> Reminted</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>, </span>bool</span> redeem</span>)</span>;</span></span>
</span>
    function</span> deposit</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> payable</span>;</span></span>
</span>
    function</span> withdraw</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span>;</span></span>
</span>
    function</span> remint</span>(</span></span>
        address</span> to</span>,</span></span>
        uint256</span> id</span>,</span></span>
        uint256</span> amount</span>,</span></span>
        RemintData</span> calldata</span> data</span></span>
    )</span> external</span>;</span></span>
</span>
    //</span> Optional</span></span>
    function</span> previewDeposit</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
</span>
    //</span> Optional</span></span>
    function</span> previewWithdraw</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
</span>
    //</span> Optional</span></span>
    function</span> previewRemint</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> RemintData</span> calldata</span> data</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
</span>
    function</span> getLatestCommitment</span>(</span>uint256</span> id</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span>
</span>
    function</span> hasCommitment</span>(</span>uint256</span> id</span>,</span> bytes32</span> commitment</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
</span>
    //</span> Optional</span></span>
    function</span> getCommitLeafCount</span>(</span>uint256</span> id</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
</span>
    //</span> Optional</span></span>
    function</span> getCommitLeaves</span>(</span>uint256</span> id</span>,</span> uint256</span> startIndex</span>,</span> uint256</span> length</span>)</span></span>
    external</span> view</span> returns</span> (</span>bytes32</span>[</span>]</span> memory</span> commitHashes</span>,</span> address</span>[</span>]</span> memory</span> recipients</span>,</span> uint256</span>[</span>]</span> memory</span> amounts</span>)</span>;</span></span>
</span>
    function</span> getUnderlying</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
}</span></span></code></pre>Deposit / Wrap</h3>
///</span> @notice</span> Deposits a specified amount of the underlying asset and mints the corresponding amount of ZWToken to the given address.</span></span>
///</span> @dev</span></span>
///</span> If the underlying asset is an ERC-20/ERC-721/ERC-1155/ERC-6909 token, the caller must approve this contract to transfer the specified `amount` beforehand.</span></span>
///</span> If the underlying asset is ETH, the caller should send the deposit value along with the transaction (`msg.value`), and `msg.value` MUST be equal to `amount`.</span></span>
///</span> @param</span> to</span> The address that will receive the minted ZWTokens.</span></span>
///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span>
///</span> @param</span> amount</span> The amount of the underlying asset to deposit.</span></span>
///</span> @param</span> data</span> Additional data for extensibility, such as fee information, callback data, or metadata.</span></span>
function</span> deposit</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> payable</span>;</span></span></code></pre>


Depositor SHOULD be msg.sender</code>.</p>
</li>

The function MUST transfer the specified amount</code> of the underlying asset from depositor</code> to the ZWToken contract.</p>

If the underlying asset is an ERC-20, ERC-721, ERC-1155 or ERC-6909 token, the caller MUST approve this contract to transfer the specified amount</code> beforehand.</li>
If the underlying asset is ETH, the caller MUST send the deposit value along with the transaction (msg.value</code>), and msg.value</code> MUST be equal to amount</code>.</li>
</ul>
</li>

The function SHOULD mint ZWToken to the recipient to</code>. The amount minted MAY be reduced by fees as defined by the implementation.</p>
</li>

Commitment Update:</p>

For contract-level commitment schemes, since to may be a provable burn address, the implementation SHOULD update the corresponding commitment.

However, this MAY be optimized: if to</code> == depositor</code>, the implementation MAY skip updating the commitment, as depositor</code> cannot be a provable burn address (otherwise the transaction could not be initiated).</li>
</ul>
</li>
For protocol-level commitment schemes (e.g., Ethereum’s native Merkle Patricia Trie), the commitment (e.g., state root or block hash) is automatically updated by the protocol.</li>
</ul>
</li>

The function MUST emit a Deposited(depositor, to, id, amount)</code> event upon successful deposit.</p>

The amount</code> parameter in the Deposited</code> event represents the net amount of ZWToken received by to</code> after deducting applicable fees, rather than the amount of underlying tokens deposited.</li>
</ul>
</li>

The data</code> parameter is reserved for future extensibility and MAY be used to pass additional information such as fee configurations, callback data, or metadata. Implementations MAY ignore this parameter if not needed.</p>
</li>
</ul>
Withdraw / Unwrap</h3>
///</span> @notice</span> Withdraw underlying tokens by burning ZWToken</span></span>
///</span> @param</span> to</span> The recipient address that will receive the underlying token</span></span>
///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span>
///</span> @param</span> amount</span> The amount of ZWToken to burn and redeem for the underlying token</span></span>
///</span> @param</span> data</span> Additional data for extensibility, such as fee information, callback data, or metadata.</span></span>
function</span> withdraw</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span>;</span></span></code></pre>

Withdrawer SHOULD be msg.sender</code>.</li>
The function MUST burn the specified amount</code> of ZWToken from withdrawer.</li>
The function SHOULD transfer underlying token to the recipient to</code>. The amount transferred MAY be reduced by fees as defined by the implementation.</li>
The function MUST emit a Withdrawn(withdrawer, to, id, amount)</code> event upon successful withdrawal.

The amount</code> parameter in the Withdrawn</code> event represents the net amount of underlying tokens received by to</code> after deducting applicable fees, rather than the amount of ZWToken burned.</li>
</ul>
</li>
The data</code> parameter is reserved for future extensibility and MAY be used to pass additional information such as fee configurations, callback data, or metadata. Implementations MAY ignore this parameter if not needed.</li>
</ul>
Transfer and Update Commitment</h3>

The Zero Knowledge Wrapped Token (ZWToken) remains fully compatible with the underlying token’s transfer interface, while extending it to support privacy-preserving operations.

When a ZWToken is transferred to a provable burn address, those tokens MUST be eligible for reminting through the remint interface, effectively breaking the traceability of the fund flow.</li>
A provable burn address MAY take various forms (e.g., as defined in EIP-7503). Its essential properties are:

Such addresses MUST NOT be operable by any user and MUST be provably non-correspondent to any externally owned account (EOA) or smart contract.</li>
Only the entity that generates the burn address MAY derive it, for example, through a signature-derived or deterministic generation scheme.</li>
</ul>
</li>
</ul>
</li>
Commitment Update:

For commitment schemes maintained at the contract level:

If the recipient is identified as a provable burn address, the contract MUST update the commitment.

Example — a recipient that has previously sent any ZWToken MUST NOT be a provable burn address, since such addresses are incapable of initiating outgoing transfers. In this case, commitment update is not required.</li>
</ul>
</li>
</ul>
</li>
For protocol-level commitment schemes (e.g., Ethereum’s native MPT tree), the contract does not need to manage any commitment state, since the protocol layer already provides verifiable commitment structures.</li>
</ul>
</li>
</ul>
Remint</h3>
///</span> @notice</span> Encapsulates all data required for remint operations</span></span>
///</span> @param</span> commitment</span> The commitment (Merkle root) corresponding to the provided proof</span></span>
///</span> @param</span> nullifiers</span> Array of unique nullifiers used to prevent double-remint</span></span>
///</span> @param</span> proverData</span> Generic data for the prover. The meaning and encoding are implementation-specific (e.g., a circuit identifier/version).</span></span>
///</span> @param</span> relayerData</span> Generic data for the relayer. The meaning and encoding are implementation-specific (e.g., fee information).</span></span>
///</span> @param</span> redeem</span> If true, withdraws the equivalent underlying token instead of reminting ZWToken</span></span>
///</span> @param</span> proof</span> Zero-knowledge proof bytes verifying ownership of the provable burn address</span></span>
struct</span> RemintData</span> {</span></span>
    bytes32</span> commitment</span>;</span></span>
    bytes32</span>[</span>]</span> nullifiers</span>;</span></span>
    bytes</span> proverData</span>;</span></span>
    bytes</span> relayerData</span>;</span></span>
    bool</span> redeem</span>;</span></span>
    bytes</span> proof</span>;</span></span>
}</span></span>
</span>
///</span> @notice</span> Remint ZWToken using a zero-knowledge proof to unlink the source of funds</span></span>
///</span> @param</span> to</span> Recipient address that will receive the reminted ZWToken or the underlying token</span></span>
///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span>
///</span> @param</span> amount</span> Amount of ZWToken burned from the provable burn address for reminting</span></span>
///</span> @param</span> data</span> Encapsulated remint data including commitment, nullifiers, redeem flag, proof, and relayer information</span></span>
function</span> remint</span>(</span></span>
    address</span> to</span>,</span></span>
    uint256</span> id</span>,</span></span>
    uint256</span> amount</span>,</span></span>
    RemintData</span> calldata</span> data</span></span>
)</span> external</span>;</span></span></code></pre>


The function MUST verify the zero-knowledge proof proof against the provided commitment to ensure:</p>

Ownership of the provable burn address.</li>
Correctness parameters of remint</code>, i.e., the zk proof public inputs.  address</span> to</span>,</span></span>
  uint256</span> id</span>,</span></span>
  uint256</span> amount</span>,</span></span>
  RemintData </span>calldata</span> data </span>//</span> All fields except data.proof are used as public inputs for zk proof verification</span></span></code></pre></li>
</ul>
</li>

Reminter SHOULD be msg.sender</code>.</p>
</li>

The function MUST validate the input data.commitment</code> to ensure it exists.</p>
</li>

The function MUST ensure that none of the data.nullifiers</code> have been used previously. Reuse of any nullifier MUST revert the transaction.</p>

This supports batch reminting in a single proof by allowing multiple nullifiers to be provided and consumed atomically.</li>
</ul>
</li>

Upon successful verification:</p>

If data.redeem</code> is false, the function MUST mint ZWToken to the recipient to</code>. The amount minted MAY be reduced by fees as defined by the implementation.

In this case, the function MUST emit the Reminted</code> event after a successful remint of ZWToken.</li>
</ul>
</li>
If data.redeem</code> is true, the function MUST transfer underlying token to the recipient to</code>. The amount transferred MAY be reduced by fees as defined by the implementation.

In this case, the function MUST emit the Reminted</code> event after a successful withdrawal of the underlying token.</li>
</ul>
</li>
The net tokens received by the recipient to</code> MAY be reduced by relayer fees if the relayer charges a fee (as specified in data.relayerData</code>).</li>
The function MUST mark each</strong> nullifier in data.nullifiers</code> as spent to prevent double-spending.</li>
</ul>
</li>

The function MUST emit a Reminted(reminter, to, id, amount, data.redeem)</code> event upon successful remint.</p>

The amount</code> parameter in the Reminted</code> event represents the net amount of underlying tokens or ZWToken received by to</code> after all applicable fees have been deducted.</li>
</ul>
</li>
</ul>
Preview Functions (Optional)</h3>
Since the actual token amounts received may differ from the input amounts due to implementation-specific factors (e.g., fees), users need a standardized way to determine the exact amounts they will receive. Following the design pattern established by ERC-4626</a>, the preview functions allow users to simulate the effects of their operations at the current block, returning values as close to and no more than the exact amounts that would result from the corresponding mutable operations if called in the same transaction.</p>
///</span> @notice</span> OPTIONAL: Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block.</span></span>
///</span> @dev</span> MUST return as close to and no more than the exact amount of ZWToken that would be minted in a `deposit` call in the same transaction.</span></span>
///</span> @param</span> to</span> The address that will receive the minted ZWTokens.</span></span>
///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span>
///</span> @param</span> amount</span> The amount of underlying tokens to deposit.</span></span>
///</span> @param</span> data</span> Additional data for extensibility, such as fee information.</span></span>
///</span> @return</span> The</span> amount of ZWToken that would be minted to the recipient after deducting applicable fees.</span></span>
function</span> previewDeposit</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span></code></pre>

previewDeposit(address to, uint256 id, uint256 amount, bytes calldata data)</code>: OPTIONAL. Returns the exact amount of ZWToken that would be minted for the specified amount of underlying tokens.

MUST be inclusive of deposit fees. Integrators SHOULD be aware of the existence of deposit fees.</li>
MUST NOT revert due to implementation-specific user/global limits.</li>
MAY revert due to other conditions that would also cause deposit</code> to revert.</li>
</ul>
</li>
</ul>
///</span> @notice</span> OPTIONAL: Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block.</span></span>
///</span> @dev</span> MUST return as close to and no more than the exact amount of underlying tokens that would be received in a `withdraw` call in the same transaction.</span></span>
///</span> @param</span> to</span> The recipient address that will receive the underlying token.</span></span>
///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span>
///</span> @param</span> amount</span> The amount of ZWToken to burn.</span></span>
///</span> @param</span> data</span> Additional data for extensibility, such as fee information.</span></span>
///</span> @return</span> The</span> amount of underlying tokens that would be received by the recipient after deducting applicable fees.</span></span>
function</span> previewWithdraw</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span></code></pre>

previewWithdraw(address to, uint256 id, uint256 amount, bytes calldata data)</code>: OPTIONAL. Returns the exact amount of underlying tokens that would be received for burning the specified amount of ZWToken.

MUST be inclusive of withdrawal fees. Integrators SHOULD be aware of the existence of withdrawal fees.</li>
MUST NOT revert due to implementation-specific user/global limits.</li>
MAY revert due to other conditions that would also cause withdraw</code> to revert.</li>
</ul>
</li>
</ul>
///</span> @notice</span> OPTIONAL: Allows an on-chain or off-chain user to simulate the effects of their remint at the current block.</span></span>
///</span> @dev</span> MUST return as close to and no more than the exact amount of ZWToken or underlying tokens that would be received in a `remint` call in the same transaction.</span></span>
///</span> @param</span> to</span> Recipient address that will receive the reminted ZWToken or the underlying token.</span></span>
///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span>
///</span> @param</span> amount</span> The amount of ZWToken burned from the provable burn address for reminting.</span></span>
///</span> @param</span> data</span> Encapsulated remint data including commitment, nullifiers, redeem flag, proof, and relayer information.</span></span>
///</span> @return</span> The</span> amount of ZWToken or underlying tokens that would be received by the recipient after all applicable fees have been deducted.</span></span>
function</span> previewRemint</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> RemintData</span> calldata</span> data</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span></code></pre>

previewRemint(address to, uint256 id, uint256 amount, RemintData calldata data)</code>: OPTIONAL. Returns the exact amount of ZWToken (or underlying tokens if data.redeem</code> is true) that would be received for a remint operation.

MUST be inclusive of all applicable fees, including remint fees and relayer fees (as specified in data.relayerData</code>).</li>
MUST NOT revert due to implementation-specific user/global limits.</li>
MAY revert due to other conditions that would also cause remint</code> to revert.</li>
</ul>
</li>
</ul>
Query Interfaces</h3>
///</span> @notice</span> Returns the current top-level commitment representing the privacy state</span></span>
///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span>
///</span> @return</span> The</span> latest root hash of the commitment tree</span></span>
function</span> getLatestCommitment</span>(</span>uint256</span> id</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span>
</span>
///</span> @notice</span> Checks if a specific top-level commitment exists</span></span>
///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span>
///</span> @param</span> commitment</span> The root hash to verify</span></span>
///</span> @return</span> True</span> if the commitment exists, false otherwise</span></span>
function</span> hasCommitment</span>(</span>uint256</span> id</span>,</span> bytes32</span> commitment</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
</span>
///</span> @notice</span> OPTIONAL: Returns the total number of commitment leaves stored</span></span>
///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span>
///</span> @return</span> The</span> total count of commitment leaves</span></span>
function</span> getCommitLeafCount</span>(</span>uint256</span> id</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
</span>
///</span> @notice</span> OPTIONAL: Retrieves leaf-level commit data and their hashes</span></span>
///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span>
///</span> @param</span> startIndex</span> Index of the first leaf to fetch</span></span>
///</span> @param</span> length</span> Number of leaves to fetch</span></span>
///</span> @return</span> commitHashes</span> Hashes of the leaf data</span></span>
///</span> @return</span> recipients</span> Recipient addresses of each leaf</span></span>
///</span> @return</span> amounts</span> Token amounts of each leaf</span></span>
function</span> getCommitLeaves</span>(</span>uint256</span> id</span>,</span> uint256</span> startIndex</span>,</span> uint256</span> length</span>)</span></span>
    external</span> view</span> returns</span> (</span>bytes32</span>[</span>]</span> memory</span> commitHashes</span>,</span> address</span>[</span>]</span> memory</span> recipients</span>,</span> uint256</span>[</span>]</span> memory</span> amounts</span>)</span>;</span></span>
</span>
///</span> @notice</span> Returns the address of the underlying token wrapped by this ZWToken</span></span>
///</span> @return</span> The</span> underlying token contract address, or address(0) if the underlying asset is ETH.</span></span>
function</span> getUnderlying</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span></code></pre>


getLatestCommitment(uint256 id)</code>: MUST return the most recent top-level commitment associated with the specified token identifier, representing the current state of the ZWToken system.</p>

For protocol-level commitments, the block number can be used as the commitment, as it can directly map to the block hash.</li>
</ul>
</li>

hasCommitment(uint256 id, bytes32 commitment)</code>: MUST check whether a specific top-level commitment associated with the specified token identifier exists in the contract.</p>

For proving ownership of a provable burn address, it does not require the latest commitment.</li>
For protocol-level commitments, the block number can be used as the commitment, as it can directly map to the block hash.</li>
</ul>
</li>

getCommitLeafCount(uint256 id)</code>: OPTIONAL. Returns the total number of leaf-level commitments, which helps getCommitLeaves</code> retrieve the leaves. The returned value also represents the current size of the privacy pool.</p>
</li>

getCommitLeaves(uint256 id, uint256 startIndex, uint256 length)</code>: OPTIONAL. Retrieves leaf-level commitment data from the commitment tree associated with the specified token identifier.</p>

On-chain storage of commit data can be used to improve privacy and decentralization but will incur higher gas costs.</li>
Event-based reconstruction can be used as an alternative, though it introduces potential centralization risks.</li>
</ul>
</li>

getUnderlying()</code>: MUST return the address of the underlying token that this ZWToken wraps.</p>

If the underlying asset is ETH, MUST return address(0)</code>.</li>
</ul>
</li>
</ul>
ERC-165</a> Support</h3>

Implementations of this ERC MUST implement ERC-165 interface detection.</li>
supportsInterface(bytes4)</code> MUST return true</code> for type(IERC8065).interfaceId</code> (in addition to any other supported interfaces), allowing other contracts to reliably detect whether a token is a ZWToken wrapper.</li>
</ul>
Events</h3>
//</span> Optional: Emitted when a contract-maintained commitment is updated</span></span>
///</span> @notice</span> OPTIONAL event emitted when a commitment is updated in the contract</span></span>
///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span>
///</span> @param</span> commitment</span> The new top-level commitment hash</span></span>
///</span> @param</span> to</span> The recipient address associated with the commitment</span></span>
///</span> @param</span> amount</span> The amount related to this commitment update</span></span>
event</span> CommitmentUpdated</span>(</span>uint256</span> indexed</span> id</span>, </span>bytes32</span> indexed</span> commitment</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> amount</span>)</span>;</span></span>
</span>
///</span> @notice</span> Emitted when underlying tokens are deposited and ZWToken is minted to the recipient</span></span>
///</span> @param</span> from</span> The address sending the underlying tokens</span></span>
///</span> @param</span> to</span> The address receiving the minted ZWToken (after fees)</span></span>
///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span>
///</span> @param</span> amount</span> The net amount of ZWToken minted to `to` after deducting applicable fees</span></span>
event</span> Deposited</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>)</span>;</span></span>
</span>
///</span> @notice</span> Emitted when ZWToken is burned to redeem underlying tokens to the recipient</span></span>
///</span> @param</span> from</span> The address burning the ZWToken</span></span>
///</span> @param</span> to</span> The address receiving the redeemed underlying tokens (after fees)</span></span>
///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span>
///</span> @param</span> amount</span> The net amount of underlying tokens received by `to` after deducting applicable fees</span></span>
event</span> Withdrawn</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>)</span>;</span></span>
</span>
///</span> @notice</span> Emitted upon successful reminting of ZWToken or withdrawal of underlying tokens via a zero-knowledge proof</span></span>
///</span> @param</span> from</span> The address initiating the remint operation</span></span>
///</span> @param</span> to</span> The address receiving the reminted ZWToken or withdrawn underlying tokens (after fees)</span></span>
///</span> @param</span> id</span> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span>
///</span> @param</span> amount</span> The net amount of ZWToken or underlying tokens received by `to` after all applicable fees have been deducted</span></span>
///</span> @param</span> redeem</span> If true, withdraws the equivalent underlying tokens instead of reminting ZWToken</span></span>
event</span> Reminted</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>, </span>bool</span> redeem</span>)</span>;</span></span></code></pre>


CommitmentUpdated(uint256 indexed id, bytes32 indexed commitment, address indexed to, uint256 amount)</code> is OPTIONAL and may be emitted when a contract-maintained commitment is updated, such as when ZWToken is sent to a potential provable burn address. It allows users to reconstruct commitments and generate zero-knowledge proofs, where id</code> is the token identifier, commitment</code> is the new commitment, to</code> is the recipient, and amount</code> is the committed token amount.</p>
</li>

Deposited(address indexed from, address indexed to, uint256 indexed id, uint256 amount)</code> signals that underlying tokens have been deposited and ZWToken minted to the recipient, where from</code> is the sender, to</code> is the recipient, id</code> is the token identifier and amount</code> is the net amount of ZWToken minted to to</code> after deducting applicable fees.</p>
</li>

Withdrawn(address indexed from, address indexed to, uint256 indexed id, uint256 amount)</code> signals that ZWToken has been burned to redeem underlying tokens to the recipient, where from</code> is the burner, to</code> is the receiver, id</code> is the token identifier and amount</code> is the net amount of underlying tokens received by to</code> after deducting applicable fees.</p>
</li>

Reminted(address indexed from, address indexed to, uint256 indexed id, uint256 amount, bool redeem)</code> MUST be emitted upon successful reminting of ZWToken or withdrawal of underlying tokens via a zero-knowledge proof, where from</code> is the reminter, to</code> is the recipient, id</code> is the token identifier and amount</code> is the net amount of ZWToken or underlying tokens received by to</code> after all applicable fees have been deducted.</p>
</li>
</ul>
Rationale</h2>


Permissionless Wrapping: Launching a new zk-native token is unlikely to achieve sufficient liquidity or adoption, and major token issuers are unlikely to deploy zk variants due to regulatory and operational constraints. A permissionless wrapper makes privacy a native feature for existing tokens. ZWToken does not require issuer consent—any existing token can be wrapped, ensuring openness and equal accessibility regardless of issuer policies.</p>
</li>

Composable Privacy: Wrapped tokens remain fully compatible with their underlying token standards, preserving interoperability across the Ethereum ecosystem. Users and dApps can treat ZWToken as the underlying token when privacy is not required, making privacy an optional and composable extension rather than a separate system.</p>
</li>

Awareness of ZWToken: This ERC supports both ZWToken-aware and ZWToken-unaware workflows, each with distinct advantages. In the ZWToken-aware workflow, ZWToken inherits all functional properties of the underlying token and can interact seamlessly with existing DeFi protocols. In the ZWToken-unaware workflow, ZWToken operates transparently beneath the user interface, reducing the number of required contract interactions and improving user experience for those who prefer not to hold ZWToken directly.</p>
</li>

Multiple Token Standard Support: This ERC only depends on the transferability of the underlying token, enabling broad compatibility with token standards such as ERC-20, ERC-721, ERC-1155, and ERC-6909. Non-transferable tokens (e.g., Soulbound Tokens, SBTs) are out of scope. Implementations may require extra care for:</p>

Fee-on-transfer tokens.</li>
Rebasing tokens (consider wrapping an existing non-rebasing wrapper to avoid rebase-handling complexity).</li>
</ul>
</li>

Fee Mechanisms: Fee structures are implementation-specific and not defined by this ERC. Implementations MAY apply fees during deposit, remint, or withdraw phases, and MAY support various fee models (e.g., fixed fees, percentage-based fees, or no fees).</p>
</li>

Relayer-Enabled Remint: This ERC supports relayer functionality, allowing third parties to submit remint transactions on behalf of users while receiving a fee. This design mitigates privacy leakage caused by revealing the original sender's address when paying gas fees.</p>
</li>

Data Extensibility:</p>

The meaning and encoding of proverData</code> and relayerData</code> are implementation-specific.</li>
Implementations MAY encode prover-specific metadata in data.proverData</code> (e.g., a circuit identifier/version, a proving key identifier, or packed auxiliary public inputs).</li>
Implementations MAY encode relayer-specific metadata in data.relayerData</code> (e.g., fee information, a fee token, or other fee model parameters).</li>
A single universal encoding is impractical because proving schemes and relayer compensation models can vary significantly.</li>
If cross-implementation interoperability is desired, a separate ERC (or profile) SHOULD standardize encoding(s) for proverData</code> and/or relayerData</code>.</li>
</ul>
</li>

Commitment Generalization: The ERC adopts a generic commitment abstraction, supporting various schemes such as Merkle trees or other verifiable cryptographic accumulators. This flexibility enables developers to adapt the standard to different privacy or scalability trade-offs.</p>
</li>

Proof System Generalization: Proofs are passed as bytes calldata, allowing the use of SNARKs, STARKs, or any other zero-knowledge proof system, ensuring future-proof interoperability across cryptographic frameworks.</p>
</li>

Provable Burn Address Generalization: This ERC does not prescribe a specific method for generating Provable Burn Addresses, as long as the following conditions are met. One example is adopting zk-friendly hash functions such as Poseidon to replace keccak256 in the address generation algorithm.</p>

Such addresses MUST NOT be operable by any user and MUST be provably non-correspondent to any externally owned account (EOA) or smart contract.</li>
Only the entity that generates the burn address MAY derive it, for example through a signature-derived or deterministic generation scheme.</li>
</ul>
</li>

Dual Commitment Options: The ERC supports both contract-maintained commitments and protocol-level commitments (using blockhash as the commitment).</p>

Contract-maintained commitments reduce proof complexity, allowing smaller ZK circuits and enabling proof generation directly in browsers or mobile devices, at the cost of higher gas consumption during transfers.</li>
Using blockhash as the commitment eliminates on-chain maintenance overhead but increases the complexity of off-chain proof generation.</li>
</ul>
</li>

Preview Functions: Following the design pattern established by ERC-4626</a>, this ERC includes optional preview functions (previewDeposit</code>, previewWithdraw</code>, previewRemint</code>) that simulate the exact outcomes of their corresponding mutable operations.</p>

Since the actual token amounts received may differ from the input amounts due to implementation-specific factors (e.g., fees), users and integrators need a standardized way to determine the exact amounts.</li>
These functions provide a standardized interface for querying the net token amounts, enabling accurate UX displays and informed decision-making before executing transactions.</li>
Each preview function mirrors the parameters of its corresponding mutable operation to ensure accurate calculations that may depend on any of these parameters.</li>
</ul>
</li>
</ul>
Backwards Compatibility</h2>
This ERC introduces no breaking changes. It extends the functionality of the underlying token without modifying or overriding its base interfaces.</p>
Reference Implementation</h2>
//</span> SPDX-License-Identifier: MIT</span></span>
pragma</span> solidity</span> ^0.8.20</span>;</span></span>
</span>
import</span> {</span>ERC20</span>}</span> from</span> "@openzeppelin/contracts/token/ERC20/ERC20.sol"</span>;</span></span>
import</span> {</span>IERC20</span>}</span> from</span> "@openzeppelin/contracts/token/ERC20/IERC20.sol"</span>;</span></span>
import</span> {</span>SafeERC20</span>}</span> from</span> "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol"</span>;</span></span>
import</span> {</span>ERC165</span>}</span> from</span> "@openzeppelin/contracts/utils/introspection/ERC165.sol"</span>;</span></span>
import</span> {</span>IERC165</span>}</span> from</span> "@openzeppelin/contracts/utils/introspection/IERC165.sol"</span>;</span></span>
</span>
interface</span> IVerifier</span> {</span></span>
    function</span> verifyProof</span>(</span></span>
        bytes</span> calldata</span> proof</span>,</span></span>
        uint256</span>[</span>]</span> calldata</span> input</span></span>
    )</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
}</span></span>
</span>
contract</span> ZWToken</span> is</span> IERC8065</span>, </span>ERC20</span>, </span>ERC165</span> {</span></span>
    using</span> SafeERC20</span> for</span> IERC20</span>;</span></span>
</span>
    IERC20 </span>public</span> immutable</span> underlying</span>;</span></span>
    IVerifier </span>public</span> immutable</span> verifier</span>;</span></span>
</span>
    mapping</span>(</span>bytes32</span> =></span> bool</span>)</span> public</span> usedNullifier</span>;</span></span>
</span>
    event</span> Deposited</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>)</span>;</span></span>
    event</span> Withdrawn</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>)</span>;</span></span>
    event</span> Reminted</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> id</span>, </span>uint256</span> amount</span>, </span>bool</span> redeem</span>)</span>;</span></span>
</span>
    constructor</span>(</span></span>
        string</span> memory</span> name_</span>,</span></span>
        string</span> memory</span> symbol_</span>,</span></span>
        address</span> underlying_</span>,</span></span>
        address</span> verifier_</span></span>
    )</span> ERC20</span>(</span>name_, symbol_) </span>{</span></span>
        require</span>(</span>underlying_ </span>!=</span> address</span>(</span>0</span>)</span>,</span> "Invalid underlying"</span>)</span>;</span></span>
        require</span>(</span>verifier_ </span>!=</span> address</span>(</span>0</span>)</span>,</span> "Invalid verifier"</span>)</span>;</span></span>
        underlying </span>=</span> IERC20</span>(</span>underlying_</span>)</span>;</span></span>
        verifier </span>=</span> IVerifier</span>(</span>verifier_</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> deposit</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> /*</span>data</span>*/</span>)</span> external</span> payable</span> override</span> {</span></span>
        require</span>(</span>amount </span>></span> 0</span>,</span> "amount must > 0"</span>)</span>;</span></span>
        require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span>
        underlying</span>.</span>safeTransferFrom</span>(</span>msg.sender</span>,</span> address</span>(</span>this</span>)</span>,</span> amount</span>)</span>;</span></span>
        _mint</span>(</span>to</span>,</span> amount</span>)</span>;</span></span>
        emit</span> Deposited</span>(</span>msg.sender</span>,</span> to</span>,</span> id</span>,</span> amount</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> withdraw</span>(</span>address</span> to</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> /*</span>data</span>*/</span>)</span> external</span> override</span> {</span></span>
        require</span>(</span>amount </span>></span> 0</span>,</span> "amount must > 0"</span>)</span>;</span></span>
        require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span>
        _burn</span>(</span>msg.sender</span>,</span> amount</span>)</span>;</span></span>
        underlying</span>.</span>safeTransfer</span>(</span>to</span>,</span> amount</span>)</span>;</span></span>
        emit</span> Withdrawn</span>(</span>msg.sender</span>,</span> to</span>,</span> id</span>,</span> amount</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> remint</span>(</span></span>
        address</span> to</span>,</span></span>
        uint256</span> id</span>,</span></span>
        uint256</span> amount</span>,</span></span>
        IERC8065</span>.</span>RemintData</span> calldata</span> data</span></span>
    )</span> external</span> override</span> {</span></span>
        require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span>
        //</span> NOTE</span>: This reference implementation uses a verifier circuit that consumes a single nullifier as a public input.</span></span>
        //</span> The ERC-8065 specification allows `data.nullifiers` to contain multiple nullifiers so implementations can</span></span>
        //</span> support batch reminting (consuming multiple nullifiers atomically within one proof).</span></span>
        require</span>(</span>data</span>.</span>nullifiers</span>.</span>length </span>==</span> 1</span>,</span> "Only single nullifier supported"</span>)</span>;</span></span>
        bytes32</span> nullifier </span>=</span> data</span>.</span>nullifiers</span>[</span>0</span>]</span>;</span></span>
        require</span>(</span>!</span>usedNullifier</span>[</span>nullifier</span>]</span>,</span> "nullifier used"</span>)</span>;</span></span>
</span>
        bytes32</span> headerHash </span>=</span> blockhash</span>(</span>uint256</span>(</span>data</span>.</span>commitment</span>)</span>)</span>;</span></span>
        require</span>(</span>headerHash </span>!=</span> bytes32</span>(</span>0</span>)</span>,</span> "commitment not found"</span>)</span>;</span></span>
</span>
        //</span> Example encoding (implementation-specific):</span></span>
        //</span> if relayerData.length >= 32, first 32 bytes are interpreted as relayerFee (uint256)</span></span>
        uint256</span> relayerFee </span>=</span> 0</span>;</span></span>
        if</span> (</span>data</span>.</span>relayerData</span>.</span>length </span>></span>=</span> 32</span>)</span> {</span></span>
            assembly</span> {</span></span>
                relayerFee </span>:=</span> calldataload</span>(</span>data</span>.</span>relayerData</span>.</span>offset</span>)</span></span>
            }</span></span>
        }</span></span>
</span>
        //</span> Replay protection by chain id and contract address is handled externally––</span></span>
        //</span> they MUST be included as parameters when generating the provable burn address and proof.</span></span>
        //</span> (For example, the Poseidon hash that defines the burn address should incorporate these values.)</span></span>
        //</span> No contract-side enforcement is implemented here.</span></span>
        uint256</span>[</span>]</span> memory</span> input </span>=</span> new</span> uint256</span>[](</span>7</span>)</span>;</span></span>
        input</span>[</span>0</span>]</span> =</span> uint256</span>(</span>headerHash</span>)</span>;</span></span>
        input</span>[</span>1</span>]</span> =</span> uint256</span>(</span>nullifier</span>)</span>;</span></span>
        input</span>[</span>2</span>]</span> =</span> uint256</span>(</span>uint160</span>(</span>to</span>)</span>)</span>;</span></span>
        input</span>[</span>3</span>]</span> =</span> uint256</span>(</span>id</span>)</span>;</span></span>
        input</span>[</span>4</span>]</span> =</span> uint256</span>(</span>amount</span>)</span>;</span></span>
        input</span>[</span>5</span>]</span> =</span> uint256</span>(</span>data</span>.</span>redeem </span>?</span> 1</span> :</span> 0</span>)</span>;</span></span>
        input</span>[</span>6</span>]</span> =</span> uint256</span>(</span>relayerFee</span>)</span>;</span></span>
</span>
        require</span>(</span>verifier</span>.</span>verifyProof</span>(</span>data</span>.</span>proof</span>,</span> input</span>)</span>,</span> "bad proof"</span>)</span>;</span></span>
</span>
        usedNullifier</span>[</span>nullifier</span>]</span> =</span> true</span>;</span></span>
</span>
        //</span> Fee handling is implementation-specific</span></span>
        //</span> This example implementation applies only relayer fees (parsed from relayerData above)</span></span>
        //</span> In this example, relayerFee is interpreted as a percentage with denominator 10000</span></span>
        uint256</span> remain </span>=</span> amount</span>;</span></span>
        if</span> (</span>relayerFee </span>></span> 0</span>)</span> {</span></span>
            uint256</span> feeDenominator </span>=</span> 10000</span>;</span></span>
            require</span>(</span>relayerFee </span><</span> feeDenominator</span>,</span> "invalid relayer fee"</span>)</span>;</span></span>
            remain </span>=</span> amount </span>-</span> amount </span>*</span> relayerFee </span>/</span> feeDenominator</span>;</span></span>
            require</span>(</span>remain </span>></span> 0</span>,</span> "invalid remain"</span>)</span>;</span></span>
        }</span></span>
</span>
        if</span> (</span>data</span>.</span>redeem</span>)</span> {</span></span>
            underlying</span>.</span>safeTransfer</span>(</span>to</span>,</span> remain</span>)</span>;</span></span>
            if</span> (</span>relayerFee </span>></span> 0</span>)</span> {</span></span>
                underlying</span>.</span>safeTransfer</span>(</span>msg.sender</span>,</span> amount </span>-</span> remain</span>)</span>;</span></span>
            }</span></span>
        }</span> else</span> {</span></span>
            _mint</span>(</span>to</span>,</span> remain</span>)</span>;</span></span>
            if</span> (</span>relayerFee </span>></span> 0</span>)</span> {</span></span>
                _mint</span>(</span>msg.sender</span>,</span> amount </span>-</span> remain</span>)</span>;</span></span>
            }</span></span>
        }</span></span>
        emit</span> Reminted</span>(</span>msg.sender</span>,</span> to</span>,</span> id</span>,</span> remain</span>,</span> data</span>.</span>redeem</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> getLatestCommitment</span>(</span>uint256</span> id</span>)</span> external</span> view</span> override</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
        require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span>
        return</span> bytes32</span>(</span>block</span>.</span>number</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> hasCommitment</span>(</span>uint256</span> id</span>,</span> bytes32</span> commitment</span>)</span> external</span> view</span> override</span> returns</span> (</span>bool</span>)</span> {</span></span>
        require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span>
        bytes32</span> headerHash </span>=</span> blockhash</span>(</span>uint256</span>(</span>commitment</span>)</span>)</span>;</span></span>
        return</span> headerHash </span>!=</span> bytes32</span>(</span>0</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> getUnderlying</span>(</span>)</span> external</span> view</span> override</span> returns</span> (</span>address</span>)</span> {</span></span>
        return</span> address</span>(</span>underlying</span>)</span>;</span></span>
    }</span></span>
</span>
    //</span> Optional preview functions</span></span>
    function</span> previewDeposit</span>(</span>address</span> /*</span>to</span>*/</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> /*</span>data</span>*/</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span> {</span></span>
        require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span>
        //</span> This example implementation has no deposit fees, so the output equals the input.</span></span>
        //</span> Implementations with fees SHOULD deduct them here.</span></span>
        return</span> amount</span>;</span></span>
    }</span></span>
</span>
    function</span> previewWithdraw</span>(</span>address</span> /*</span>to</span>*/</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> /*</span>data</span>*/</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span> {</span></span>
        require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span>
        //</span> This example implementation has no withdrawal fees, so the output equals the input.</span></span>
        //</span> Implementations with fees SHOULD deduct them here.</span></span>
        return</span> amount</span>;</span></span>
    }</span></span>
</span>
    function</span> previewRemint</span>(</span>address</span> /*</span>to</span>*/</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>,</span> IERC8065</span>.</span>RemintData</span> calldata</span> data</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span> {</span></span>
        require</span>(</span>id </span>==</span> 0</span>,</span> "id must be 0 for ERC20"</span>)</span>;</span></span>
        //</span> Example encoding (implementation-specific):</span></span>
        //</span> Parse relayerFee from relayerData (if provided)</span></span>
        uint256</span> relayerFee </span>=</span> 0</span>;</span></span>
        if</span> (</span>data</span>.</span>relayerData</span>.</span>length </span>></span>=</span> 32</span>)</span> {</span></span>
            relayerFee </span>=</span> abi</span>.</span>decode</span>(</span>data</span>.</span>relayerData</span>[</span>:</span>32</span>]</span>,</span> (</span>uint256</span>)</span>)</span>;</span></span>
        }</span></span>
        //</span> Apply relayer fee (percentage with denominator 10000)</span></span>
        uint256</span> remain </span>=</span> amount</span>;</span></span>
        if</span> (</span>relayerFee </span>></span> 0</span>)</span> {</span></span>
            uint256</span> feeDenominator </span>=</span> 10000</span>;</span></span>
            require</span>(</span>relayerFee </span><</span> feeDenominator</span>,</span> "invalid relayer fee"</span>)</span>;</span></span>
            remain </span>=</span> amount </span>-</span> amount </span>*</span> relayerFee </span>/</span> feeDenominator</span>;</span></span>
        }</span></span>
        return</span> remain</span>;</span></span>
    }</span></span>
</span>
    function</span> supportsInterface</span>(</span>bytes4</span> interfaceId</span>)</span></span>
        public</span></span>
        view</span></span>
        virtual</span></span>
        override</span>(</span>ERC165</span>,</span> IERC165</span>)</span></span>
        returns</span> (</span>bool</span>)</span></span>
    {</span></span>
        return</span> interfaceId </span>==</span> type</span>(</span>IERC8065</span>)</span>.</span>interfaceId </span>||</span> super</span>.</span>supportsInterface</span>(</span>interfaceId</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Security Considerations</h2>


Double-Remint Prevention: Each remint operation MUST include one or more unique nullifiers (data.nullifiers</code>) to prevent double-remint attacks.</p>

Reusing any nullifier MUST revert.</li>
On success, all provided nullifiers MUST be marked as spent.</li>
</ul>
</li>

Over-Minting Protection: The total supply of ZWToken MAY temporarily exceed the supply of the underlying token. However, the surplus represents provably burnt tokens, which are permanently removed from circulation and cannot be redeemed.</p>
</li>

Local Proof Generation: Circuits SHOULD remain as small and efficient as possible to enable users to generate zero-knowledge proofs locally (e.g., within browsers or mobile devices). This minimizes reliance on third-party provers that may introduce privacy leakage risks.</p>
</li>

Provable Burn Address Security: Provable burn addresses MAY follow different generation schemes (e.g., as proposed in EIP-7503). The essential properties are:</p>

These addresses MUST be non-operable and provably non-correspondent to any externally owned account (EOA) or smart contract.</li>
Only the generator of the burn address MAY deterministically derive it, for instance, through a signature-derived scheme.</li>
Implementations SHOULD prefer zk-friendly hash functions (e.g., Poseidon) in place of keccak256 to improve proof efficiency and reduce circuit size.</li>
</ul>
</li>

Burn and Remint Process Privacy:</p>

Burn amounts SHOULD appear indistinguishable from ordinary transfers to prevent correlation with remint amounts.</li>
Burn and remint events SHOULD be separated in time to reduce linkability.</li>
Each burn operation MUST use a unique Provable Burn Address that can be used only once.</li>
</ul>
</li>

Fully On-Chain Operation: The protocol operates entirely on-chain and requires no trusted backend. It can be directly integrated into wallets or dApps without introducing custodial or centralized dependencies.</p>
</li>

Commit Data Privacy: When generating proofs, users SHOULD retrieve as much commitment data as possible to maximize anonymity. Relying on selective or limited data sources may allow inference of the specific commit path being proven, weakening privacy guarantees.</p>
</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Diamond Storage
2025-10-11T00:00:00+00:00
Abstract</h2>
This standard formalizes the diamond storage pattern originally introduced by ERC-2535 Diamonds</a> and widely adopted across smart contracts.</p>
Though originally created for proxy contracts, diamond storage can be used to organize storage and data access within any</em> smart contract.</p>
Diamond storage defines the location of structs in contract storage using the keccak256</code> hash of human-readable identifiers.</p>
ERC-8042</a> standardizes this simple and production-proven approach, offering a lightweight alternative to ERC-7201</a> for new and existing projects.</p>
Motivation</h2>
On March 10, 2020, a change to the Solidity compiler introduced the ability to assign structs to any storage location. This enabled a new pattern for using separate areas of storage. The pattern became known as diamond storage, as it was first popularized by ERC-2535 Diamonds and has since been widely used.</p>
Later, on June 20, 2023, ERC-7201 was introduced to standardize this general storage pattern. However, the formula that ERC-7201 proposed for generating storage locations differed from the one already established and in active use by diamond storage.</p>
ERC-8042 standardizes diamond storage for new projects and validates past diamond storage implementations.</p>
While ERC-7201 defines a generalized mechanism for storage namespaces, ERC-8042 preserves the simplicity and backward compatibility of the diamond storage convention already deployed in production across many projects.</p>
Developers may prefer diamond storage for its simplicity, restricted ASCII identifiers, and direct hash-based computation of storage locations.</p>
This standard can be used by tools to find and access data within smart contract storage.</p>
Specification</h2>
Diamond storage defines where structs are located in contract storage.</p>
A diamond storage identifier is defined as a string containing only printable ASCII characters. That is characters 0x20</code> through 0x7E</code> inclusive.</p>
The location of a diamond storage struct is determined by the keccak256</code> hash of a diamond storage identifier.</p>
Recommendations</h3>

Use Solidity's string literals</h4>
A string literal is an ASCII string type that is literally written between quotes, for example: "this is a string literal"</code>.</p>
It is recommended to use Solidity's string literals to create diamond storage identifiers because the Solidity compiler enforces that they only contain printable ASCII characters, characters 0x20</code> through 0x7E</code> inclusive. Hex (\xNN</code>) and Unicode (\uNNNN</code>) escape sequences should NOT</strong> be used in diamond storage identifiers.</p>
It is recommended to use compile-time constant string literals. Here is an example:</p>
bytes32 constant STORAGE_POSITION = keccak256("myproject.erc721.registry");</code></p>
</li>
Use unique, human-readable, meaningful strings</h4>
A human-readable string is a string that humans can normally read and understand, like "Transaction successful".</p>
A meaningful string in this context is a string that appropriately names or describes a storage space, or uses a pattern to do so. For example, "myproject.erc721.registry"</code> is a hierarchical pattern that specifies ERC-721</a> related storage for a registry. The string "car.fish.piano.run"</code> is not a meaningful string because it is random and does not appropriately name or describe something.</p>
Diamond storage identifiers should be unique, human-readable, meaningful strings.</p>
</li>
Do NOT use Unicode literals</h4>
Unicode literals can contain invisible characters and other non-ASCII characters which violates the specification of this standard.</p>
Here is an example of a Unicode literal in Solidity: string memory a = unicode"Hello 😃";</code>.</p>
Unicode literals should NOT</strong> be used to create diamond storage identifiers.</p>
</li>
Do not use the space 0x20</code> character</h4>
Including the space (0x20</code>) character in diamond storage identifiers is not recommended, as it may interfere with tooling such as the NatSpec tag described next.</p>
</li>
</ol>
ERC-8042 NatSpec tag</h3>
ERC-7201 defines the NatSpec tag @custom:storage-location <FORMULA_ID>:<NAMESPACE_ID></code>, where <FORMULA_ID></code> identifies a formula used to compute the storage location of a struct based on the namespace id.</p>
The formula identified by erc8042</code> is defined as erc8042(id: string literal) = keccak256(id)</code>. In Solidity, this corresponds to the expression keccak256(id)</code>. When using this formula the annotation becomes @custom:storage-location erc8042:<NAMESPACE_ID></code>. For example, @custom:storage-location erc8042:myproject.erc721.registry</code> annotates diamond storage with id "myproject.erc721.registry"</code> rooted at erc8042("myproject.erc721.registry")</code>.</p>
Rationale</h2>
Proxy contracts and contracts that use DELEGATECALL</code> need a reliable and secure way to define, document, and manage separate areas of smart contract storage.</p>
In March 2020, diamond storage established a way to do this and has been in use since then. However, diamond storage wasn't formalized as a standard, which is important to clarify its mechanics, usage and precise specification.</p>
In June 2023, ERC-7201 Namespaced Storage Layout standardized the general pattern but has looser restrictions on namespace ids and a more complicated formula for calculating storage locations. Some people may prefer using ERC-7201, especially if they may auto-generate machine-readable or random strings for their namespace ids.</p>
Some people may prefer ERC-8042 Diamond Storage for its ASCII-enforced, human-readable, meaningful strings and simple calculation of storage locations.</p>
ERC-2535 Diamonds first introduced the pattern of distinct storage areas for smart contracts. ERC-7201 later standardized the idea. ERC-8042 standardizes the original, simpler diamond storage variant for new projects and legacy compatibility.</p>
Though originally created for proxy contracts, diamond storage can be used to organize storage and data access within any</em> smart contract.</p>
Comparing ERC-8042 and ERC-7201</h3>
ERC-7201</h4>
ERC-7201 applies a formula to a namespace id to generate a storage location. Per the ERC-7201 specification a namespace id is a string that should not contain any whitespace characters. A namespace id has no other restrictions. So a namespace id could be something meaningful like mycompany.projectA.erc721</code> or it could be a series of random bytes, characters or words, etc.</p>
ERC-7201 uses the following formula, given in Solidity, to generate a storage location: keccak256(abi.encode(uint256(keccak256(bytes(namespace id))) - 1)) & ~bytes32(uint256(0xff))</code>.</p>


The first part of the ERC-7201 formula keccak256(abi.encode(uint256(keccak256(bytes(namespace id))) - 1))</code> ensures that the input bytes to the second call to keccak256</code> will not match any input bytes used by Solidity's types that also use keccak256</code> to determine storage locations. This makes it possible to use any sequence of bytes for the namespace id.</p>
</li>

The last part of ERC-7201, & ~bytes32(uint256(0xff))</code> ensures that the final storage location is a multiple of 256 which may provide a gas optimization in the future.</p>
</li>
</ol>
ERC-8042</h4>
ERC-8042 identifiers can only contain printable ASCII characters and recommends using Solidity's string literals which enforces this constraint.</p>
ERC-8042 recommends human-readable, meaningful strings for diamond storage identifiers.</p>
ERC-8042 uses the following formula, given in Solidity, to generate a storage location: keccak256(string literal)</code>.</p>
Backwards Compatibility</h2>
Diamond storage as described by this standard has been in use for 5 years. This standard recognizes and standardizes all previous uses of diamond storage that conform to the specification.</p>
Reference Implementation</h2>
This is a simple example of a contract that uses diamond storage:</p>
/**</span></span>
 * </span>@title</span> ERC721Registry</span></span>
 * </span>@notice</span> A registry contract for tracking ERC721 contracts.</span></span>
 *         Allows adding ERC721 contract addresses up to a configurable limit.</span></span>
 * </span>@dev</span> EIP-8042 Diamond Storage is used to organize and manage access to storage.</span></span>
 */</span></span>
contract</span> ERC721Registry</span> {</span></span>
</span>
  ///</span> @notice</span> Reverts when the registry reaches its configured capacity.</span></span>
  error</span> ERC721RegistryFull</span>(</span>)</span>;</span></span>
  </span></span>
  ///</span> @notice</span> Struct storage position defined by keccak256 hash </span></span>
  ///</span>         of diamond storage identifier.</span></span>
  bytes32</span> constant</span> STORAGE_POSITION </span>=</span> keccak256</span>(</span>"myproject.erc721.registry"</span>)</span>;</span></span>
 </span></span>
  ///</span> @notice</span> @notice</span> Storage layout for the ERC721 registry, following EIP-8042.  </span></span>
  ///</span> @dev</span> - `erc721Contracts`: Dynamic array of registered ERC721 contract addresses.</span></span>
  ///</span>      - `registryLimit`: Maximum allowed entries.</span></span>
  ///</span> @custom:storage</span>-location erc8042:myproject.erc721.registry</span></span>
  struct</span> ERC721RegistryStorage</span> {</span></span>
    address</span>[</span>]</span> erc721Contracts</span>;</span></span>
    uint256</span> registryLimit</span>;</span>    </span></span>
  }</span></span>
</span>
  ///</span> @notice</span> Returns a pointer to the ERC721RegistryStorage struct in storage.</span></span>
  ///</span> @dev</span> Uses inline assembly to access the storage slot defined by STORAGE_POSITION.</span></span>
  ///</span> @return</span> s</span> The ERC173Storage struct in storage.</span></span>
  function</span> getStorage</span>(</span>)</span> internal</span> pure</span>  returns</span> (</span>ERC721RegistryStorage</span> storage</span> s</span>)</span> {</span></span>
    bytes32</span> position </span>=</span> STORAGE_POSITION</span>;</span></span>
    assembly</span> {</span></span>
      s</span>.</span>slot </span>:=</span> position</span></span>
    }</span></span>
  }</span></span>
</span>
  ///</span> @notice</span> Sets the maximum number of ERC721 contracts the registry can hold.  </span></span>
  ///</span> @param</span> _newLimit</span> New registry capacity limit.</span></span>
  function</span> setRegistryLimit</span>(</span>uint256</span> _newLimit</span>)</span> internal</span> {</span></span>
    getStorage</span>(</span>)</span>.</span>registryLimit </span>=</span> _newLimit</span>;</span></span>
  }</span></span>
</span>
  ///</span> @notice</span> Adds an ERC721 contract address to the registry.</span></span>
  ///</span> @dev</span> Reverts with `ERC721RegistryFull` if the registry is full.</span></span>
  ///</span> @param</span> _erc721Contract</span> Address of the ERC721 contract to register.</span></span>
  function</span> addERC721Contract</span>(</span>address</span> _erc721Contract</span>)</span> internal</span> {</span> </span></span>
    ERC721RegistryStorage </span>storage</span> s </span>=</span> getStorage</span>(</span>)</span>;</span></span>
</span>
    if</span>(</span>s</span>.</span>erc721Contracts</span>.</span>length </span>==</span> s</span>.</span>registryLimit</span>)</span> {</span></span>
      revert</span> ERC721RegistryFull</span>(</span>)</span>;</span></span>
    }</span></span>
    </span></span>
    s</span>.</span>erc721Contracts</span>.</span>push</span>(</span>_erc721Contract</span>)</span>;</span>        </span></span>
  }</span></span>
</span>
  ///</span> @notice</span> Returns a list of all registered ERC721 contract addresses.</span></span>
  ///</span> @return</span> Array</span> of registered ERC721 contract addresses.</span></span>
  function</span> getERC721Registry</span>(</span>)</span> internal</span> view</span> returns</span> (</span>address</span>[</span>]</span> memory</span>)</span> {</span></span>
    return</span> getStorage</span>(</span>)</span>.</span>erc721Contracts</span>;</span></span>
  }</span></span>
}</span></span></code></pre>Security Considerations</h2>
Uniqueness of identifiers</h3>
Two independent contracts or libraries using the same human-readable string will map to the same storage slot. Developers must ensure that diamond storage identifiers are unique within a contract system to prevent unintentional data overlap or corruption. A common practice is to prefix identifiers with a project, organization, or standard name (for example, "myproject.erc721.registry"</code>).</p>
ASCII Input Restriction to Prevent Storage Collisions</h3>
To prevent storage collisions, diamond storage identifiers must consist only of printable ASCII characters, specifically the range 0x20</code> to 0x7E</code> inclusive. Identifiers must not include Unicode escape sequences (\uNNNN</code>) or hexadecimal escape sequences (\xNN</code>).</p>
Solidity’s storage slot encoding, as produced by abi.encode(p)</code>, contains non-printable bytes, particularly null bytes (0x00</code>), due to Solidity’s default storage layout and padding rules.</p>
Allowing identifiers to include such bytes could enable a malicious developer to craft an identifier like "config\x00\x00..."</code>. The bytes of such an identifier could collide with the storage encoded input of mappings, dynamic arrays, strings and bytes which use keccak256</code> to compute storage locations. Such collisions could result in overwrites, corruption of contract state, or security vulnerabilities.</p>
Restricting identifiers to printable ASCII removes this exploitable source of collision. While this restriction does not provide a mathematical guarantee that collisions are impossible — because, in theory, a sufficiently large storage layout position (p</code>) could accidentally contain all printable ASCII bytes — the probability of this occurring is extremely small, and impractical.</p>
By using human-readable, meaningful strings for identifiers, the practical likelihood of any collision is virtually zero, providing strong protection for the integrity and safety of contract storage.</p>
String Literals</h3>
The specification recommends using string literals to create diamond storage identifiers because the Solidity compiler enforces that only printable ASCII characters are used. However, string literals should not use Unicode escape sequences (\uNNNN</code> ) or hexadecimal escape sequences (\xNN</code> ).</p>
Unicode Literals</h3>
Unicode literals (e.g. unicode"Hello 😃"</code>) should not be used to create diamond storage identifiers because they can contain non-printable bytes and characters, and they can be used to obfuscate identifiers by using characters that look like other characters. For example, the Cyrillic character а</code> (\u0430</code>) looks identical to the ASCII character a</code> (\u0061</code>).” In addition Unicode has control characters that change the direction text is displayed.</p>
keccak256</code> Hash Collision Resistance</h3>
The location of a diamond storage struct is determined by the output of the keccak256</code> hash function. Some developers may wonder about the likelihood that a diamond storage struct lands at an address where it will accidentally overwrite existing storage data. The 256-bit address space of contract storage is so vast that the likelihood of data overlap is statistically improbable.</p>
Solidity mappings, dynamic arrays, strings and bytes also use keccak256</code> to determine their location in contract storage.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Contract-Level Onchain Metadata
2025-10-10T00:00:00+00:00
Abstract</h2>
This ERC defines a standard for storing contract-level metadata onchain. It extends ERC-7572</a>'s contract-level metadata concept by providing onchain storage. Contracts MAY optionally use ERC-8042</a>'s Diamond Storage pattern for predictable storage locations, enabling cross-chain compatibility and supporting upgradable contracts.</p>
Motivation</h2>
Contract metadata today typically relies on offchain storage such as URLs or IPFS, creating trust and availability risks—servers go down, domains expire, and malicious actors can modify data without onchain record. Storing metadata onchain makes contract identity censorship-resistant and enables wallets and block explorers to display verifiable information without trusting external services.</p>
Specification</h2>
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.</p>
Required Metadata Function and Event</h3>
Contracts implementing this ERC MUST implement the following interface:</p>
interface</span> IERC8049</span> {</span></span>
    ///</span> @notice</span> Get contract metadata value for a key.</span></span>
    function</span> getContractMetadata</span>(</span>string</span> calldata</span> key</span>)</span> external</span> view</span> returns</span> (</span>bytes</span> memory</span>)</span>;</span></span>
    </span></span>
    ///</span> @notice</span> Emitted when contract metadata is updated.</span></span>
    event</span> ContractMetadataUpdated</span>(</span>string</span> indexed</span> indexedKey</span>, </span>string</span> key</span>, </span>bytes</span> value</span>)</span>;</span></span>
}</span></span></code></pre>
Contracts implementing this ERC MAY also expose a setContractMetadata(string calldata key, bytes calldata value)</code> function to allow metadata updates, with write policy determined by the contract.</p>
Contracts implementing this ERC MUST emit the following event when metadata is set:</p>
event</span> ContractMetadataUpdated</span>(</span>string</span> indexed</span> indexedKey</span>, </span>string</span> key</span>, </span>bytes</span> value</span>)</span>;</span></span></code></pre>Key/Value Pairs</h3>
This ERC specifies that the key is a string type and the value is bytes type. This provides flexibility for storing any type of data while maintaining an intuitive string-based key interface.</p>
Optional Key Parameters</h3>
Keys MAY include parameters to represent variations or instances of a metadata type, such as "registration: 1"</code> or "name: Maria"</code>; see ERC-8119</a>: Key Parameters.</p>
Optional Diamond Storage</h3>
Contracts implementing this ERC MAY use Diamond Storage pattern for predictable storage locations. If implemented, contracts MUST use the namespace ID "erc8049.contract.metadata.storage"</code>.</p>
The Diamond Storage pattern provides predictable storage locations for data, which is useful for cross-chain applications using inclusion proofs and for upgradable contracts. For more details on Diamond Storage, see ERC-8042</a>.</p>
Value Interpretation</h3>
If no standard is specified for a metadata value, clients MAY assume the value is a UTF-8 encoded string (bytes(string)) unless otherwise specified by the implementing contract or protocol.</p>
Examples</h3>
Example: Basic Contract Information</h4>
A contract can store basic information about itself:</p>

Key: "name"</code> → Value: bytes("MyToken")</code></li>
Key: "description"</code> → Value: bytes("A decentralized exchange")</code></li>
Key: "collaborators"</code> → Value: bytes(abi.encodePacked(address1, address2, address3))</code></li>
</ul>
Example: ENS Name for Contract</h4>
A contract can specify its ENS name using this standard:</p>

Key: "ens_name"</code> → Value: bytes("mycontract.eth")</code></li>
</ul>
This allows clients to discover the contract's ENS name and resolve it to get additional information about the contract.</p>
Optional Metadata Hooks</h3>
Contracts implementing this ERC MAY use hooks to redirect metadata resolution to a different contract. For the full specification, see ERC-8121</a>. When using hooks with contract metadata, the target function MUST be getContractMetadata(string)</code> returning bytes</code>. The hook selector is 0x9e574b14</code>.</p>
Rationale</h2>
This design prioritizes simplicity and flexibility by using a string-key, bytes-value store that provides an intuitive interface for any type of contract metadata. The minimal interface with a single getContractMetadata</code> function provides all necessary functionality. The optional setContractMetadata</code> function enables flexible access control for metadata updates. The required ContractMetadataUpdated</code> event provides transparent audit trails with indexed key for efficient filtering. Contracts that need predictable storage locations can optionally use Diamond Storage pattern. This makes the standard suitable for diverse use cases including contract identification, collaboration tracking, and custom metadata storage.</p>
Backwards Compatibility</h2>

Fully compatible with existing smart contracts.</li>
Non-supporting clients can ignore the scheme.</li>
</ul>
Reference Implementation</h2>
The interface is defined in the Required Metadata Function and Event section above. Here are reference implementations:</p>
Basic Implementation</h3>
pragma</span> solidity</span> ^0.8.25</span>;</span></span>
</span>
import</span> "./IERC8049.sol"</span>;</span></span>
</span>
contract</span> BasicContractMetadata</span> is</span> IERC8049</span> {</span></span>
    //</span> Simple mapping for contract-level metadata</span></span>
    mapping</span>(</span>string</span> key </span>=></span> bytes</span> value</span>)</span> private</span> _metadata</span>;</span></span>
</span>
    function</span> getContractMetadata</span>(</span>string</span> calldata</span> key</span>)</span> external</span> view</span> override</span> returns</span> (</span>bytes</span> memory</span>)</span> {</span></span>
        return</span> _metadata</span>[</span>key</span>]</span>;</span></span>
    }</span></span>
</span>
    function</span> setContractMetadata</span>(</span>string</span> calldata</span> key</span>,</span> bytes</span> calldata</span> value</span>)</span> external</span> {</span></span>
        _metadata</span>[</span>key</span>]</span> =</span> value</span>;</span></span>
        emit</span> ContractMetadataUpdated</span>(</span>key</span>,</span> key</span>,</span> value</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Diamond Storage Implementation</h3>
pragma</span> solidity</span> ^0.8.25</span>;</span></span>
</span>
import</span> "./IERC8049.sol"</span>;</span></span>
</span>
contract</span> DiamondContractMetadata</span> is</span> IERC8049</span> {</span></span>
    struct</span> ContractMetadataStorage</span> {</span></span>
        mapping</span>(</span>string</span> key </span>=></span> bytes</span> value</span>)</span> metadata</span>;</span></span>
    }</span></span>
</span>
    //</span> keccak256("erc8049.contract.metadata.storage")</span></span>
    bytes32</span> private</span> constant</span> CONTRACT_METADATA_STORAGE_LOCATION </span>=</span></span>
        keccak256</span>(</span>"erc8049.contract.metadata.storage"</span>)</span>;</span></span>
</span>
    function</span> _getContractMetadataStorage</span>(</span>)</span> private</span> pure</span> returns</span> (</span>ContractMetadataStorage</span> storage</span> $</span>)</span> {</span></span>
        bytes32</span> location </span>=</span> CONTRACT_METADATA_STORAGE_LOCATION</span>;</span></span>
        assembly</span> {</span></span>
            $</span>.</span>slot </span>:=</span> location</span></span>
        }</span></span>
    }</span></span>
</span>
    function</span> getContractMetadata</span>(</span>string</span> calldata</span> key</span>)</span> external</span> view</span> override</span> returns</span> (</span>bytes</span> memory</span>)</span> {</span></span>
        ContractMetadataStorage </span>storage</span> $ </span>=</span> _getContractMetadataStorage</span>(</span>)</span>;</span></span>
        return</span> $</span>.</span>metadata</span>[</span>key</span>]</span>;</span></span>
    }</span></span>
</span>
    function</span> setContractMetadata</span>(</span>string</span> calldata</span> key</span>,</span> bytes</span> calldata</span> value</span>)</span> external</span> {</span></span>
        ContractMetadataStorage </span>storage</span> $ </span>=</span> _getContractMetadataStorage</span>(</span>)</span>;</span></span>
        $</span>.</span>metadata</span>[</span>key</span>]</span> =</span> value</span>;</span></span>
        emit</span> ContractMetadataUpdated</span>(</span>key</span>,</span> key</span>,</span> value</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Security Considerations</h2>
This ERC is designed to put metadata onchain, providing security benefits through onchain storage.</p>
Implementations that choose to use the optional Diamond Storage pattern should consider the security considerations of ERC-8042</a>.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Referable NFT Royalties
2025-10-02T00:00:00+00:00
Abstract</h2>
This ERC proposes Royalty Motivatio Specif 
The key words "MUST", 
Interface</h3> The IRNFTRoyalty 
</span>  </span>   </span>  </span>  </span>  </span>    </span>    Implementations 
Additional interfaces </ul>  RECOMMENDED Typed Struct</p> 
         Structs</h4>  RoyaltyInfo</code>:  recipient: The address 
royaltyAmount</code>: </ul> </li> 
ReferenceRoyalty</code>:  royaltyInfos</code>: 
referenceDepth</code>: </ul> </li> </ul> Functions</h4>   getReferenceRoyaltyInfo(address 
 Returns a ReferenceRoyalty 
Includes primary-level 
MUST return zero </ul> </li> 
 getReferenceRoyaltyInfo(address 
 Returns a ReferenceRoyalty 
Includes primary-level 
MUST return the </ul> </li> 
 setReferenceRoyalty(address 
 Configures royalties 
recipients and royaltyFractions 
referenceDepth limits 
MUST be restricted 
MUST enforce a total </ul> </li> 
 setReferenceRoyalty(address 
 Signature-based 
MUST verify signer 
The signer parameter </ul> </li> 
 supportsReferenceRoy 
 Returns true if </ul> </li> 
 royaltyNonce(address 
 Returns the current </ul> </li> </ul> Events</h4>  ReferenceRoyaltiesP </ul> Example</h3> For an rNFT (contract 
  Configuration:</p> 
 Primary royalties: 
Depth 1: Two referenced 
Depth 2: No royalties </ul> </li> 
 getReferenceRoyaltyInfo(0xABC, 
  Returns:</p> 
{ royaltyInfos: [ </li> </ul> </li> 
 Sale for 100 ETH:</p> 
  getReferenceRoyaltyInfo(0xABC, 
{ royaltyInfos: [ </li> </ul> </li> </ul> 
Rationale</h2>  Fixed Royalty Query: 
Multiple Recipients: 
Single Depth Limit: 
Standalone Design: 
Voluntary Royalties: 
Transparency: On-chain 
ERC-165 Discoverability: 
EIP-712 Signatures: </ul> Backwards This standard is 
 Checking ERC-165: 
Calling getReferenc 
Optionally leveraging </ul> pragma </span> import import import import import import </span> import </span> interface      </span> contract  </span>      </span>            </span>      </span>     </span>  </span>         </span>                   </span>                   </span>      </span>  </span>              </span>    </span>       </span>   </span>             </span>                         </span>              </span>    </span>            </span>                </span>             </span>    </span>    </span>   </span>      </span>          </span>   </span>    </span>    </span>               </span>    </span>       </span>       </span>   </span>          </span>            </span>   </span>    </span>            </span>             </span>                           </span>                                      </span>    </span>         </span>   </span>         </span>     </span>   </span>     </span>   </span>      </span>   </span>      </span>          </span>      </span>          </span>           </span>  </span>       </span>  </span>        </span>        </span>      </span>   </span>    </span>   </span>           </span>           Access Control: 
Total Royalty Cap 
Gas Limits: referen 
Input Validation: 
Interface Signaling: 
Signature Replay: </ul> Copyright</h2> Copyright and related 
  Agent Council Oracles
 2025-09-28T00:00:00+00:00

Distribution, a standalone royalty distribution for Referable Non-Fungible Tokens (rNFTs). It enables royalty distribution to multiple recipients at the primary level and referenced NFTs in the directed acyclic graph (DAG), with a single depth limit to control propagation. The standard is independent of ERC-2981</a>. and token-standard-agnostic, but expects ERC-5521</a> rNFTs, which in practice build on ERC-721</a> ownership semantics. It includes a function to query fixed royalty amounts (in basis points) for transparency. Royalties are voluntary, transparent, and configurable on-chain, supporting collaborative ecosystems and fair compensation.</p> n</h2> ;wg-eips.ritovision.com/5521/">ERC-5521</a> introduces Referable NFTs (rNFTs), which form a DAG through "referring" and "referred" relationships. Existing royalty standards like ERC-2981</a> do not account for this structure or support multiple recipients per level. This EIP addresses the need for a royalty mechanism that:</p> recipients per royalty level (e.g., creators and collaborators).</li> to referenced NFTs in the DAG.</li> with a single reference depth.</li> to query fixed royalty amounts without a sale price.</li> to query fixed royalty amounts with a sale price.</li> of ERC-721</a> or ERC-2981</a>.</li> for marketplaces and users.</li> via ERC-165</a> supportsInterface.</li> EIP-712</a> signature-based configuration to streamline marketplace or owner-driven updates.</li> ication</h2> "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.</p> interface defines the royalty distribution for rNFTs and MUST inherit ERC165</code> so that supporting contracts can advertise compliance via ERC-165</a>:</p> data-lang="solidity">//</span> SPDX-License-Identifier: CC0-1.0</span></span> class="z-keyword">pragma</span> solidity</span> ^0.8.0</span>;</span></span> class="z-storage z-type">interface</span> IRNFTRoyalty</span> is</span> ERC165</span> {</span></span> class="z-storage z-type">    struct</span> RoyaltyInfo</span> {</span></span> class="z-support">        address</span> recipient</span>;</span> //</span> Address to receive royalty</span></span> class="z-support">        uint256</span> royaltyAmount</span>;</span> //</span> Royalty amount (in wei for sale-based queries, basis points for fixed queries)</span></span> }</span></span> class="z-storage z-type">    struct</span> ReferenceRoyalty</span> {</span></span> RoyaltyInfo</span>[</span>]</span> royaltyInfos</span>;</span> //</span> Array of recipients and their royalty amounts</span></span> class="z-support">        uint256</span> referenceDepth</span>;</span> //</span> Maximum depth in the reference DAG for royalty distribution</span></span> }</span></span> class="z-storage z-type">    event</span> ReferenceRoyaltiesPaid</span>(</span></span> class="z-support">        address</span> indexed</span> rNFTContract</span>,</span></span> class="z-support">        uint256</span> indexed</span> tokenId</span>,</span></span> class="z-support">        address</span> indexed</span> buyer</span>,</span></span> class="z-support">        address</span> marketplace</span>,</span></span> class="z-variable">        ReferenceRoyalty</span> royalties</span></span> )</span>;</span></span> class="z-storage z-type">    function</span> getReferenceRoyaltyInfo</span>(</span></span> class="z-support">        address</span> rNFTContract</span>,</span></span> class="z-support">        uint256</span> tokenId</span>,</span></span> class="z-support">        uint256</span> salePrice</span></span> )</span> external</span> view</span> returns</span> (</span>ReferenceRoyalty</span> memory</span> royalties</span>)</span>;</span></span> class="z-storage z-type">    function</span> getReferenceRoyaltyInfo</span>(</span></span> class="z-support">        address</span> rNFTContract</span>,</span></span> class="z-support">        uint256</span> tokenId</span></span> )</span> external</span> view</span> returns</span> (</span>ReferenceRoyalty</span> memory</span> royalties</span>)</span>;</span></span> class="z-storage z-type">    function</span> setReferenceRoyalty</span>(</span></span> class="z-support">        address</span> rNFTContract</span>,</span></span> class="z-support">        uint256</span> tokenId</span>,</span></span> class="z-support">        address</span>[</span>]</span> memory</span> recipients</span>,</span></span> class="z-support">        uint256</span>[</span>]</span> memory</span> royaltyFractions</span>,</span></span> class="z-support">        uint256</span> referenceDepth</span></span> )</span> external</span>;</span></span> </span></span> class="z-storage z-type">    function</span> setReferenceRoyalty</span>(</span></span> class="z-support">        address</span> rNFTContract</span>,</span></span> class="z-support">        uint256</span> tokenId</span>,</span></span> class="z-support">        address</span>[</span>]</span> memory</span> recipients</span>,</span></span> class="z-support">        uint256</span>[</span>]</span> memory</span> royaltyFractions</span>,</span></span> class="z-support">        uint256</span> referenceDepth</span>,</span></span> class="z-support">        address</span> signer</span>,</span></span> class="z-support">        uint256</span> deadline</span>,</span></span> class="z-support">        bytes</span> calldata</span> signature</span></span> )</span> external</span>;</span></span> class="z-storage z-type">    function</span> supportsReferenceRoyalties</span>(</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> </span></span> class="z-storage z-type">    function</span> royaltyNonce</span>(</span>address</span> signer</span>,</span> address</span> rNFTContract</span>,</span> uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> }</span></span></code></pre>
ERC-165 requirement</h3> MUST return true for supportsInterface(type(IRNFTRoyalty).interfaceId)</code>.</li> (e.g., AccessControl) SHOULD be forwarded via super.supportsInterface(interfaceId)</code> when using inheritance.</li> guration">Signature-Based Configuration</h3> and flexible configuration, implementations MUST support the following semantics for the signature overload:</p> recovered EIP-712 signer MUST satisfy one of: ract).ownerOf(tokenId)</code> at verification time.</li> message MUST include a nonce; the contract MUST track, verify, and increment a nonce to prevent replay.</li> EIP-712 domain and struct as below (reference implementation provided).</li> compared against block.timestamp; signatures with block.timestamp > deadline MUST be rejected.</li> version = "2", chainId, verifyingContract = address(this)</li> data-lang="plain">SetReferenceRoyalty(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> bytes32 recipientsHash,        // keccak256(abi.encode(recipients))</span></span> bytes32 royaltyFractionsHash,  // keccak256(abi.encode(royaltyFractions))</span></span> uint256 referenceDepth,</span></span> address signer,</span></span> uint256 deadline,</span></span> uint256 nonce</span></span> )</span></span></code></pre>Key Components</h3> to receive the royalty payment.</li> The royalty amount, in wei for getReferenceRoyaltyInfo</code> with salePrice, or basis points (e.g., 100 = 1%) for getReferenceRoyaltyInfo</code> without salePrice.</li> An array of RoyaltyInfo</code> for multiple recipients at the primary level and referenced NFTs.</li> A single value limiting royalty distribution to referenced NFTs in the DAG.</li> rNFTContract, uint256 tokenId, uint256 salePrice)</code>:</p> struct with royalty amounts in wei, calculated from the salePrice.</li> royalties and referenced NFT royalties up to referenceDepth</code>.</li> amounts if no royalties are configured or if salePrice is zero.</li> rNFTContract, uint256 tokenId)</code>:</p> struct with fixed royalty amounts in basis points (e.g., 100 = 1%).</li> royalties and referenced NFT royalties up to referenceDepth.</li> configured royalty fractions without sale price calculations.</li> rNFTContract, uint256 tokenId, address[] recipients, uint256[] royaltyFractions, uint256 referenceDepth)</code>:</p> for the specified rNFT.</li> (in basis points) define primary-level royalties.</li> royalty distribution to referenced NFTs.</li> to authorized parties (e.g., rNFT contract owner).</li> primary-level royalty cap of ≤ 1000 basis points (10%).</li> rNFTContract, uint256 tokenId, address[] recipients, uint256[] royaltyFractions, uint256 referenceDepth, address signer, uint256 deadline, bytes signature)</code>:</p> configuration per EIP-712.</li> authorization, nonce, and enforce deadline to reject expired signatures.</li> specifies which address is expected to have signed the message, enabling relayer execution.</li> alties()</code>:</p> the contract implements this standard. Discovery MUST rely on ERC-165.</li> signer, address rNFTContract, uint256 tokenId) external view returns (uint256)</code>:</p> nonce used for EIP-712 signatures.</li> aid</code>: Emitted when royalties are paid, logging the rNFT contract, token ID, buyer, marketplace, and ReferenceRoyalty</code> details (with royaltyAmount in wei).</li> model">Royalty Distribution Model</h3> The rNFT’s royaltyInfos array specifies multiple recipients and their fractions (e.g., 5% total, split as 3% and 2%).</li> At each hop, a total forwarded share equal to REFERRED_ROYALTY_FRACTION (e.g., 200 bps / 2%) is carved out and distributed across all referenced NFTs at that depth proportional to their configured weights (fallback: evenly if all weights are zero).</li> (Primary Level): The 10% (1000 bps) cap applies to the primary-level configured royaltyFractions. Propagated/reference-level flows are governed separately by REFERRED_ROYALTY_FRACTION and referenceDepth.</li> MUST cap referenceDepth</code>; this reference implementation enforces <= 3 (RECOMMENDED).</li> The getReferenceRoyaltyInfo</code> function without salePrice returns royalty fractions in basis points, enabling transparent inspection.</li> 0xABC, token ID 1) with referenceDepth</code> = 2:</p> 5% (3% to creator, 2% to collaborator).</li> NFTs; a total of 2% is forwarded at depth 1 and split equally (1% each) under equal weights.</li> (capped by referenceDepth).</li> 1)</code>:</p> {recipient: creator, royaltyAmount: 300}, {recipient: collaborator, royaltyAmount: 200}, {recipient: tokenA_owner, royaltyAmount: 100}, {recipient: tokenB_owner, royaltyAmount: 100} ], referenceDepth: 2 }.</p> 1, 100 ether) returns:</p> {recipient: creator, royaltyAmount: 3 ether}, {recipient: collaborator, royaltyAmount: 2 ether}, {recipient: tokenA_owner, royaltyAmount: 1 ether}, {recipient: tokenB_owner, royaltyAmount: 1 ether} ], referenceDepth: 2 }.</p> The new getReferenceRoyaltyInfo</code> function without salePrice allows users to inspect fixed royalty fractions (in basis points), improving transparency.</li> The RoyaltyInfo</code> array supports collaborative projects.</li> Simplifies configuration and reduces gas costs.</li> Ensures compatibility with any ERC-5521 contract.</li> Aligns with marketplace practices.</li> storage and fixed-amount queries enable verifiable royalties.</li> Marketplaces and wallets can reliably detect support via supportsInterface, avoiding ad-hoc feature flags.</li> Off-chain approvals enable safe, gas-efficient configurations.</li> Compatibility</h2> independent of ERC-2981 and targets ERC-5521 rNFTs, which in practice build on ERC-721 ownership semantics. Marketplaces can integrate by:</p> supportsInterface(type(IRNFTRoyalty).interfaceId)</code>.</li> eRoyaltyInfo</code> (with or without sale price).</li> the signature-based configuration for off-chain workflows.</li> ion">Reference Implementation</h2> data-lang="plain">// SPDX-License-Identifier: CC0-1.0</span></span> solidity ^0.8.0;</span></span> "@openzeppelin/contracts/access/AccessControl.sol";</span></span> "@openzeppelin/contracts/utils/cryptography/EIP712.sol"; </span></span> "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";</span></span> "@openzeppelin/contracts/utils/introspection/IERC165.sol";</span></span> "@openzeppelin/contracts/token/ERC721/IERC721.sol";</span></span> "@openzeppelin/contracts/utils/ReentrancyGuard.sol";</span></span> "./IRNFTRoyalty.sol";</span></span> IERC_5521 is IERC165 {</span></span> function setNode(uint256 tokenId, address[] memory addresses, uint256[][] memory tokenIds) external;</span></span> function referringOf(address _address, uint256 tokenId) external view returns (address[] memory, uint256[][] memory);</span></span> function referredOf(address _address, uint256 tokenId) external view returns (address[] memory, uint256[][] memory);</span></span> function supportsInterface(bytes4 interfaceId) external view returns (bool);</span></span> }</span></span> RNFTRoyalty is IRNFTRoyalty, AccessControl, EIP712, ReentrancyGuard {</span></span> using ECDSA for bytes32;</span></span> bytes32 public constant CONFIGURATOR_ROLE = keccak256("CONFIGURATOR_ROLE");</span></span> uint256 private constant MAX_ROYALTY_FRACTION = 1000; // 10%</span></span> uint256 private constant REFERRED_ROYALTY_FRACTION = 200; // 2%</span></span> uint256 private constant MAX_CHAIN_STEPS = 32;</span></span> uint256 private constant MAX_RECIPIENTS = 64;</span></span> // storage</span></span> mapping(address => mapping(uint256 => ReferenceRoyalty)) private _royalties;</span></span> event ReferenceRoyaltyConfigured(</span></span> address indexed rNFTContract,</span></span> uint256 indexed tokenId,</span></span> address indexed setter,</span></span> address[] recipients,</span></span> uint256[] royaltyFractions,</span></span> uint256 referenceDepth,</span></span> bool viaSignature</span></span> );</span></span> // EIP-712 typed data & nonce</span></span> bytes32 private constant _SET_TYPEHASH =</span></span> keccak256("SetReferenceRoyalty(address rNFTContract,uint256 tokenId,bytes32 recipientsHash,bytes32 royaltyFractionsHash,uint256 referenceDepth,address signer,uint256 deadline,uint256 nonce)");</span></span> // (signer => rNFT => tokenId => nonce)</span></span> mapping(address => mapping(address => mapping(uint256 => uint256))) private _sigNonces;</span></span> constructor() EIP712("RNFTRoyalty", "2") {</span></span> _grantRole(DEFAULT_ADMIN_ROLE, msg.sender);</span></span> _grantRole(CONFIGURATOR_ROLE, msg.sender);</span></span> }</span></span> // ===== IRNFTRoyalty =====</span></span> // expose nonce for off-chain signing</span></span> function royaltyNonce(address signer, address rNFTContract, uint256 tokenId)</span></span> external</span></span> view</span></span> returns (uint256)</span></span> {</span></span> return _sigNonces[signer][rNFTContract][tokenId];</span></span> }</span></span> function setReferenceRoyalty(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address[] calldata recipients,</span></span> uint256[] calldata royaltyFractions,</span></span> uint256 referenceDepth</span></span> ) external onlyRole(CONFIGURATOR_ROLE) {</span></span> _configureRoyalty(rNFTContract, tokenId, recipients, royaltyFractions, referenceDepth);</span></span> emit ReferenceRoyaltyConfigured(</span></span> rNFTContract,</span></span> tokenId,</span></span> msg.sender,</span></span> recipients,</span></span> royaltyFractions,</span></span> referenceDepth,</span></span> false</span></span> );</span></span> }</span></span> /// @notice Configure reference royalty via EIP-712 signature (supports relayers).</span></span> /// @dev</span></span> /// - Uses explicit `signer` for nonce lookup and authorization; caller can be a relayer.</span></span> /// - Includes `deadline` in the signed struct; reverts with "Signature expired" if now > deadline.</span></span> /// - Non-reentrant to defend against malicious `rNFT.ownerOf` implementations.</span></span> /// - Authorization: `signer` must have `CONFIGURATOR_ROLE` or be current `ownerOf(tokenId)`.</span></span> /// - Nonce scope: per-signer-per-token; increments on success to prevent replay.</span></span> function setReferenceRoyalty(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address[] calldata recipients,</span></span> uint256[] calldata royaltyFractions,</span></span> uint256 referenceDepth,</span></span> address signer,</span></span> uint256 deadline,</span></span> bytes calldata signature</span></span> ) external nonReentrant {</span></span> _checkParams(rNFTContract, recipients, royaltyFractions, referenceDepth);</span></span> bytes32 recipientsHash = keccak256(abi.encode(recipients));</span></span> bytes32 fractionsHash  = keccak256(abi.encode(royaltyFractions));</span></span> // Compute expected signer digest and use per-signer-per-token nonce (explicit signer for relaying)</span></span> require(signer != address(0), "Invalid signer");</span></span> uint256 nonce = _sigNonces[signer][rNFTContract][tokenId];</span></span> require(block.timestamp <= deadline, "Signature expired");</span></span> bytes32 structHash = keccak256(</span></span> abi.encode(</span></span> _SET_TYPEHASH,</span></span> rNFTContract,</span></span> tokenId,</span></span> recipientsHash,</span></span> fractionsHash,</span></span> referenceDepth,</span></span> signer,</span></span> deadline,</span></span> nonce</span></span> )</span></span> );</span></span> bytes32 digest = _hashTypedDataV4(structHash);</span></span> address recovered = ECDSA.recover(digest, signature);</span></span> require(recovered == signer && signer != address(0), "Invalid signature");</span></span> // Authorization: CONFIGURATOR_ROLE or current owner</span></span> bool authorized = hasRole(CONFIGURATOR_ROLE, signer);</span></span> if (!authorized) {</span></span> address owner = _safeOwnerOf(IERC721(rNFTContract), tokenId);</span></span> require(signer == owner, "Signer not authorized");</span></span> }</span></span> // effects: bump nonce to prevent replay</span></span> _sigNonces[signer][rNFTContract][tokenId] = nonce + 1;</span></span> // configure royalties</span></span> _configureRoyalty(rNFTContract, tokenId, recipients, royaltyFractions, referenceDepth);</span></span> emit ReferenceRoyaltyConfigured(</span></span> rNFTContract,</span></span> tokenId,</span></span> signer,</span></span> recipients,</span></span> royaltyFractions,</span></span> referenceDepth,</span></span> true</span></span> );</span></span> }</span></span> /// @notice Compute reference royalty distribution for a concrete sale price (values in wei).</span></span> /// @param rNFTContract RNFT contract implementing IERC_5521</span></span> /// @param tokenId Token id</span></span> /// @param salePrice Sale price in wei</span></span> function getReferenceRoyaltyInfo(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> uint256 salePrice</span></span> ) external view returns (ReferenceRoyalty memory royalties) {</span></span> royalties = _royalties[rNFTContract][tokenId];</span></span> if (salePrice == 0) {</span></span> uint256 len = royalties.royaltyInfos.length;</span></span> if (len == 0) return royalties;</span></span> RoyaltyInfo[] memory zeroed = new RoyaltyInfo[](len);</span></span> for (uint256 i = 0; i < len; i++) {</span></span> zeroed[i] = RoyaltyInfo(royalties.royaltyInfos[i].recipient, 0);</span></span> }</span></span> royalties.royaltyInfos = zeroed;</span></span> return royalties;</span></span> }</span></span> RoyaltyInfo[] memory chainRoyalties = _calculateChainRoyalties(rNFTContract, tokenId, salePrice);</span></span> royalties.royaltyInfos = chainRoyalties;</span></span> return royalties;</span></span> }</span></span> /// @notice Compute reference royalty distribution in basis points (bps), i.e. relative amounts.</span></span> /// @param rNFTContract RNFT contract implementing IERC_5521</span></span> /// @param tokenId Token id</span></span> function getReferenceRoyaltyInfo(</span></span> address rNFTContract,</span></span> uint256 tokenId</span></span> ) external view returns (ReferenceRoyalty memory royalties) {</span></span> royalties = _royalties[rNFTContract][tokenId];</span></span> if (royalties.royaltyInfos.length == 0) return royalties;</span></span> RoyaltyInfo[] memory bpsRoyalties = _calculateChainRoyalties(rNFTContract, tokenId, 0);</span></span> royalties.royaltyInfos = bpsRoyalties;</span></span> return royalties;</span></span> }</span></span> function supportsReferenceRoyalties() external pure returns (bool) {</span></span> return true;</span></span> }</span></span> // ===== ERC-165 =====</span></span> function supportsInterface(bytes4 interfaceId)</span></span> public</span></span> view</span></span> override(AccessControl, IERC165)</span></span> returns (bool)</span></span> {</span></span> return</span></span> interfaceId == type(IRNFTRoyalty).interfaceId ||</span></span> super.supportsInterface(interfaceId);</span></span> }</span></span> // ===== Internal =====</span></span> function _checkParams(</span></span> address rNFTContract,</span></span> address[] calldata recipients,</span></span> uint256[] calldata royaltyFractions,</span></span> uint256 referenceDepth</span></span> ) internal pure {</span></span> require(rNFTContract != address(0), "Invalid contract");</span></span> require(recipients.length == royaltyFractions.length, "Length mismatch");</span></span> require(recipients.length <= MAX_RECIPIENTS, "Too many recipients");</span></span> require(referenceDepth <= 3, "Depth too high");</span></span> for (uint256 i = 0; i < recipients.length; ++i) {</span></span> require(recipients[i] != address(0), "Zero recipient");</span></span> }</span></span> }</span></span> function _configureRoyalty(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address[] calldata recipients,</span></span> uint256[] calldata royaltyFractions,</span></span> uint256 referenceDepth</span></span> ) internal {</span></span> uint256 totalFraction = 0;</span></span> for (uint256 i = 0; i < royaltyFractions.length; i++) {</span></span> totalFraction += royaltyFractions[i];</span></span> }</span></span> require(totalFraction <= MAX_ROYALTY_FRACTION, "Royalty cap exceeded");</span></span> ReferenceRoyalty memory config;</span></span> config.referenceDepth = referenceDepth;</span></span> config.royaltyInfos = new RoyaltyInfo[](recipients.length);</span></span> for (uint256 i = 0; i < recipients.length; i++) {</span></span> config.royaltyInfos[i] = RoyaltyInfo(recipients[i], royaltyFractions[i]);</span></span> }</span></span> _royalties[rNFTContract][tokenId] = config;</span></span> }</span></span> function _safeOwnerOf(IERC721 rNFT, uint256 tokenId) internal view returns (address) {</span></span> address owner = rNFT.ownerOf(tokenId);</span></span> require(owner != address(0), "No owner");</span></span> return owner;</span></span> }</span></span> function _calculateChainRoyalties(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> uint256 salePrice</span></span> ) internal view returns (RoyaltyInfo[] memory) {</span></span> ReferenceRoyalty memory currentRoyalty = _royalties[rNFTContract][tokenId];</span></span> if (currentRoyalty.royaltyInfos.length == 0) {</span></span> return new RoyaltyInfo[](0);</span></span> }</span></span> RoyaltyInfo[] memory staged = new RoyaltyInfo[](MAX_CHAIN_STEPS * 32 + 32);</span></span> uint256 count = 0;</span></span> uint256 totalShare = _sumShares(currentRoyalty);</span></span> (uint256 netPrimary, uint256 remainder) = _splitRoyalty(totalShare, salePrice, currentRoyalty.referenceDepth > 0);</span></span> count = _appendDistribution(staged, count, currentRoyalty, netPrimary);</span></span> if (remainder == 0) {</span></span> return _shrink(staged, count);</span></span> }</span></span> // Layered aggregation (BFS) to support multi-parent merges</span></span> uint256 maxItems = MAX_CHAIN_STEPS * 32 + 32;</span></span> address[] memory curContracts = new address[](maxItems);</span></span> uint256[] memory curIds = new uint256[](maxItems);</span></span> uint256[] memory curAmts = new uint256[](maxItems);</span></span> uint256[] memory curDepths = new uint256[](maxItems);</span></span> uint256 curCount = 0;</span></span> if (remainder > 0 && currentRoyalty.referenceDepth > 0) {</span></span> curContracts[0] = rNFTContract;</span></span> curIds[0] = tokenId;</span></span> curAmts[0] = remainder;</span></span> curDepths[0] = currentRoyalty.referenceDepth;</span></span> curCount = 1;</span></span> }</span></span> address[] memory processedContracts = new address[](maxItems);</span></span> uint256[] memory processed = new uint256[](maxItems);</span></span> uint256 processedCount = 0;</span></span> while (curCount > 0) {</span></span> address[] memory nextContracts = new address[](maxItems);</span></span> uint256[] memory nextIds = new uint256[](maxItems);</span></span> uint256[] memory nextAmts = new uint256[](maxItems);</span></span> uint256[] memory nextDepths = new uint256[](maxItems);</span></span> uint256 nextCount = 0;</span></span> for (uint256 iL = 0; iL < curCount; iL++) {</span></span> address curContract = curContracts[iL];</span></span> uint256 curId = curIds[iL];</span></span> uint256 amt = curAmts[iL];</span></span> uint256 depth = curDepths[iL];</span></span> if (amt == 0) continue;</span></span> IERC_5521 curRNFT = IERC_5521(curContract);</span></span> IERC721 curRNFT721 = IERC721(curContract);</span></span> bool seen = false;</span></span> for (uint256 p = 0; p < processedCount; p++) {</span></span> if (processed[p] == curId && processedContracts[p] == curContract) { seen = true; break; }</span></span> }</span></span> if (seen) {</span></span> address cycOwner = _safeOwnerOf(curRNFT721, curId);</span></span> staged[count++] = RoyaltyInfo(cycOwner, amt);</span></span> continue;</span></span> }</span></span> uint256 maxChildren = 32;</span></span> address[] memory childContracts = new address[](maxChildren);</span></span> uint256[] memory childIds = new uint256[](maxChildren);</span></span> uint256 children = _collectReferring(curRNFT, curContract, curId, childContracts, childIds);</span></span> if (depth == 0 || children == 0) {</span></span> address fallbackOwner = _safeOwnerOf(curRNFT721, curId);</span></span> staged[count++] = RoyaltyInfo(fallbackOwner, amt);</span></span> processedContracts[processedCount] = curContract;</span></span> processed[processedCount++] = curId;</span></span> continue;</span></span> }</span></span> uint256 keepBase = (amt * (10_000 - REFERRED_ROYALTY_FRACTION)) / 10_000;</span></span> uint256 passBase = amt - keepBase;</span></span> uint256[] memory childWeights = new uint256[](maxChildren);</span></span> ReferenceRoyalty[] memory childConfigs = new ReferenceRoyalty[](maxChildren);</span></span> uint256 sumWeights = 0;</span></span> for (uint256 j = 0; j < children; j++) {</span></span> address childContract = childContracts[j];</span></span> uint256 cid = childIds[j];</span></span> ReferenceRoyalty memory cfg = _royalties[childContract][cid];</span></span> childConfigs[j] = cfg;</span></span> if (cfg.royaltyInfos.length > 0) {</span></span> uint256 w = _sumShares(cfg);</span></span> childWeights[j] = w;</span></span> sumWeights += w;</span></span> }</span></span> }</span></span> if (sumWeights == 0) {</span></span> uint256 each = amt / children;</span></span> uint256 rem = amt - (each * children);</span></span> for (uint256 j = 0; j < children; j++) {</span></span> address ow = _safeOwnerOf(IERC721(childContracts[j]), childIds[j]);</span></span> uint256 share = each + (j == children - 1 ? rem : 0);</span></span> staged[count++] = RoyaltyInfo(ow, share);</span></span> }</span></span> processedContracts[processedCount] = curContract;</span></span> processed[processedCount++] = curId;</span></span> continue;</span></span> }</span></span> uint256 passDistributed = 0;</span></span> uint256 lastWeightedIdx = 0;</span></span> uint256[] memory keepShares = new uint256[](children);</span></span> uint256[] memory passShares = new uint256[](children);</span></span> for (uint256 j = 0; j < children; j++) {</span></span> if (childWeights[j] == 0) continue;</span></span> lastWeightedIdx = j;</span></span> uint256 kShare = (keepBase * childWeights[j]) / sumWeights;</span></span> uint256 pShare = (passBase * childWeights[j]) / sumWeights;</span></span> keepShares[j] = kShare;</span></span> passShares[j] = pShare;</span></span> passDistributed += pShare;</span></span> }</span></span> // Remainders: pass and keep</span></span> uint256 passRemainder = passBase - passDistributed;</span></span> if (passRemainder > 0) {</span></span> passShares[lastWeightedIdx] += passRemainder;</span></span> }</span></span> uint256 keepDistributed = 0;</span></span> for (uint256 j2 = 0; j2 < children; j2++) {</span></span> keepDistributed += keepShares[j2];</span></span> }</span></span> uint256 keepRemainder = keepBase - keepDistributed;</span></span> if (keepRemainder > 0) {</span></span> keepShares[lastWeightedIdx] += keepRemainder;</span></span> }</span></span> for (uint256 j = 0; j < children; j++) {</span></span> if (childWeights[j] == 0) continue;</span></span> uint256 kShare = keepShares[j];</span></span> uint256 pShare = passShares[j];</span></span> ReferenceRoyalty memory cfgj = childConfigs[j];</span></span> uint256 cid2 = childIds[j];</span></span> address childContract = childContracts[j];</span></span> uint256 nextDepth = depth > 0 ? depth - 1 : 0;</span></span> if (nextDepth == 0) {</span></span> // Depth exhausted: distribute both keep and pass to child's recipients</span></span> count = _appendDistribution(staged, count, cfgj, kShare + pShare);</span></span> } else {</span></span> if (kShare > 0) {</span></span> count = _appendDistribution(staged, count, cfgj, kShare);</span></span> }</span></span> if (pShare > 0) {</span></span> bool merged = false;</span></span> for (uint256 nx = 0; nx < nextCount; nx++) {</span></span> if (nextIds[nx] == cid2 && nextContracts[nx] == childContract) {</span></span> nextAmts[nx] += pShare;</span></span> if (nextDepth > nextDepths[nx]) {</span></span> nextDepths[nx] = nextDepth;</span></span> }</span></span> merged = true;</span></span> break;</span></span> }</span></span> }</span></span> if (!merged) {</span></span> nextContracts[nextCount] = childContract;</span></span> nextIds[nextCount] = cid2;</span></span> nextAmts[nextCount] = pShare;</span></span> nextDepths[nextCount] = nextDepth;</span></span> nextCount++;</span></span> }</span></span> }</span></span> }</span></span> }</span></span> processedContracts[processedCount] = curContract;</span></span> processed[processedCount++] = curId;</span></span> }</span></span> for (uint256 k = 0; k < nextCount; k++) {</span></span> curContracts[k] = nextContracts[k];</span></span> curIds[k] = nextIds[k];</span></span> curAmts[k] = nextAmts[k];</span></span> curDepths[k] = nextDepths[k];</span></span> }</span></span> curCount = nextCount;</span></span> }</span></span> return _shrink(staged, count);</span></span> }</span></span> function _splitRoyalty(uint256 totalRate, uint256 salePrice, bool canPropagate)</span></span> internal</span></span> pure</span></span> returns (uint256 netPrimary, uint256 forwardedAmount)</span></span> {</span></span> if (totalRate == 0) {</span></span> return (0, 0);</span></span> }</span></span> if (!canPropagate) {</span></span> if (salePrice == 0) {</span></span> return (totalRate, 0);</span></span> }</span></span> return ((salePrice * totalRate) / 10_000, 0);</span></span> }</span></span> if (salePrice == 0) {</span></span> if (totalRate <= REFERRED_ROYALTY_FRACTION) {</span></span> return (0, totalRate);</span></span> }</span></span> return (totalRate - REFERRED_ROYALTY_FRACTION, REFERRED_ROYALTY_FRACTION);</span></span> }</span></span> uint256 gross = (salePrice * totalRate) / 10_000;</span></span> uint256 forwarded = (salePrice * REFERRED_ROYALTY_FRACTION) / 10_000;</span></span> if (forwarded > gross) {</span></span> forwarded = gross;</span></span> }</span></span> return (gross > forwarded ? gross - forwarded : 0, forwarded);</span></span> }</span></span> function _sumShares(ReferenceRoyalty memory config) internal pure returns (uint256 total) {</span></span> for (uint256 i = 0; i < config.royaltyInfos.length; i++) {</span></span> total += config.royaltyInfos[i].royaltyAmount;</span></span> }</span></span> }</span></span> function _collectReferring(</span></span> IERC_5521 rNFT,</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address[] memory childContracts,</span></span> uint256[] memory childIds</span></span> ) internal view returns (uint256 childCount) {</span></span> (address[] memory refContracts, uint256[][] memory refTokenIds) =</span></span> rNFT.referringOf(rNFTContract, tokenId);</span></span> uint256 maxChildren = childIds.length;</span></span> uint256 listLen = refContracts.length;</span></span> if (refTokenIds.length < listLen) {</span></span> listLen = refTokenIds.length;</span></span> }</span></span> for (uint256 i = 0; i < listLen && childCount < maxChildren; i++) {</span></span> uint256[] memory ids = refTokenIds[i];</span></span> for (uint256 j = 0; j < ids.length && childCount < maxChildren; j++) {</span></span> childContracts[childCount] = refContracts[i];</span></span> childIds[childCount] = ids[j];</span></span> childCount++;</span></span> }</span></span> }</span></span> }</span></span> function _appendDistribution(</span></span> RoyaltyInfo[] memory staged,</span></span> uint256 count,</span></span> ReferenceRoyalty memory config,</span></span> uint256 amount</span></span> ) internal pure returns (uint256) {</span></span> uint256 len = config.royaltyInfos.length;</span></span> if (len == 0) {</span></span> return count;</span></span> }</span></span> require(count + len <= staged.length, "royalty overflow");</span></span> if (amount == 0) {</span></span> for (uint256 i = 0; i < len; i++) {</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[i].recipient, 0);</span></span> }</span></span> return count;</span></span> }</span></span> uint256 totalShare = _sumShares(config);</span></span> if (totalShare == 0) {</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[0].recipient, amount);</span></span> for (uint256 i = 1; i < len; i++) {</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[i].recipient, 0);</span></span> }</span></span> return count;</span></span> }</span></span> uint256 remaining = amount;</span></span> for (uint256 i = 0; i < len; i++) {</span></span> uint256 share = config.royaltyInfos[i].royaltyAmount;</span></span> if (share == 0) {</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[i].recipient, 0);</span></span> continue;</span></span> }</span></span> uint256 portion = (amount * share) / totalShare;</span></span> if (portion > remaining) {</span></span> portion = remaining;</span></span> }</span></span> remaining -= portion;</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[i].recipient, portion);</span></span> }</span></span> if (remaining > 0) {</span></span> staged[count - 1].royaltyAmount += remaining;</span></span> }</span></span> return count;</span></span> }</span></span> function _shrink(RoyaltyInfo[] memory staged, uint256 count)</span></span> internal</span></span> pure</span></span> returns (RoyaltyInfo[] memory out)</span></span> {</span></span> out = new RoyaltyInfo[](count);</span></span> for (uint256 i = 0; i < count; i++) {</span></span> out[i] = staged[i];</span></span> }</span></span> }</span></span> function recordRoyaltyPayment(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address buyer,</span></span> ReferenceRoyalty memory royalties</span></span> ) external {</span></span> emit ReferenceRoyaltiesPaid(rNFTContract, tokenId, buyer, msg.sender, royalties);</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> setReferenceRoyalty</code> MUST be restricted to authorized roles (e.g., via AccessControl).</li> (Primary Level): The 10% (1000 bps) cap applies to the primary-level configured royaltyFractions. Propagated/reference-level flows are governed separately by REFERRED_ROYALTY_FRACTION and referenceDepth.</li> ceDepth</code> MUST be capped (e.g., ≤ 3) to avoid high gas costs.</li> Ensure non-zero addresses and valid royalty fractions.</li> Ensure supportsInterface forwards properly to parents.</li> Use a per-signer-per-(rNFTContract, tokenId) nonce, and increment after successful verification. Implementations MUST document the chosen scope.</li> rights waived via CC0</a>.</p>
Abstract</h2>
This ERC defines a standard interface for oracle contracts that use multi-agent councils to resolve arbitrary information queries. It enables dApps to request resolutions, general information arbitration, and build consensus and validation in a trust-minimized way, with agents submitting answers to the queries on-chain. The ERC works by a requester opening a query to be resolved. The contract then emits the RequestCreated event with parameters specifying the query, number of infoAgents, commit deadline, and reward/bond amounts, specifications, and capabilities required. A commit phase is initiated where InfoAgents can participate by staking the required bond and submitting a hash of the answer to the query as a commit. After the quorum of infoAgents have committed, the reveal process is initiated where infoAgents post the key to the commit hash. A judgeAgent is then selected to review the committed hash and answers provided by the infoAgents. The judgeAgent then selects the infoAgents which answered the query correctly and the reward is divided among the winners. The infoAgents which answered incorrectly lose their bond. The interface supports permissionless participation, bond-based incentives, and optional extensions for reputation, disputes, and callbacks, making it suitable for applications like semantic data oracles and prediction markets.</p>
Motivation</h2>
With AI agents advancing rapidly, we can build trust-minimized oracles that are cheaper, faster, and more scalable than traditional human or node-based systems. Traditional data oracles primarily provide quantitative feeds and are often centralized or expensive for arbitrary, one-off queries. With AI agents becoming reliable for factual resolutions from public sources, this EIP standardizes an interface for agent councils to handle query resolution via commit-reveal-judging flows, fostering interoperability across implementations. It is generalizable for discrete (defined options) or open-ended queries, with hooks for collusion deterrence and verification. Integration with reputation systems (such as that in ERC-8004</a>) is recommended but optional to keep the core lightweight.</p>
This is generalizable for any resolvable information, making it useful for both qualitative and quantitative data. Existing examples we see this standard being useful for are, tracing information tasks (off-chain data processing with on-chain validation hooks), resolving prediction markets, and creating verified info feeds for DeFi platforms (aggregating real-time semantic data from multiple sources).</p>
We envision an information market evolving where agents compete to answer queries, exchanging data resolutions for tokenized incentives.</p>
Specification</h2>
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.</p>
This EIP proposes the IAgentCouncilOracle</code> interface, which defines methods and events for a council-based resolution flow. Implementations MUST support the core flow: request creation, agent commitment, reveal, judging/aggregation, and reward distribution. An OPTIONAL dispute resolution extension is also included. Off-chain processing (LLM inference and analysis) is handled by agents, with on-chain elements opened to coordination and verification of information.</p>
The council consists of two agent roles: Info Agents (who submit individual information) and Judge Agents (who aggregate and resolve consensus). We make this distinction to clarify how responsibilities from this standard are assigned.</p>
Main Types</h3>
   //</span> Struct for query requests</span></span>
    struct</span> AgentCapabilities</span> {</span></span>
        string</span>[</span>]</span> capabilities</span>;</span> //</span> text, vision, audio etc</span></span>
        string</span>[</span>]</span> domains</span>;</span> //</span> Expertise areas</span></span>
    }</span></span>
</span>
    struct</span> Request</span> {</span></span>
        address</span> requester</span>;</span></span>
        uint256</span> rewardAmount</span>;</span>  //</span> Total reward (native token or ERC-20)</span></span>
        address</span> rewardToken</span>;</span>  //</span> native or ERC-20 token</span></span>
        uint256</span> bondAmount</span>;</span>  //</span> Bond per agent (native token or ERC-20)</span></span>
        address</span> bondToken</span>;</span> //</span> native or ERC-20 token</span></span>
        uint256</span> numInfoAgents</span>;</span>  //</span> Target number of info agents</span></span>
        uint256</span> deadline</span>;</span>  //</span> Unix timestamp for commit phase end</span></span>
        string</span> query</span>;</span>  //</span> The information query</span></span>
        string</span> specifications</span>;</span> //</span> Additional miscellaneous instructions (optional in implementations)</span></span>
        AgentCapabilities requiredCapabilities</span>;</span>  //</span> For filtering agents (optional in implementations)</span></span>
    }</span></span></code></pre>Interface</h3>
interface</span> IAgentCouncilOracle</span> {</span></span>
    //</span> Events for transparency and monitoring</span></span>
    event</span> RequestCreated</span>(</span>uint256</span> indexed</span> requestId</span>, </span>address</span> requester</span>, </span>string</span> query</span>, </span>uint256</span> rewardAmount</span>, </span>uint256</span> numInfoAgents</span>, </span>uint256</span> bondAmount</span>)</span>;</span></span>
    event</span> AgentCommitted</span>(</span>uint256</span> indexed</span> requestId</span>, </span>address</span> agent</span>, </span>bytes32</span> commitment</span>)</span>;</span></span>
    event</span> AgentRevealed</span>(</span>uint256</span> indexed</span> requestId</span>, </span>address</span> agent</span>, </span>bytes</span> answer</span>)</span>;</span>  //</span> Or bytes for flexibility</span></span>
    event</span> JudgeSelected</span>(</span>uint256</span> indexed</span> requestId</span>, </span>address</span> judge</span>)</span>;</span></span>
    event</span> ResolutionFinalized</span>(</span>uint256</span> indexed</span> requestId</span>, </span>bytes</span> finalAnswer</span>)</span>;</span>  //</span> Or bytes</span></span>
    event</span> RewardsDistributed</span>(</span>uint256</span> indexed</span> requestId</span>, </span>address</span>[</span>]</span> winners</span>, </span>uint256</span>[</span>]</span> amounts</span>)</span>;</span></span>
    event</span> ResolutionFailed</span>(</span>uint256</span> indexed</span> requestId</span>, </span>string</span> reason</span>)</span>;</span></span>
    event</span> DisputeInitiated</span>(</span>uint256</span> indexed</span> requestId</span>, </span>address</span> disputer</span>, </span>string</span> reason</span>)</span>;</span></span>
    event</span> DisputeWindowOpened</span>(</span>uint256</span> indexed</span> requestId</span>, </span>uint256</span> endTimestamp</span>)</span>;</span></span>
    event</span> DisputeResolved</span>(</span>uint256</span> indexed</span> requestId</span>, </span>bool</span> overturned</span>, </span>bytes</span> finalAnswer</span>)</span>;</span></span>
    </span></span>
</span>
    //</span> Core methods</span></span>
    function</span> createRequest</span>(</span>string</span> calldata</span> query</span>,</span> uint256</span> numInfoAgents</span>,</span> uint256</span> rewardAmount</span>,</span> uint256</span> bondAmount</span>,</span> uint256</span> deadline</span>,</span> address</span> rewardToken</span>,</span> address</span> bondToken</span>,</span> string</span> calldata</span> specifications</span>,</span> AgentCapabilities</span> calldata</span> requiredCapabilities</span>)</span> external</span> payable</span> returns</span> (</span>uint256</span> requestId</span>)</span>;</span></span>
    //</span> Commit: Permissionless, with bond</span></span>
    function</span> commit</span>(</span>uint256</span> requestId</span>,</span> bytes32</span> commitment</span>)</span> external</span> payable</span>;</span></span>
    //</span> Reveal: Submit answer matching commitment</span></span>
    function</span> reveal</span>(</span>uint256</span> requestId</span>,</span> bytes</span> calldata</span> answer</span>,</span> uint256</span> nonce</span>)</span> external</span>;</span></span>
    //</span> Judge/Aggregate: Called by selected judge or automatic for discrete option queries</span></span>
    function</span> aggregate</span>(</span>uint256</span> requestId</span>,</span> bytes</span> calldata</span> finalAnswer</span>,</span> address</span>[</span>]</span> calldata</span> winners</span>,</span> bytes</span> calldata</span> reasoning</span>)</span> external</span>;</span>  //</span> Winners for reward classification</span></span>
    //</span> Distribute: Auto or manual post-aggregation</span></span>
    function</span> distributeRewards</span>(</span>uint256</span> requestId</span>)</span> external</span>;</span></span>
    //</span> Get final resolution</span></span>
    function</span> getResolution</span>(</span>uint256</span> requestId</span>)</span> external</span> view</span> returns</span> (</span>bytes</span> memory</span> finalAnswer</span>,</span> bool</span> finalized</span>)</span>;</span></span>
</span>
    //</span> Optional Dispute Methods</span></span>
    function</span> initiateDispute</span>(</span>uint256</span> requestId</span>,</span> string</span> calldata</span> reason</span>)</span> external</span> payable</span>;</span></span>
    function</span> resolveDispute</span>(</span>uint256</span> requestId</span>,</span> bool</span> overturn</span>,</span> bytes</span> calldata</span> newAnswer</span>,</span> address</span>[</span>]</span> calldata</span> newWinners</span>)</span> external</span>;</span></span>
</span>
    //</span> Getters for oracle flow data</span></span>
    function</span> getRequest</span>(</span>uint256</span> requestId</span>)</span> external</span> view</span> returns</span> (</span>Request</span> memory</span>)</span>;</span></span>
    function</span> getCommits</span>(</span>uint256</span> requestId</span>)</span> external</span> view</span> returns</span> (</span>address</span>[</span>]</span> memory</span> agents</span>,</span> bytes32</span>[</span>]</span> memory</span> commitments</span>)</span>;</span></span>
    function</span> getReveals</span>(</span>uint256</span> requestId</span>)</span> external</span> view</span> returns</span> (</span>address</span>[</span>]</span> memory</span> agents</span>,</span> bytes</span>[</span>]</span> memory</span> answers</span>)</span>;</span></span>
}</span></span></code></pre>
We do not enforce limits on the number or size of items in capabilities, domains, queries, or answers to maintain flexibility for evolving agent ecosystems and models. However, it is RECOMMENDED implementations impose reasonable limits on metrics such as the number of items (ex. max 64), bytes per item (ex. max 64), and/or total encoded bytes (ex. max 8192) to mitigate gas costs and DoS risks. Implementations MUST document any such limits in their code or README and MUST revert with descriptive errors (ex. CapListTooLong) if exceeded. For high-gas environments, implementations SHOULD use off-chain references (such as an IPFS hash on-chain or some external domain) for verbosity, storing only these references in the struct.</p>
Core Flow</h3>
Implementations MUST follow this sequence for interoperability:</p>


Request Creation</strong>: Requester calls createRequest</code>, providing query, params (ex. numInfoAgents</code>, bondAmount</code>), and rewardAmount</code> (with msg.value</code> or ERC-20</a> transfer). If rewardToken == address(0)</code>, this is the native asset and createRequest MUST be payable and expect msg.value to fund the reward (and native bonds if used). If rewardToken != address(0)</code>, it MUST be an ERC-20</a> and implementations SHOULD pull funds via transferFrom</code>. Emits RequestCreated</code>. The bond is a slashable stake an agent put in, and be penalized if the submission turns out to be wrong, malicious etc. The amount and token for the bond (specified with bondAmount</code> and bondToken</code>) is implementation-specific and these MAY be different from the values used for the reward.</p>
</li>

Commit Process</strong>: Permissionless Info Agents call commit</code> with a hash (RECOMMENDED: keccak256(abi.encode(answer, nonce))</code>) and bond. Caps at numInfoAgents</code>. Phase ends at deadline or when all InfoAgents are committed. Emits AgentCommitted</code>.</p>
</li>

Reveal/Collection Process</strong>: Committed Info Agents call reveal</code> to submit answers. MUST match commitment. Emits AgentRevealed</code>. Proceed only if quorum (RECOMMENDED:  >50% reveals) otherwise emit ResolutionFailed</code> and refund. This helps reduce coordination/collusion of submissions as they aren’t revealed early.</p>
</li>

Judging Process</strong>: After reveals, select a Judge Agent (RECOMMENDED: randomly from a separate pool, distinct from Info Agents) and emit JudgeSelected. The Judge Agent calls aggregate to submit the final answer and classify winners (majority agents). For open-ended and discrete queries, the Judge MUST synthesize revealed submissions (semantic consensus via LLM) and provide reasoning as part of the submission. In ties, the Judge MAY provide a tie-breaker with reasoning. Emits ResolutionFinalized</p>
</li>

Reward Distribution Process</strong>: Call distributeRewards</code> to payout correct Info Agents / Judge Agent based on config (proportional or equal splits, with implementation specific params for ratios like Judge fee percentage). Refund bonds to correct Info Agents; forfeit others. Emits RewardsDistributed</code>. Implementations MAY forfeit the Judge Agent’s bond and redistribute to correct Info Agents or proposer if the judge fails to resolve within the allotted window.</p>
</li>
</ol>
Off-chain storage (such as IPFS for reveals/reasoning) MAY be used, with on-chain hashes for verifiability.</p>
Optional Extensions</h3>
Dispute Standard</strong>: Implementations MAY add a dispute mechanism post-finalization.</p>
Suggested flow: After finalization, open a dispute window. Any party MAY call initiateDispute</code> with a disputeBond</code> (ex.  1.5-2x original bond) and on-chain reason (such as  a hash of detailed reasoning, optionally on IPFS), emitting DisputeInitiated</code>. Re-select a Judge (randomly, with higher minReputation threshold). Judge reviews and calls resolveDispute</code> to uphold or overturn, submitting new answers/winners if overturned. If upheld, the disputer’s bond is forfeited to the correct agents and arbitration creator. If overturned, return the disputer's bond, provide reimbursement (ex. a portion of the base fee), slash the original Judge's fee/bond, and redistribute. Dispute Judge receives reimbursement (ex. some fixed/percentage fee). Emits DisputeResolved</code>.</p>
Configurable params: disputeWindow</code> (duration), disputeBond</code>, minDisputeJudgeReputation</code> (higher than original), disputerReimbursement</code>, judgeReimbursement</code>. MAY integrate ERC-8004</a> for re-runs/proofs with validation hooks; partial payouts/escrow during window for efficiency.</p>
Reputation Hooks</strong>: MAY integrate with ERC-8004</a> for filtering (min reputation for agents or judges) or proportional rewards. RECOMMENDED: Set a minimum reputation for Judge Agents, higher than for Info Agents, as they make a final decision. This creates an identifiable on-chain trail for accountability.</p>
Callbacks</strong>: MAY add callback(address target, uint256 requestId)</code> for notifying requester contracts.</p>
ERC-20</a> Rewards</strong>: Extend with token transfers instead of the native token.</p>
Configs (such as phase durations, quorums, reward ratios) are implementation-specific parameters.</p>
Rationale</h2>
This interface standardizes a council flow for AI-driven oracles, balancing minimal on-chain logic with off-chain flexibility. Commit-reveal prevents front-running and judging enables consensus on complex queries. Bonds and optional reputation help deter attacks.</p>
Reputation scores provide a rationale for enhanced security: they enable proportional reward distribution, gating participation to experienced agents, and reducing collusion risks by aligning incentives with proven performance. Without reputation, attack vectors may increase, but the core bond system offers baseline protection and we expect this baseline to allow for a self regulating rewards incentive market that drives agents to act in good faith.</p>
We considered a single-round, plaintext submission model. While simpler and cheaper, it is susceptible to (i) copying attacks where later agents replicate early submissions, (ii) MEV/front-running of plaintext answers, and (iii) coercion/censorship risks when answers must be revealed before full participation. Plain text answers are easily identified and may be delayed, susceptible to being reordered, or unfavorable answers may be censored compromising the integrity of the Info Agents answers. By contrast, a commit-reveal flow keeps content hidden during the commit phase: adversaries cannot cheaply target specific answers.</p>
Weighted voting (a common alternative in oracles like Universal Market Access) was evaluated as a potential replacement for distinct roles where agents could stake bonds or reputation to vote with proportional influence. This could reduce moving parts but weakens explainability and accountability for open-ended queries. Instead, a Judge allows for semantic interpretation of answers. Our role-based approach mitigates this by random Judge selection and optional reputation thresholds, promoting broader participation while maintaining checks (Judge Agents can tie-break with reasoning). This also aligns better with AI agent ecosystems, where specialized agents mirror real-world councils or juries, fostering an "information market".</em> A lack of a Judge Agent would limit the ERC to only discrete information and make it unclear how non-discrete data is resolved. We standardize the Info/Judge split for the core flow (specialization + reasoning from the Judge), while leaving weighted aggregation as an OPTIONAL extension</strong> for discrete queries.</p>
Using a single agent reduces complexity but mixes retrieval/synthesis with adjudication. We determined that explicit role separation enables (a) different capability/reputation thresholds, (b) clearer slashing semantics for adjudication failures, and (c) better human-auditable reasoning trails. We intentionally separate roles for specialization and explainability.</p>
The commit-reveal process is more gas-intensive (requiring two transactions per Info Agent: commit and reveal) but provides increased security through ease of verifiability and reduced attack surfaces like front-running. The increased gas is offset by preventing costly disputes from copied or manipulated answers. Other existing commit-reveal mechanisms were considered but were too constrained for our resolution flow and would have increased complexity. For example, ERC-5732</a> does not provide a built-in reveal mechanism. The reveal is a critical step in the agent council flow to ensure quorum and prevent collusion. The ERC-162</a> commit and reveal process was also considered but is not easily applicable to text fields and resolution flow here.</p>
Longer form responses written directly to the blockchain may be gas-prohibitive for complex queries so off-chain storage like IPFS for larger reveals/reasoning is recommended, with on-chain hashes for integrity. This trades some security (IPFS links are not permanent and could be censored) for cost savings, but implementations can mitigate this via decentralized pinning services or agent domains from ERC-8004</a>. Creating different schemes for off-chain verifiability significantly increases complexity. To enhance usability, our core interface keeps methods lightweight, and optional extensions like disputes remain modular, allowing simple implementations for low-stakes queries while scaling to high-security ones.</p>
This ERC is meant to be complimentary to recent standards like ERC-8004</a>, which provides a foundational step toward enabling agent-to-agent communication. Features like Identity, Reputation, and Validation can strengthen the verifiability and fidelity of answers from Info Agents and rulings from Judge Agents. For instance, implementations can filter participants via ERC-8004</a>'s reputation scores (minReputation params for agents). They can also use validation hooks to verify off-chain computations cryptographically, reducing reliance on bonds alone. The framework for Agent Council Oracles differs significantly. It focuses on a standard mechanism for agents to reach consensus without human input, emphasizing on-chain coordination flows (commit-reveal-judge) for query resolution.</strong> While ERC-8004</a> is geared toward trustless agent interoperability and off-chain logic, our EIP builds atop it by standardizing automated information arbitration. This can apply to specific use cases such as data oracles or prediction markets. The integration with ERC-8004</a> is optional to keep the core lightweight, but recommended for high-stakes scenarios. Other differentiators unique to our standard include our bond incentives and dispute windows, which add economic security layers otherwise absent in multi-agent coordination layers.</p>
Backwards Compatibility</h2>
No conflicts with existing standards.</p>
Security Considerations</h2>

Collusion: Mitigated by bonds (refundable for honest participation, forfeited for failures), random judge selection, and optional reputation. Bonds disincentivize spam and non-reveals by redistributing to participants.</li>
Spam: Prevented by bonds and caps.</li>
Failures: Refunds for low participation or abandonment.</li>
Disputes: Optional for high-stakes, with higher stakes/thresholds.</li>
Fairness of random selection of Judge relies on the crypto strength of randomness
Implementations should audit for reentrancy and use verifiable randomness.</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Multi-step Contract Ownership
2025-09-16T00:00:00+00:00
Abstract</h2>
We define a multi-stepped contract ownership interface for more secure contract ownership management. This makes the ownership transfer into 3 distinct steps. With the first 2 steps, performed by the original owner (initiate → confirm) and the remaining 1 step performed by the new owner (accept).</p>
We enforce an optional time window between the initiate and confirm stages to give additional room for review, and make ownership key compromise scenarios less fatal.</p>
Motivation</h2>
Ownership management is crucial in on-chain security and a significant portion of the security assumptions of defi protocols, smart contract wallets and on-chain utilities rely on the contract ownership.</p>
The single-step transferOwnership()</code> style ownership mechanism has been in the industry for a long time, (e.g.,ERC-173</a>), and has been used ubiquitously as an industry standard. As the industry evolves and attacks get more sophisticated there is a strong need for a multi-step, time gated ownership management process to enhance the ecosystem’s contract ownership to be more reviewable, stoppable, thorough and secure.</p>
The main objective of this standard is to make ownership more secure and handled in a multi-stepped approach that enables the operation to be conducted with more caution and lesser operational mistakes, while being immune to potential scam attacks.</p>
Key factors taken into consideration for the standard:</p>

Reduce probability of operational mistakes.</li>
Foster on-chain reviewal practice for ownership transfer.</li>
Ability to rollback ownership transfer, during the transfer process.</li>
Simplicity.</li>
</ol>
1. Reduce probability of operational mistakes:</strong> The standard makes the ownership transfer stage into 3 different clear steps. Initiation → Confirmation → Acceptance. The owner will have the enforced ability to review the newOwner address secured by the pre-set buffer time. Also to reduce any operational mistakes or possible scams (e.g., address poisoning) the address is required as the parameter in each Initiation & Confirmation stage.</p>
2. Foster on-chain reviewal practice for ownership transfer:</strong> We not only targets this as a contract interface and implementation methodology, but also hopes to foster an ecosystem-level awareness and security practice to thoroughly review, confirm the ownership transfer. The standard helps operators of Smart Contract to review newOwner address on-chain, and further confirm again if the address is indeed correct.</p>
3. Ability to rollback ownership transfer, during the transfer process:</strong> Whether through an operational mistake or private key leak of owner account, or other reasons, the ability to rollback ownership transfer within the time buffer highly increases the security and operational burden.</p>
Even in the extreme case of owner private key leak, if the buffer time is set enough, the original owner can earn time to evacuate the funds from the protocol, and possibly prohibit ownership transfer through DoS of ownership (attack → initiate , original owner(defender) → re initiate. which will reset the time back to 0).</p>
4. Simplicity:</strong> MultistepOwnable</code> is targeted to be a simple contract given the diverse use cases and scenarios it could be applied. The process for ownership transfer is concise but thorough enough to allow owners review each step. This is the rationale behind making the ownership transfer time buffer and buffer time update capability optional.</p>
Specification</h2>
The keywords "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.</p>
A multi-step ownable contract MUST implement the following interface:</p>
///</span> @title</span> Multistep Ownership Standard</span></span>
interface</span> MultiStepOwnable</span> {</span></span>
</span>
	event</span> OwnershipTransferInitiated</span>(</span>address</span> indexed</span> prevOwner</span>, </span>address</span> indexed</span> newOwner</span>)</span>;</span>	</span></span>
	event</span> OwnershipTransferConfirmed</span>(</span>address</span> indexed</span> prevOwner</span>, </span>address</span> indexed</span> newOwner</span>)</span>;</span></span>
	event</span> OwnershipTransferred</span>(</span>address</span> indexed</span> prevOwner</span>, </span>address</span> indexed</span> newOwner</span>)</span>;</span></span>
</span>
	///</span> @dev</span> initiate the ownership transfer. First step of ownership transfer.</span></span>
	///</span> moves the newOwner to the preConfirmed stage.</span></span>
	///</span> </span></span>
	///</span> @param</span> newOwner</span> the address of the new owner of the contract.</span></span>
	///</span> stored as preConfirmedOwner.</span></span>
	function</span> initiateOwnershipTransfer</span>(</span>address</span> newOwner</span>)</span> external</span>;</span></span>
	</span></span>
	///</span> @dev</span> confirm the ownership transfer. Second step of ownership transfer.</span></span>
	///</span> confirmation can only be done after the transfer-buffer period from initiation.</span></span>
	///</span> newOwner should match with the initiation step's newOwner.</span></span>
	///</span> To initiate ownership transfer to a different newOwner, initiation step should be re-conducted.</span></span>
	///</span></span>
	///</span> @param</span> newOwner</span> the address of the new owner of the contract.</span></span>
	///</span> stored as pendingOwner.</span></span>
	function</span> confirmOwnershipTransfer</span>(</span>address</span> newOwner</span>)</span> external</span>;</span></span>
	</span></span>
	///</span> @dev</span> cancels the pending ownership transfer. Before the final step of ownership transfer (acceptOwnershipTransfer()).</span></span>
	///</span> This function should wipe out the pendingOwner.</span></span>
	///</span> By calling this function, ownership transfer process is canceled and should be reinitiated from initiateOwnershipTransfer().</span></span>
	function</span> cancelPendingOwnershipTransfer</span>(</span>)</span> external</span>;</span></span>
</span>
	///</span> @dev</span> accepts the ownership transfer. Final step of ownership transfer.</span></span>
	///</span> This function can only be called by the newOwner that was confirmed in step 2.</span></span>
	///</span> The contract should perform access control e.g.,</span></span>
	///</span> msg.sender == pendingOwner()</span></span>
	function</span> acceptOwnershipTransfer</span>(</span>)</span> external</span>;</span></span>
	</span></span>
	///</span> @notice</span> only the address returned by owner() has authority as the owner.</span></span>
	///</span> pendingOwner() and preConfirmedOwner() should not possess any</span></span>
	///</span> authority/access/right.</span></span>
	///</span> @dev</span> returns the owner of the contract</span></span>
	function</span> owner</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
	</span></span>
	///</span> @dev</span> returns the pending owner of the account.</span></span>
	///</span> pending owner should not have any authority/access/right.</span></span>
	function</span> pendingOwner</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
	</span></span>
	///</span> @dev</span> returns the pre-confirmed owner of the account.</span></span>
	///</span> pre-confirmed owner should not have any authority/access/right.</span></span>
	function</span> preConfirmedOwner</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
	</span></span>
	///</span> @dev</span> returns the ownership transfer buffer time (in seconds).</span></span>
	///</span> the buffer is enforced between initiation <> confirmation of ownership transfer. </span></span>
	///</span> the standard does not enforce the value range. it is highly recommended to be between 2 <> 14 days.</span></span>
	function</span> getOwnershipTransferBuffer</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
}</span></span></code></pre>
The MultiStepOwnable</code> contract MAY implement the UpdateableOwnershipTransferBuffer</code> interface to enable buffer period modification.</p>
The contract MUST update the buffer period with a 2 step approach of initiation (initiateOwnershipBufferUpdate()</code>) and then confirmation (confirmOwnershipBufferUpdate()</code>) after the existing buffer period. The buffer period should be enforced between these 2 function calls.
If this behavior is not enforced, the security of ownershipTransferBuffer</code> could break during owner key compromise scenario.</p>
///</span> @title</span> UpdateableOwnershipTransferBuffer. Extension of MultiStepOwnable.</span></span>
interface</span> UpdateableOwnershipTransferBuffer</span> {</span></span>
</span>
	///</span> @dev</span> initiates the update of ownership transfer time buffer.</span></span>
	function</span> initiateOwnershipBufferUpdate</span>(</span>uint256</span> newBuffer</span>)</span> external</span>;</span></span>
	</span></span>
	///</span> @dev</span> confirms the update of ownership transfer time buffer.</span></span>
	///</span> confirmation SHOULD revert if existing time buffer did not pass since</span></span>
	///</span> initiation of ownership transfer time buffer.</span></span>
	function</span> confirmOwnershipBufferUpdate</span>(</span>uint256</span> newBuffer</span>)</span> external</span>;</span></span>
}</span></span></code></pre>Rationale</h2>


A time buffer for ownership transfer is introduced to foster a process of reviewing the new owner address on-chain. However, this remains an optional behavior to allow flexibility in ownership management. Removing the optional time buffer would be similar to the implementation of Ownable2Step</code> with an additional step for confirmation.</p>
</li>

Enforcing a time buffer to update the ownership transfer time buffer is crucial for maintaining the security of the MultiStepOwnable</code> contract. When the owner key is compromised, this allows the original owner of the account to be able to DoS and prohibit the ownership transfer to the malicious entity when the ownership transfer buffer is sufficiently long enough.</p>
</li>

For compatibility with existing ownership mechanisms, the standard is designed to be compatible with the existing ownership mechanism for fetching the owner through owner()</code>.</p>
</li>
</ol>
Backwards Compatibility</h2>
TBD </p>
Security Considerations</h2>

Only owner should be available to call initiateOwnershipTransfer()</code> & confirmOwnershipTransfer()</code> & cancelPendingOwnershipTransfer()</code>.</li>
OwnershipTransferBuffer</code> should be set together when owner is set. e.g., constructor()</code>, initialize()</code>.</li>
If OwnershipTransferBuffer</code> is set, it should be strictly enforced between initiation and confirmation.</li>
Before the new owner performs acceptOwnership()</code>, the original, existing owner should still hold all rights as the owner. Because the owner is still unchanged.</li>
</ol>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Minimal Wallet-Managed Auto-Login for SIWE
2025-09-02T00:00:00+00:00
Abstract</h2>
Defines a wallet-local allowlist for automatic signing of ERC-4361</a> messages when simple, deterministic match rules succeed. Policies are created and managed only by the wallet/user.</p>
Motivation</h2>
Users repeatedly sign identical Sign-In With Ethereum (SIWE) messages for trusted apps. A small, explicit match policy enables zero-prompt login without involving apps.</p>
Users already get prompted by their wallets if they trust a certain app when they initially connect to it - this flow can also authorize auto-login if applicable.</p>
Specification</h2>
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.</p>
The term “wallet” refers to wallet user interfaces, regardless of whether mobile, web-based or browser extensions.</p>
Overview</h3>
Each allow-policy is defined as:</p>
{</span></span>
  "</span>domain</span>"</span>: </span>"</span>example.com</span>"</span>,</span>                  //</span> exact match to SIWE domain</span></span>
  "</span>uriPrefix</span>"</span>: </span>"</span>https://example.com/</span>"</span>,</span>      //</span> SIWE URI MUST start with this</span></span>
  "</span>allowedChains</span>"</span>:</span> [</span>1</span>]</span>,</span>                     //</span> list of allowed chainIds</span></span>
  "</span>allowedResources</span>"</span>:</span> [</span>"</span>https://example.com/login</span>"</span>]</span>,</span> //</span> exact set match</span></span>
  "</span>supportsEIP6492</span>"</span>: </span>true</span>,</span>                   //</span> required for smooth UX when using hardware wallets</span></span>
  "</span>expiresAt</span>"</span>: </span>1700000000000</span> //</span> UNIX timestamp when this policy expires, or 0 for no expiry</span></span>
}</span></span></code></pre>Auto-sign rule</h3>
Given a parsed ERC-4361</a> message M</code>, the wallet MAY</strong> auto-sign if</strong>:</p>

M.domain == policy.domain</code></li>
M.uri</code> startsWith</strong> policy.uriPrefix</code></li>
If M.chainId present: M.chainId</code> is in policy.allowedChains</code></li>
If policy.allowedResources non-empty:
the set of M.resources</code> is a subset of policy.allowedResources</code> (order does not matter); otherwise no resources will be allowed at all</li>
If policy.expiresAt</code> is non-zero, the current time is less than policy.expiresAt</code></li>
</ol>
All other SIWE validations (nonce uniqueness, time validity, signature domain binding) remain as per ERC-4361</a> and MUST be enforced by the wallet.</p>
Management of policies</h3>
Policies are created, listed, updated, and deleted only</strong> within the wallet UI - wallets decide how much control they want to give to users over this.</p>
It’s recommended that each wallet:</p>

includes a default list of policies for popular apps</li>
automatically creates policies for apps that it considers safe, after the first SIWE signature, with user consent - this implies a different flow where, upon receiving the SIWE message sign request, the wallet will not go through the regular message signing flow, but prompt the user “App X wants to log-in with your account” with a checkbox to “Automatically sign into  in the future”</li>
</ul>
There’s no app-provided hints or headers that influence policy creation.</p>
Hardware wallet compatibility and ERC-6492</a></h3>
Auto-signing is not viable with hardware wallet accounts, as the user will be prompted without context or expectation to sign the login message.</p>
This is why we include the supportsEIP6492</code> property. If it is set to false</code>, the wallet MUST not auto-login if the account's primary signer is a hardware wallet, as the app has no way of verifying a smart contract signature.</p>
However, if it's set to true</code>, the wallet MAY perform auto-login as long as 1) it can enable EIP-7702</a> on the account OR the account is a smart account 2) it can authorize a limited-scope session key or delegation just for the auto-login. If said conditions are met, the wallet MAY generate a login signature without prompting the user on their hardware device. That said, enabling EIP-7702 and the session key/delegation will require prompting the user, so it's up to the wallet to walk the user through it. The exact mechanism of how wallets should manage the session key/delegation is out of scope of this ERC, but ERC-7710</a> may be used.</p>
RPC method</h3>
Wallets MAY implement an RPC method, wallet_getCurrentAutoLoginPolicy</code>, which has no parameters and returns an object describing the current policy for the calling app.</p>
{</span></span>
  //</span> the object that describes the active policy, or null</span></span>
  "</span>activePolicy</span>"</span>:</span> {</span></span>
    "</span>domain</span>"</span>:</span> "</span>example.com</span>"</span>,</span></span>
    "</span>uriPrefix</span>"</span>:</span> "</span>https://example.com/</span>"</span>,</span></span>
    "</span>allowedChains</span>"</span>:</span> [</span>1</span>]</span>,</span></span>
    "</span>allowedResources</span>"</span>:</span> [</span>"</span>https://example.com/login</span>"</span>]</span>,</span></span>
    "</span>supportsEIP6492</span>"</span>:</span> true</span>,</span></span>
    "</span>expiresAt</span>"</span>:</span> 1700000000000</span></span>
  }</span>,</span></span>
}</span></span></code></pre>
The response of this method allows apps to determine whether they can self-initiate login requests without user interaction.</p>
If this ERC is disabled in the wallet, or there is no active policy for the calling app, the wallet MUST return null</code> for activePolicy</code>.</p>
It's recommended that the wallet returns null</code> if the policy has expired or the app is connected on a non-allowed chain.</p>
Rationale</h2>

This ERC is designed with minimal modifications to existing apps in mind</li>
From a security perspective, it's much easier to "outsource" the job of determining which apps to enable to this policy for to wallets - most wallets already maintain lists of "trusted" apps</li>
EIP-712</a> (typed data) is out of scope due to SIWE deciding to build on plain text.</li>
</ul>
Backwards Compatibility</h2>
Backwards compatibility is one of the main goals of this ERC, and it requires no changes to existing apps, building upon ERC-4361</a> as-is.</p>
To fully take advantage of this ERC, apps need to self-initiate the login request rather than expecting users to press a log-in button (using wallet_getCurrentAutoLoginPolicy</code>).</p>
Reference Implementation</h2>
function</span> shouldAutoSign</span>(</span>M</span>,</span> P</span>)</span> {</span></span>
  if</span> (</span>M</span>.</span>domain</span> !==</span> P</span>.</span>domain</span>)</span> return</span> false</span>;</span></span>
  if</span> (</span>!</span>M</span>.</span>uri</span>.</span>startsWith</span>(</span>P</span>.</span>uriPrefix</span>)</span>)</span> return</span> false</span>;</span></span>
  if</span> (</span>!</span>P</span>.</span>allowedChains</span>.</span>includes</span>(</span>M</span>.</span>chainId</span>)</span>)</span> return</span> false</span>;</span></span>
  if</span> (</span>M</span>.</span>resources</span>)</span> {</span></span>
    const</span> allowList</span> =</span> P</span>.</span>allowedResources</span> ||</span> [</span>]</span></span>
    if</span> (</span>!</span>M</span>.</span>resources</span>.</span>every</span>(</span>resource</span> =></span> allowList</span>.</span>includes</span>(</span>resource</span>)</span>)</span>)</span> return</span> false</span>;</span></span>
  }</span></span>
  if</span> (</span>P</span>.</span>expiresAt</span> !==</span> 0</span> &&</span> Date</span>.</span>now</span>(</span>)</span> >=</span> P</span>.</span>expiresAt</span>)</span> return</span> false</span>;</span></span>
  //</span> Also enforce standard SIWE validations here.</span></span>
  return</span> true</span>;</span></span>
}</span></span></code></pre>Security Considerations</h2>

It’s recommended for Auto login to be OFF by default on wallets’ UIs so that users can explicitly toggle ON for websites they trust.</li>
Managing policies it out of scope of this ERC, as most wallets already manage trusted app lists - however, the recommended best practice is to:

Include a default list of policies for popular apps</li>
Auto-create policies for other apps if the user consents to it</li>
</ul>
</li>
Standard SIWE checks (fresh nonce, correct domain binding, time validity) should still be enforced.</li>
uriPrefix</code> should be kept specific (e.g., /login</code>) to avoid over-broad matches.</li>
It's recommended to include a top-level setting in each wallet that can disable this ERC.</li>
Always match M.domain</code> against the top-level origin of each app, to avoid auto-login working in iframes that are included in a malicious top-level origin.</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Payout Race
2025-08-31T00:00:00+00:00
Abstract</h2>
This ERC specifies a small contract surface for a "payout race": a bucket that holds a single payout asset type and transfers the entire bucket to a recipient when a caller pays a fixed required payment</strong> in a configured desired payment asset. The desired payment asset can be ETH or one ERC-20</a>. The payout asset can be ETH or one ERC-20.</p>
This ERC is inspired by the Uniswap Foundation's Unistaker</strong> proposal, which introduced the term Payout Race</strong> and motivated this design.</p>
Motivation</h2>
Many protocols need an ongoing way to convert a continuous stream of value into another asset at or near prevailing market prices. Typical cases include buying back a protocol token using protocol revenue, accumulating a reserve asset, funding incentive budgets, or rebalancing treasuries. Existing patterns have material drawbacks. Integrating an AMM couples outcomes to external liquidity, slippage, and fees, and requires retuning when pool conditions change. General on-chain auctions add operational complexity and higher gas, especially when run continuously.</p>
This ERC defines a deterministic, revenue-driven primitive that is analogous to a Dutch auction. Sources of value flow into this contract, filling a "bucket" of purchasable assets. The first caller that supplies the required payment in the desired payment asset receives the entire current balance of the payout token in the bucket. The interface is small, auditable, and easy to compose with upstream controllers that decide when the exchange is economically sound.</p>
Specification</h2>
The following interface and rules are normative. 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.</p>
Definitions</h3>


Conforming contract</strong>: Any smart contract that exposes this interface and claims compliance with this ERC. This includes proxies and clones. Requirements in this document apply to the observable runtime behavior of the deployed contract.</p>
</li>

Payout asset</strong>: Asset dispensed from the bucket. payoutAsset == address(0)</code> means ETH payout.</p>
</li>

Desired payment asset</strong>: Asset the buyer must pay. Referred to as desiredAsset</code> in the interface. desiredAsset == address(0)</code> means ETH payment.</p>
</li>

Required payment</strong>: Fixed amount of the desired payment asset (desiredAsset</code>) or ETH that must be provided by the buyer to trigger the payout.</p>
</li>
</ul>
Interface</h3>
//</span> SPDX-License-Identifier: CC0-1.0</span></span>
pragma</span> solidity</span> ^0.8.24</span>;</span></span>
</span>
interface</span> IPayoutRace</span> {</span></span>
    ///</span> @notice</span> Payout asset. address(0) means ETH payout.</span></span>
    function</span> payoutAsset</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Desired payment asset. address(0) means ETH payment.</span></span>
    function</span> desiredAsset</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Fixed amount required to win the race, denominated in the desired payment asset.</span></span>
    function</span> requiredPayment</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Destination that receives the buyer's payment.</span></span>
    function</span> paymentSink</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Pay the required amount and receive the entire current balance of the payout token to `to`.</span></span>
    ///</span> @dev</span> Reverts if the computed dispensed amount is zero. Must be safe against reentrancy.</span></span>
    ///</span> @return</span> dispensed</span> The amount of payout token transferred to `to`.</span></span>
    function</span> purchase</span>(</span>address</span> to</span>)</span> external</span> payable</span> returns</span> (</span>uint256</span> dispensed</span>)</span>;</span></span>
</span>
    //</span> Admin surface.</span></span>
    function</span> setRequiredPayment</span>(</span>uint256</span> amount</span>)</span> external</span>;</span></span>
    function</span> setPaymentSink</span>(</span>address</span> sink</span>)</span> external</span>;</span></span>
</span>
    //</span> Events</span></span>
    event</span> Purchased</span>(</span>address</span> indexed</span> buyer</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> dispensed</span>, </span>uint256</span> paid</span>)</span>;</span></span>
    event</span> PaymentConfigUpdated</span>(</span>address</span> desiredAsset</span>, </span>uint256</span> requiredPayment</span>, </span>address</span> sink</span>)</span>;</span></span>
}</span></span></code></pre>Required Behavior</h3>


Exact required payment.</strong> Callers MUST</strong> provide exactly requiredPayment()</code> in the configured desiredAsset</code> or in ETH to call purchase</code>.</p>
</li>

Token pairing.</strong> payoutAsset</code> and desiredAsset</code> MUST NOT</strong> both be address(0)</code>. ETH on both sides is disallowed.</p>
</li>

Desired payment asset immutability.</strong> desiredAsset</code> MUST NOT</strong> change after initialization. A conforming contract MUST NOT</strong> expose any callable setter that can change desiredAsset</code>.</p>
</li>

Payout asset immutability.</strong> payoutAsset</code> MUST NOT</strong> change after initialization. A conforming contract MUST NOT</strong> expose any callable setter that can change payoutAsset</code>.</p>
</li>

All-or-nothing dispense.</strong> On purchase</code>, a conforming contract MUST compute the amount to dispense as the live balance of the payout token captured at function entry, before any external calls. The contract MUST transfer exactly this amount to to</code> in a single call and the call MUST revert if this amount is zero.</p>
</li>

Payment collection.</strong></p>

If desiredAsset == address(0)</code>, purchase</code> MUST</strong> require msg.value == requiredPayment()</code> and MUST</strong> forward that ETH to paymentSink()</code>.</li>
If desiredAsset != address(0)</code>, purchase</code> MUST</strong> require msg.value == 0</code> and MUST</strong> call transferFrom(msg.sender, paymentSink(), requiredPayment())</code> on desiredAsset</code>.</li>
</ul>
</li>

Admin changes.</strong> A conforming contract MUST</strong> restrict the admin setters to an authorized role and MUST</strong> emit PaymentConfigUpdated</code> when requiredPayment</code> or paymentSink</code> change.</p>
</li>
</ol>
Optional Extensions</h3>

Permit for payment</strong>: A conforming contract MAY</strong> expose purchaseWithPermit(...)</code> that accepts EIP-2612</a> permit parameters. If implemented, the function MUST</strong> require desiredAsset != address(0)</code>, MUST</strong> call permit</code> on desiredAsset</code> with the supplied signature, and MUST</strong> collect requiredPayment</code> via transferFrom</code> in the same transaction. The call MUST</strong> revert if desiredAsset</code> does not implement EIP-2612 or if the permit does not yield sufficient allowance.</li>
Rescue for unintended assets</strong>: A conforming contract MAY</strong> implement an admin-only rescue</code> function to recover assets that are not the payoutAsset</code> (e.g., unsolicited ERC-20s or ETH sent when payoutAsset</code> is an ERC-20). If provided, the function MUST NOT</strong> transfer the payoutAsset</code>, MUST</strong> emit a Rescued(address token, address to, uint256 amount)</code> event, and MUST</strong> be restricted to an authorized role.</li>
</ul>
Rationale</h2>

A single required payment pairs well with controllers that evaluate when the exchange is economically sound and trigger purchase</code> only when conditions justify it. The onchain primitive then validates the payment and atomically transfers the entire bucket.</li>
paymentSink</code> reduces persistent balances in the contract and simplifies audits. Sinks can be treasuries, splitters, or burns.</li>
Using the live onchain balance as the source of truth automatically captures rebases and fee-on-transfer mechanics, and keeps the onchain tracking minimized. It also implies that unsolicited transfers to the contract will be included in the next payout, which purchasers may want to account for at the integration level.</li>
</ul>
Admin Considerations</h3>
Access control for admin setters is intentionally unspecified; EIP-173</a> ownership or a role-based pattern is recommended.</p>
Some deployments may renounce or restrict admin rights for policy or compliance reasons (for example, renouncing ownership or disabling roles). This ERC does not prescribe any specific mechanism.</p>
The reference uses EIP-173</a> style ownership for illustration. Any access control that enforces the Required behavior is acceptable. Deployments may assign distinct roles per setter or make one or more parameters immutable. The specification is agnostic to the mechanism.</p>
Parameter Selection and Degenerate Cases</h3>
This mechanism works best when value accrues gradually. Large, lumpy deposits can overshoot the required payment threshold and leak value to the first successful caller. Operators should size requiredPayment</code> relative to observed inflow volatility and adjust conservatively. If the payout asset appreciates against the desired payment asset, purchases may stall. If it depreciates, purchases may trigger so frequently that value is lost whenever a large trade pushes the bucket well above the threshold.</p>
Changing requiredPayment</code> carries risks. Lowering it can leak value at the moment of change if accrued payout already exceeds the new threshold, since searchers can win a bargain. Raising it can disrupt or bankrupt naive searchers and MEV bots that provide rewards by arbitraging fee collection. Mitigations may include timelocked or scheduled parameter changes, announce windows, caps on per-block deposits, cooldowns after changes, and time-weighted average pricing (TWAP)-based or ratcheted adjustments to requiredPayment</code>.</p>
Considered Alternatives: Multi-Asset Sweep</h3>
This design could be extended to support multiple payout assets by maintaining an explicit allowlist and, on a successful purchase</code>, sweeping each allowlisted token to the recipient using the same mechanics as the single-asset case.</p>
Backwards Compatibility</h2>
Compatible with any ERC-20</a>. Wallets and dApps can integrate using standard allowance flows or optional permit</code> helpers.</p>
Reference Implementation</h2>
//</span> SPDX-License-Identifier: CC0-1.0</span></span>
pragma</span> solidity</span> ^0.8.24</span>;</span></span>
</span>
import</span> {</span>IERC20</span>}</span> from</span> "@openzeppelin/contracts/token/ERC20/IERC20.sol"</span>;</span></span>
import</span> {</span>ReentrancyGuard</span>}</span> from</span> "@openzeppelin/contracts/security/ReentrancyGuard.sol"</span>;</span></span>
</span>
contract</span> PayoutRace</span> is</span> ReentrancyGuard</span> {</span></span>
    address</span> public</span> immutable</span> payoutAsset</span>;</span>        //</span> address(0) for ETH payout</span></span>
    address</span> public</span> immutable</span> desiredAsset</span>;</span>       //</span> address(0) for ETH payment</span></span>
    uint256</span> public</span> requiredPayment</span>;</span>              //</span> fixed amount owed by buyer</span></span>
    address</span> public</span> paymentSink</span>;</span></span>
</span>
    address</span> private</span> _owner</span>;</span></span>
</span>
    event</span> Purchased</span>(</span>address</span> indexed</span> buyer</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> dispensed</span>, </span>uint256</span> paid</span>)</span>;</span></span>
    event</span> PaymentConfigUpdated</span>(</span>address</span> desiredAsset</span>, </span>uint256</span> requiredPayment</span>, </span>address</span> sink</span>)</span>;</span></span>
    event</span> OwnershipTransferred</span>(</span>address</span> indexed</span> oldOwner</span>, </span>address</span> indexed</span> newOwner</span>)</span>;</span></span>
</span>
    modifier</span> onlyOwner</span>(</span>)</span> {</span> require</span>(</span>msg.sender</span> ==</span> _owner</span>,</span> "not owner"</span>)</span>;</span> _</span>;</span> }</span></span>
</span>
    constructor</span>(</span>address</span> _payoutAsset</span>,</span> address</span> _desiredAsset</span>,</span> uint256</span> _required</span>,</span> address</span> _sink</span>)</span> {</span></span>
        require</span>(</span>!</span>(</span>_payoutAsset </span>==</span> address</span>(</span>0</span>)</span> &&</span> _desiredAsset </span>==</span> address</span>(</span>0</span>)</span>)</span>,</span> "ETH-ETH disallowed"</span>)</span>;</span></span>
        _owner </span>=</span> msg.sender</span>;</span></span>
        payoutAsset </span>=</span> _payoutAsset</span>;</span>              //</span> zero means ETH payout</span></span>
        desiredAsset </span>=</span> _desiredAsset</span>;</span>            //</span> zero means ETH payment</span></span>
        requiredPayment </span>=</span> _required</span>;</span></span>
        paymentSink </span>=</span> _sink</span>;</span></span>
        emit</span> OwnershipTransferred</span>(</span>address</span>(</span>0</span>)</span>,</span> _owner</span>)</span>;</span></span>
        emit</span> PaymentConfigUpdated</span>(</span>desiredAsset</span>,</span> requiredPayment</span>,</span> paymentSink</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> owner</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span> {</span> return</span> _owner</span>;</span> }</span></span>
    function</span> transferOwnership</span>(</span>address</span> n</span>)</span> external</span> onlyOwner</span> {</span> _owner </span>=</span> n</span>;</span> emit</span> OwnershipTransferred</span>(</span>msg.sender</span>,</span> n</span>)</span>;</span> }</span></span>
</span>
    ///</span> @notice</span> Accept ETH only when this instance vends ETH</span></span>
    receive</span>(</span>)</span> external</span> payable</span> {</span></span>
        require</span>(</span>payoutToken </span>==</span> address</span>(</span>0</span>)</span>,</span> "ETH payout disabled"</span>)</span>;</span></span>
    }</span></span>
</span>
    //</span> desiredAsset is immutable in this reference; no setter is provided.</span></span>
    function</span> setRequiredPayment</span>(</span>uint256</span> amount</span>)</span> external</span> onlyOwner</span> {</span> requiredPayment </span>=</span> amount</span>;</span> emit</span> PaymentConfigUpdated</span>(</span>desiredAsset</span>,</span> requiredPayment</span>,</span> paymentSink</span>)</span>;</span> }</span></span>
    function</span> setPaymentSink</span>(</span>address</span> sink</span>)</span> external</span> onlyOwner</span> {</span> paymentSink </span>=</span> sink</span>;</span> emit</span> PaymentConfigUpdated</span>(</span>desiredAsset</span>,</span> requiredPayment</span>,</span> paymentSink</span>)</span>;</span> }</span></span>
</span>
    function</span> purchase</span>(</span>address</span> to</span>)</span> external</span> payable</span> nonReentrant</span> returns</span> (</span>uint256</span> dispensed</span>)</span> {</span></span>
        uint256</span> toDispense</span>;</span></span>
        if</span> (</span>payoutAsset </span>==</span> address</span>(</span>0</span>)</span>)</span> {</span></span>
            //</span> capture live ETH balance</span></span>
            toDispense </span>=</span> address</span>(</span>this</span>)</span>.</span>balance</span>;</span></span>
        }</span> else</span> {</span></span>
            toDispense </span>=</span> IERC20</span>(</span>payoutAsset</span>)</span>.</span>balanceOf</span>(</span>address</span>(</span>this</span>)</span>)</span>;</span></span>
        }</span></span>
        require</span>(</span>toDispense </span>></span> 0</span>,</span> "empty"</span>)</span>;</span></span>
</span>
        //</span> collect payment</span></span>
        if</span> (</span>desiredAsset </span>==</span> address</span>(</span>0</span>)</span>)</span> {</span></span>
            require</span>(</span>msg</span>.</span>value </span>==</span> requiredPayment</span>,</span> "bad msg.value"</span>)</span>;</span></span>
            (</span>bool</span> ok</span>,</span> )</span> =</span> paymentSink</span>.</span>call</span>{</span>value</span>:</span> msg</span>.</span>value</span>}</span>(</span>""</span>)</span>;</span></span>
            require</span>(</span>ok</span>,</span> "sink transfer failed"</span>)</span>;</span></span>
        }</span> else</span> {</span></span>
            require</span>(</span>msg</span>.</span>value </span>==</span> 0</span>,</span> "unexpected ETH"</span>)</span>;</span></span>
            require</span>(</span>IERC20</span>(</span>desiredAsset</span>)</span>.</span>transferFrom</span>(</span>msg.sender</span>,</span> paymentSink</span>,</span> requiredPayment</span>)</span>,</span> "payment transfer failed"</span>)</span>;</span></span>
        }</span></span>
</span>
        //</span> payout</span></span>
        if</span> (</span>payoutAsset </span>==</span> address</span>(</span>0</span>)</span>)</span> {</span></span>
            (</span>bool</span> ok2</span>,</span> )</span> =</span> to</span>.</span>call</span>{</span>value</span>:</span> toDispense</span>}</span>(</span>""</span>)</span>;</span></span>
            require</span>(</span>ok2</span>,</span> "ETH payout failed"</span>)</span>;</span></span>
        }</span> else</span> {</span></span>
            require</span>(</span>IERC20</span>(</span>payoutAsset</span>)</span>.</span>transfer</span>(</span>to</span>,</span> toDispense</span>)</span>,</span> "token payout failed"</span>)</span>;</span></span>
        }</span></span>
</span>
        emit</span> Purchased</span>(</span>msg.sender</span>,</span> to</span>,</span> toDispense</span>,</span> requiredPayment</span>)</span>;</span></span>
        return</span> toDispense</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Security Considerations</h2>


Payout accounting.</strong> The dispensed amount is computed from the live onchain balance of the payout asset. Because ETH-to-ETH is disallowed, there is no ambiguity about subtracting msg.value</code>. Capture the amount to dispense at function entry and use that value for the transfer.</p>
</li>

Reentrancy and external calls.</strong> Use the Checks-Effects-Interactions pattern and a reentrancy guard. Avoid any external calls before you (a) capture the amount to dispense and (b) forward payment to paymentSink</code>. Do not perform callbacks between collecting payment and completing the payout.</p>
</li>

Receiver constraints.</strong> The recipient to</code> must be able to receive the asset being dispensed. ETH payouts require a payable fallback; ERC-20</a> payouts require that to</code> is not a contract that reverts on transfer</code>.</p>
</li>

Payment sink constraints.</strong> The paymentSink</code> must be able to receive the desired payment asset. For ETH payments, paymentSink</code> must be payable. For ERC-20</a> payments, paymentSink</code> must not revert when credited via transferFrom</code>. Using a burn address, splitter, or treasury is acceptable; the specification is agnostic to the mechanism.</p>
</li>

Unsolicited transfers.</strong> The next payout will include any assets pushed to the contract (e.g., direct ETH sends or ERC-20</a> transfers). Operators should account for this at the integration layer, or front the contract with filters if needed. An optional admin-only rescue</code> for non-payoutAsset</code> assets can mitigate mistakes without affecting conformance.</p>
</li>

Approvals and permits.</strong> When using ERC-20</a> payments, callers should consider allowance race conditions. If a purchaseWithPermit</code> helper is implemented, verify domain separator, deadline, and nonce handling, and revert on insufficient post‑permit allowance.</p>
</li>

Admin changes.</strong> Because setters can change requiredPayment</code> or paymentSink</code>, governance should protect these operations. Common mitigations include timelocks, scheduled changes with announcement windows, and immutability for parameters that should never change.</p>
</li>

Proxies and clones.</strong> Constructors do not run per proxy or minimal clone. Implementations should set payoutAsset</code> and desiredAsset</code> once during initialization and ensure they cannot change afterward. Avoid exposing setters and protect initializers against re-entry or multiple calls.</p>
</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Trustless Agents
2025-08-13T00:00:00+00:00
Abstract</h2>
This protocol proposes to use blockchains to discover, choose, and interact with agents across organizational boundaries</strong> without pre-existing trust, thus enabling open-ended agent economies</strong>.</p>
Trust models are pluggable and tiered, with security proportional to value at risk, from low-stake tasks like ordering pizza to high-stake tasks like medical diagnosis. Developers can choose from different trust models: reputation systems using client feedback, validation via stake-secured re-execution, zero-knowledge machine learning (zkML) proofs, or trusted execution environment (TEE) oracles.</p>
Motivation</h2>
Model context protocol (MCP) allows servers to list and offer their capabilities (prompts, resources, tools, and completions), while Agent2Agent (A2A) handles agent authentication, skills advertisement via AgentCards, direct messaging, and complete task-lifecycle orchestration. However, these agent communication protocols don't inherently cover agent discovery and trust.</p>
To foster an open, cross-organizational agent economy, we need mechanisms for discovering and trusting agents in untrusted settings. This ERC addresses this need through three lightweight registries, which can be deployed on any L2 or on Mainnet as per-chain singletons:</p>
Identity Registry</strong> - A minimal on-chain handle based on ERC-721</a> with URIStorage extension that resolves to an agent's registration file, providing every agent with a portable, censorship-resistant identifier.</p>
Reputation Registry</strong> - A standard interface for posting and fetching feedback signals. Scoring and aggregation occur both on-chain (for composability) and off-chain (for sophisticated algorithms), enabling an ecosystem of specialized services for agent scoring, auditor networks, and insurance pools.</p>
Validation Registry</strong> - Generic hooks for requesting and recording independent validators checks (e.g. stakers re-running the job, zkML verifiers, TEE oracles, trusted judges).</p>
Payments are orthogonal to this protocol and not covered here. However, examples are provided showing how x402 payments</strong> can enrich feedback signals.</p>
Specification</h2>
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</a> and RFC 8174</a>.</p>
Identity Registry</h3>
The Identity Registry uses ERC-721 with the URIStorage extension for agent registration, making all agents immediately browsable and transferable with NFTs-compliant apps</strong>. Each agent is uniquely identified globally by:</p>

agentRegistry</em>: A colon-separated string {namespace}:{chainId}:{identityRegistry}</code> (e.g., eip155:1:0x742...</code>) where:

namespace</em>: The chain family identifier (eip155</code> for EVM chains)</li>
chainId</em>: The blockchain network identifier</li>
identityRegistry</em>: The address where the ERC-721 registry contract is deployed</li>
</ul>
</li>
agentId</em>: The ERC-721 tokenId assigned incrementally by the registry</li>
</ul>
Throughout this document, tokenId</em> in ERC-721 is referred to as agentId</em> and tokenURI</em> in ERC-721 is referred to as agentURI</em>. The owner of the ERC-721 token is the owner of the agent and can transfer ownership or delegate management (e.g., updating the registration file) to operators, as supported by ERC721URIStorage</code>.</p>
Agent URI and Agent Registration File</h4>
The agentURI</em> MUST resolve to the agent registration file. It MAY use any URI scheme such as ipfs://</code> (e.g., ipfs://cid</code>), https://</code> (e.g., https://example.com/agent3.json</code>), or a base64-encoded data:</code> URI (e.g., data:application/json;base64,eyJ0eXBlIjoi...</code>) for fully on-chain metadata. When the registration uri changes, it can be updated with setAgentURI()</em>.</p>
The registration file MUST have the following structure:</p>
{</span></span>
  "</span>type</span>"</span>:</span> "</span>https://eips.ethereum.org/EIPS/eip-8004#registration-v1</span>"</span>,</span></span>
  "</span>name</span>"</span>:</span> "</span>myAgentName</span>"</span>,</span></span>
  "</span>description</span>"</span>:</span> "</span>A natural language description of the Agent, which MAY include what it does, how it works, pricing, and interaction methods</span>"</span>,</span></span>
  "</span>image</span>"</span>:</span> "</span>https://example.com/agentimage.png</span>"</span>,</span></span>
  "</span>services</span>"</span>:</span> [</span></span>
   {</span></span>
      "</span>name</span>"</span>:</span> "</span>web</span>"</span>,</span></span>
      "</span>endpoint</span>"</span>:</span> "</span>https://web.agentxyz.com/</span>"</span></span>
    }</span>,</span></span>
    {</span></span>
      "</span>name</span>"</span>:</span> "</span>A2A</span>"</span>,</span></span>
      "</span>endpoint</span>"</span>:</span> "</span>https://agent.example/.well-known/agent-card.json</span>"</span>,</span></span>
      "</span>version</span>"</span>:</span> "</span>0.3.0</span>"</span></span>
    }</span>,</span></span>
    {</span></span>
      "</span>name</span>"</span>:</span> "</span>MCP</span>"</span>,</span></span>
      "</span>endpoint</span>"</span>:</span> "</span>https://mcp.agent.eth/</span>"</span>,</span></span>
      "</span>version</span>"</span>:</span> "</span>2025-06-18</span>"</span></span>
    }</span>,</span></span>
    {</span></span>
      "</span>name</span>"</span>:</span> "</span>OASF</span>"</span>,</span></span>
      "</span>endpoint</span>"</span>:</span> "</span>ipfs://{cid}</span>"</span>,</span></span>
      "</span>version</span>"</span>:</span> "</span>0.8</span>"</span>,</span> //</span> https://github.com/agntcy/oasf/tree/v0.8.0</span></span>
      "</span>skills</span>"</span>:</span> [</span>]</span>,</span> //</span> OPTIONAL</span></span>
      "</span>domains</span>"</span>:</span> [</span>]</span> //</span> OPTIONAL</span></span>
    }</span>,</span></span>
    {</span></span>
      "</span>name</span>"</span>:</span> "</span>ENS</span>"</span>,</span></span>
      "</span>endpoint</span>"</span>:</span> "</span>vitalik.eth</span>"</span>,</span></span>
      "</span>version</span>"</span>:</span> "</span>v1</span>"</span></span>
    }</span>,</span></span>
    {</span></span>
      "</span>name</span>"</span>:</span> "</span>DID</span>"</span>,</span></span>
      "</span>endpoint</span>"</span>:</span> "</span>did:method:foobar</span>"</span>,</span></span>
      "</span>version</span>"</span>:</span> "</span>v1</span>"</span></span>
    }</span>,</span></span>
    {</span></span>
      "</span>name</span>"</span>:</span> "</span>email</span>"</span>,</span></span>
      "</span>endpoint</span>"</span>:</span> "</span>mail@myagent.com</span>"</span></span>
    }</span></span>
  ]</span>,</span></span>
  "</span>x402Support</span>"</span>:</span> false</span>,</span></span>
  "</span>active</span>"</span>:</span> true</span>,</span></span>
  "</span>registrations</span>"</span>:</span> [</span></span>
    {</span></span>
      "</span>agentId</span>"</span>:</span> 22</span>,</span></span>
      "</span>agentRegistry</span>"</span>:</span> "</span>{namespace}:{chainId}:{identityRegistry}</span>"</span> //</span> e.g. eip155:1:0x742...</span></span>
    }</span></span>
  ]</span>,</span></span>
  "</span>supportedTrust</span>"</span>:</span> [</span></span>
    "</span>reputation</span>"</span>,</span></span>
    "</span>crypto-economic</span>"</span>,</span></span>
    "</span>tee-attestation</span>"</span></span>
  ]</span></span>
}</span></span></code></pre>
The type</em>, name</em>, description</em>, and image</em> fields at the top SHOULD ensure compatibility with ERC-721 apps. The number and type of endpoints</em> are fully customizable, allowing developers to add as many as they wish. The version</em> field in endpoints is a SHOULD, not a MUST.</p>
Agents MAY advertise their endpoints, which point to an A2A agent card, an MCP endpoint, an ENS agent name, DIDs, or the agent's wallets on any chain (even chains where the agent is not registered).</p>
Endpoint Domain Verification (Optional)</h4>
Since endpoints can point to domains not controlled by the agent owner, an agent MAY optionally prove control of an HTTPS endpoint-domain by publishing https://{endpoint-domain}/.well-known/agent-registration.json</code> containing at least a registrations</code> list (or the full agent registration file). Users MAY treat the endpoint-domain as verified if the file is reachable over HTTPS and includes a registrations</code> entry whose agentRegistry</code> and agentId</code> match the on-chain agent; if the endpoint-domain is the same domain that serves the agent’s primary registration file referenced by agentURI</code>, this additional check is not needed because domain control is already demonstrated there.</p>
Agents SHOULD have at least one registration (multiple are possible), and all fields in the registration are mandatory.
The supportedTrust</em> field is OPTIONAL. If absent or empty, this ERC is used only for discovery, not for trust.</p>
On-chain metadata</h4>
The registry extends ERC-721 by adding getMetadata(uint256 agentId, string metadataKey)</code> and setMetadata(uint256 agentId, string metadataKey, bytes metadataValue)</code> functions for optional extra on-chain agent metadata:</p>
function</span> getMetadata</span>(</span>uint256</span> agentId</span>,</span> string</span> memory</span> metadataKey</span>)</span> external</span> view</span> returns</span> (</span>bytes</span> memory</span>)</span></span>
function</span> setMetadata</span>(</span>uint256</span> agentId</span>,</span> string</span> memory</span> metadataKey</span>,</span> bytes</span> memory</span> metadataValue</span>)</span> external</span></span></code></pre>
When metadata is set, the following event is emitted:</p>
event</span> MetadataSet</span>(</span>uint256</span> indexed</span> agentId</span>, </span>string</span> indexed</span> indexedMetadataKey</span>, </span>string</span> metadataKey</span>, </span>bytes</span> metadataValue</span>)</span></span></code></pre>
The key agentWallet</code> is reserved and cannot be set via setMetadata()</code> or during register()</code> (including the metadata array overload). It represents the address where the agent receives payments and is initially set to the owner's address. To change it, the agent owner must prove control of the new wallet by providing a valid EIP-712</a> signature for EOAs or ERC-1271</a> for smart contract wallets—by calling:</p>
function</span> setAgentWallet</span>(</span>uint256</span> agentId</span>,</span> address</span> newWallet</span>,</span> uint256</span> deadline</span>,</span> bytes</span> calldata</span> signature</span>)</span> external</span></span></code></pre>
To read and clear the currently set wallet, the following functions are exposed:</p>
function</span> getAgentWallet</span>(</span>uint256</span> agentId</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span></span>
function</span> unsetAgentWallet</span>(</span>uint256</span> agentId</span>)</span> external</span></span></code></pre>
When the agent is transferred, agentWallet</code> is automatically cleared (effectively resetting it to the zero address) and must be re-verified by the new owner.</p>
Registration</h4>
New agents can be minted by calling one of these functions:</p>
struct</span> MetadataEntry</span> {</span></span>
string</span> metadataKey</span>;</span></span>
bytes</span> metadataValue</span>;</span></span>
}</span></span>
</span>
function</span> register</span>(</span>string</span> agentURI</span>,</span> MetadataEntry</span>[</span>]</span> calldata</span> metadata</span>)</span> external</span> returns</span> (</span>uint256</span> agentId</span>)</span></span>
</span>
function</span> register</span>(</span>string</span> agentURI</span>)</span> external</span> returns</span> (</span>uint256</span> agentId</span>)</span></span>
</span>
// </span>agentURI</span> is</span> added</span> later</span> with</span> setAgentURI</span>(</span>)</span></span>
function</span> register</span>(</span>)</span> external</span> returns</span> (</span>uint256</span> agentId</span>)</span></span></code></pre>
This emits one Transfer event, one MetadataSet event for the reserved agentWallet</code> key, one MetadataSet event for each additional metadata entry (if any), and</p>
event</span> Registered</span>(</span>uint256</span> indexed</span> agentId</span>, </span>string</span> agentURI</span>, </span>address</span> indexed</span> owner</span>)</span></span></code></pre>Update agentURI</h4>
The agentURI can be updated by calling the following function, which emits a URIUpdated event:</p>
</span>
function</span> setAgentURI</span>(</span>uint256</span> agentId</span>,</span> string</span> calldata</span> newURI</span>)</span> external</span></span>
</span>
event</span> URIUpdated</span>(</span>uint256</span> indexed</span> agentId</span>,</span> string</span> newURI</span>,</span> address</span> indexed</span> updatedBy</span>)</span></span>
</span></code></pre>
If the owner wants to store the entire registration file on-chain, the agentURI</em> SHOULD use a base64-encoded data URI rather than a serialized JSON string:</p>
data:application/json;base64,eyJ0eXBlIjoi...</span></span></code></pre>Reputation Registry</h3>
When the Reputation Registry is deployed, the identityRegistry</em> address is set via initialize(address identityRegistry_)</code> and publicly visible by calling:</p>
function</span> getIdentityRegistry</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span> identityRegistry</span>)</span></span></code></pre>
The feedback given by a clientAddress</em> to an agent consists of a signed fixed-point value</em> (int128</code>) and its valueDecimals</em> (uint8</code>, 0-18), plus optional tag1</em> and tag2</em> (left to developers' discretion to provide maximum on-chain composability and filtering), an endpoint</em> URI, a file URI pointing to an off-chain JSON containing additional information, and its KECCAK-256 file hash to guarantee integrity. We suggest using IPFS or equivalent services to make feedback easily indexed by subgraphs or similar technologies. For IPFS URIs, the hash is not required.
All fields except value</em> and valueDecimals</em> are OPTIONAL, so the off-chain file is not required and can be omitted.</p>
Giving Feedback</h4>
New feedback can be added by any clientAddress</em> calling:</p>
function</span> giveFeedback</span>(</span>uint256</span> agentId</span>,</span> int128</span> value</span>,</span> uint8</span> valueDecimals</span>,</span> string</span> calldata</span> tag1</span>,</span> string</span> calldata</span> tag2</span>,</span> string</span> calldata</span> endpoint</span>,</span> string</span> calldata</span> feedbackURI</span>,</span> bytes32</span> feedbackHash</span>)</span> external</span></span></code></pre>
The agentId</em> must be a validly registered agent. The valueDecimals</em> MUST be between 0 and 18. The feedback submitter MUST NOT be the agent owner or an approved operator for agentId</em>. tag1</em>, tag2</em>, endpoint</em>, feedbackURI</em>, and feedbackHash</em> are OPTIONAL.</p>
Where provided, feedbackHash</em> is the KECCAK-256 hash (keccak256</code>) of the content referenced by feedbackURI</em>, enabling verifiable integrity for non-content-addressed URIs. For IPFS (or other content-addressed URIs), feedbackHash</em> is OPTIONAL and can be omitted (e.g., set to bytes32(0)</code>).</p>
If the procedure succeeds, an event is emitted:</p>
event</span> NewFeedback</span>(</span>uint256</span> indexed</span> agentId</span>, </span>address</span> indexed</span> clientAddress</span>, </span>uint64</span> feedbackIndex</span>, </span>int128</span> value</span>, </span>uint8</span> valueDecimals</span>, </span>string</span> indexed</span> indexedTag1</span>, </span>string</span> tag1</span>, </span>string</span> tag2</span>, </span>string</span> endpoint</span>, </span>string</span> feedbackURI</span>, </span>bytes32</span> feedbackHash</span>)</span></span></code></pre>
The feedback fields value</em>, valueDecimals</em>, tag1</em>, tag2</em>, and isRevoked</em> are stored in the contract storage along with the feedbackIndex (a 1-indexed counter of feedback submissions that clientAddress</em> has given to agentId</em>). The fields endpoint</em>, feedbackURI</em>, and feedbackHash</em> are emitted but are not stored. This exposes reputation signals to any smart contract, enabling on-chain composability.</p>
When the feedback is given by an agent (i.e., the client is an agent), the agent SHOULD use the address set in the on-chain optional agentWallet</code> metadata as the clientAddress, to facilitate reputation aggregation.</p>
Examples of value</code> / valueDecimals</code></h4>
tag1</th> What it measures</th> Example human value</th> value</code></th> valueDecimals</code></th></tr></thead>

starred</code></td> Quality rating (0-100)</td> 87/100</code></td> 87</code></td> 0</code></td></tr>
reachable</code></td> Endpoint reachable (binary)</td> true</code></td> 1</code></td> 0</code></td></tr>
ownerVerified</code></td> Endpoint owned by agent owner (binary)</td> true</code></td> 1</code></td> 0</code></td></tr>
uptime</code></td> Endpoint uptime (%)</td> 99.77%</code></td> 9977</code></td> 2</code></td></tr>
successRate</code></td> Endpoint success rate (%)</td> 89%</code></td> 89</code></td> 0</code></td></tr>
responseTime</code></td> Response time (ms)</td> 560ms</code></td> 560</code></td> 0</code></td></tr>
blocktimeFreshness</code></td> Avg block delay (blocks)</td> 4 blocks</code></td> 4</code></td> 0</code></td></tr>
revenues</code></td> Cumulative revenues (e.g., USD)</td> $560</code></td> 560</code></td> 0</code></td></tr>
tradingYield</code> (tag2</code> = day, week, month, year</code>)</td> Yield</td> -3,2%</code></td> -32</code></td> 1</code></td></tr>
</tbody></table>
Off-Chain Feedback File Structure</h4>
The OPTIONAL file at the URI could look like:</p>
{</span></span>
  //</span> MUST FIELDS</span></span>
  "</span>agentRegistry</span>"</span>:</span> "</span>eip155:1:{identityRegistry}</span>"</span>,</span></span>
  "</span>agentId</span>"</span>:</span> 22</span>,</span></span>
  "</span>clientAddress</span>"</span>:</span> "</span>eip155:1:{clientAddress}</span>"</span>,</span></span>
  "</span>createdAt</span>"</span>:</span> "</span>2025-09-23T12:00:00Z</span>"</span>,</span></span>
  "</span>value</span>"</span>:</span> 100</span>,</span></span>
  "</span>valueDecimals</span>"</span>:</span> 0</span>,</span></span>
</span>
  //</span> ALL OPTIONAL FIELDS</span></span>
  "</span>tag1</span>"</span>:</span> "</span>foo</span>"</span>,</span></span>
  "</span>tag2</span>"</span>:</span> "</span>bar</span>"</span>,</span></span>
  "</span>endpoint</span>"</span>:</span> "</span>https://agent.example.com/GetPrice</span>"</span>,</span></span>
</span>
  "</span>mcp</span>"</span>:</span> {</span> "</span>tool</span>"</span>:</span> "</span>ToolName</span>"</span> }</span>,</span> //</span> or: { "prompt": "PromptName" } / { "resource": "ResourceName" }</span></span>
</span>
  //</span> A2A: see "Context Identifier Semantics" and Task model in the A2A specification.</span></span>
  "</span>a2a</span>"</span>:</span> {</span></span>
    "</span>skills</span>"</span>:</span> [</span>"</span>as-defined-by-A2A</span>"</span>]</span>,</span> //</span> e.g., AgentSkill identifiers</span></span>
    "</span>contextId</span>"</span>:</span> "</span>as-defined-by-A2A</span>"</span>,</span></span>
    "</span>taskId</span>"</span>:</span> "</span>as-defined-by-A2A</span>"</span></span>
  }</span>,</span></span>
</span>
  "</span>oasf</span>"</span>:</span> {</span></span>
    "</span>skills</span>"</span>:</span> [</span>"</span>as-defined-by-OASF</span>"</span>]</span>,</span></span>
    "</span>domains</span>"</span>:</span> [</span>"</span>as-defined-by-OASF</span>"</span>]</span></span>
  }</span>,</span></span>
  </span></span>
  "</span>proofOfPayment</span>"</span>:</span> {</span> //</span> this can be used for x402 proof of payment</span></span>
	  "</span>fromAddress</span>"</span>:</span> "</span>0x00...</span>"</span>,</span></span>
	  "</span>toAddress</span>"</span>:</span> "</span>0x00...</span>"</span>,</span></span>
	  "</span>chainId</span>"</span>:</span> "</span>1</span>"</span>,</span></span>
	  "</span>txHash</span>"</span>:</span> "</span>0x00...</span>"</span></span>
   }</span>,</span></span>
</span>
 //</span> Other fields</span></span>
  "</span> ... </span>"</span>:</span> {</span> "</span> ... </span>"</span> }</span> //</span> MAY</span></span>
}</span></span></code></pre>Revoking Feedback</h4>
clientAddress</em> can revoke feedback by calling:</p>
function</span> revokeFeedback</span>(</span>uint256</span> agentId</span>,</span> uint64</span> feedbackIndex</span>)</span> external</span></span></code></pre>
This emits:</p>
event</span> FeedbackRevoked</span>(</span>uint256</span> indexed</span> agentId</span>, </span>address</span> indexed</span> clientAddress</span>, </span>uint64</span> indexed</span> feedbackIndex</span>)</span></span></code></pre>Appending Responses</h4>
Anyone (e.g., the agentId</em> showing a refund, any off-chain data intelligence aggregator tagging feedback as spam) can call:</p>
function</span> appendResponse</span>(</span>uint256</span> agentId</span>,</span> address</span> clientAddress</span>,</span> uint64</span> feedbackIndex</span>,</span> string</span> calldata</span> responseURI</span>,</span> bytes32</span> responseHash</span>)</span> external</span></span></code></pre>
Where responseHash</em> is the KECCAK-256 file hash of the responseURI</em> file content to guarantee integrity. This field is not required for IPFS URIs.</p>
This emits:</p>
event</span> ResponseAppended</span>(</span>uint256</span> indexed</span> agentId</span>, </span>address</span> indexed</span> clientAddress</span>, </span>uint64</span> feedbackIndex</span>, </span>address</span> indexed</span> responder</span>, </span>string</span> responseURI</span>, </span>bytes32</span> responseHash</span>)</span></span></code></pre>Read Functions</h4>
function</span> getSummary</span>(</span>uint256</span> agentId</span>,</span> address</span>[</span>]</span> calldata</span> clientAddresses</span>,</span> string</span> tag1</span>,</span> string</span> tag2</span>)</span> external</span> view</span> returns</span> (</span>uint64</span> count</span>,</span> int128</span> summaryValue</span>,</span> uint8</span> summaryValueDecimals</span>)</span></span>
// </span>agentId</span> and</span> clientAddresses</span> are</span> mandatory</span>;</span> tag1 and tag2 are optional filters</span>.</span></span>
//</span> clientAddresses MUST be provided (non-empty); results without filtering by clientAddresses are subject to Sybil/spam attacks. See Security Considerations for details</span></span>
</span>
function</span> readFeedback</span>(</span>uint256</span> agentId</span>,</span> address</span> clientAddress</span>,</span> uint64</span> feedbackIndex</span>)</span> external</span> view</span> returns</span> (</span>int128</span> value</span>,</span> uint8</span> valueDecimals</span>,</span> string</span> tag1</span>,</span> string</span> tag2</span>,</span> bool</span> isRevoked</span>)</span></span>
</span>
function</span> readAllFeedback</span>(</span>uint256</span> agentId</span>,</span> address</span>[</span>]</span> calldata</span> clientAddresses</span>,</span> string</span> tag1</span>,</span> string</span> tag2</span>,</span> bool</span> includeRevoked</span>)</span> external</span> view</span> returns</span> (</span>address</span>[</span>]</span> memory</span> clients</span>,</span> uint64</span>[</span>]</span> memory</span> feedbackIndexes</span>,</span> int128</span>[</span>]</span> memory</span> values</span>,</span> uint8</span>[</span>]</span> memory</span> valueDecimals</span>,</span> string</span>[</span>]</span> memory</span> tag1s</span>,</span> string</span>[</span>]</span> memory</span> tag2s</span>,</span> bool</span>[</span>]</span> memory</span> revokedStatuses</span>)</span></span>
// </span>agentId</span> is</span> the</span> only</span> mandatory</span> parameter</span>;</span> others are optional filters</span>.</span> Revoked feedback are omitted by default</span>.</span></span>
</span>
function</span> getResponseCount</span>(</span>uint256</span> agentId</span>,</span> address</span> clientAddress</span>,</span> uint64</span> feedbackIndex</span>,</span> address</span>[</span>]</span> responders</span>)</span> external</span> view</span> returns</span> (</span>uint64</span> count</span>)</span></span>
// </span>agentId</span> is</span> the</span> only</span> mandatory</span> parameter</span>;</span> others are optional filters</span>.</span></span>
</span>
function</span> getClients</span>(</span>uint256</span> agentId</span>)</span> external</span> view</span> returns</span> (</span>address</span>[</span>]</span> memory</span>)</span></span>
</span>
function</span> getLastIndex</span>(</span>uint256</span> agentId</span>,</span> address</span> clientAddress</span>)</span> external</span> view</span> returns</span> (</span>uint64</span>)</span></span></code></pre>
We expect reputation systems around reviewers/clientAddresses to emerge. While simple filtering by reviewer (useful to mitigate spam) and by tag are enabled on-chain, more complex reputation aggregation will happen off-chain</strong>.</p>
Validation Registry</h3>
This registry enables agents to request verification of their work and allows validator smart contracts to provide responses that can be tracked on-chain</strong>. Validator smart contracts could use, for example, stake-secured inference re-execution, zkML verifiers or TEE oracles to validate or reject requests.</p>
When the Validation Registry is deployed, the identityRegistry</em> address is set via initialize(address identityRegistry_)</code> and is visible by calling getIdentityRegistry()</code>, as described above.</p>
Validation Request</h4>
Agents request validation by calling:</p>
function</span> validationRequest</span>(</span>address</span> validatorAddress</span>,</span> uint256</span> agentId</span>,</span> string</span> requestURI</span>,</span> bytes32</span> requestHash</span>)</span> external</span></span></code></pre>
This function MUST be called by the owner or operator of agentId</em>. The requestURI</em> points to off-chain data containing all information needed for the validator to validate, including inputs and outputs needed for the verification. The requestHash</em> is a commitment to this data (keccak256</code> of the request payload) and identifies the request. All other fields are mandatory.</p>
A ValidationRequest event is emitted:</p>
event</span> ValidationRequest</span>(</span>address</span> indexed</span> validatorAddress</span>, </span>uint256</span> indexed</span> agentId</span>, </span>string</span> requestURI</span>, </span>bytes32</span> indexed</span> requestHash</span>)</span></span></code></pre>Validation Response</h4>
Validators respond by calling:</p>
function</span> validationResponse</span>(</span>bytes32</span> requestHash</span>,</span> uint8</span> response</span>,</span> string</span> responseURI</span>,</span> bytes32</span> responseHash</span>,</span> string</span> tag</span>)</span> external</span></span></code></pre>
Only requestHash</em> and response</em> are mandatory; responseURI</em>, responseHash</em> and tag</em> are optional. This function MUST be called by the validatorAddress</em> specified in the original request. The response</em> is a value between 0 and 100, which can be used as binary (0 for failed, 100 for passed) or with intermediate values for validations with a spectrum of outcomes. The optional responseURI</em> points to off-chain evidence or audit of the validation, responseHash</em> is its commitment (in case the resource is not on IPFS), while tag</em> allows for custom categorization or additional data.</p>
validationResponse() can be called multiple times for the same requestHash</em>, enabling use cases like progressive validation states (e.g., “soft finality” and “hard finality” using tag</em>) or updates to validation status.</p>
Upon successful execution, a ValidationResponse</em> event is emitted with all function parameters:</p>
event</span> ValidationResponse</span>(</span>address</span> indexed</span> validatorAddress</span>, </span>uint256</span> indexed</span> agentId</span>, </span>bytes32</span> indexed</span> requestHash</span>, </span>uint8</span> response</span>, </span>string</span> responseURI</span>, </span>bytes32</span> responseHash</span>, </span>string</span> tag</span>)</span></span></code></pre>
The contract stores requestHash</em>, validatorAddress</em>, agentId</em>, response</em>, responseHash</em>, lastUpdate</em>, and tag</em> for on-chain querying and composability.</p>
Read Functions</h4>
function</span> getValidationStatus</span>(</span>bytes32</span> requestHash</span>)</span> external</span> view</span> returns</span> (</span>address</span> validatorAddress</span>,</span> uint256</span> agentId</span>,</span> uint8</span> response</span>,</span> bytes32</span> responseHash</span>,</span> string</span> tag</span>,</span> uint256</span> lastUpdate</span>)</span></span>
</span>
//</span>Returns</span> aggregated</span> validation</span> statistics</span> for</span> an</span> agent</span>.</span> agentId</span> is</span> the</span> only</span> mandatory</span> parameter</span>;</span> validatorAddresses and tag are optional filters</span></span>
function</span> getSummary</span>(</span>uint256</span> agentId</span>,</span> address</span>[</span>]</span> calldata</span> validatorAddresses</span>,</span> string</span> tag</span>)</span> external</span> view</span> returns</span> (</span>uint64</span> count</span>,</span> uint8</span> averageResponse</span>)</span></span>
</span>
function</span> getAgentValidations</span>(</span>uint256</span> agentId</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>[</span>]</span> memory</span> requestHashes</span>)</span></span>
</span>
function</span> getValidatorRequests</span>(</span>address</span> validatorAddress</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>[</span>]</span> memory</span> requestHashes</span>)</span></span></code></pre>
Incentives and slashing related to validation are managed by the specific validation protocol and are outside the scope of this registry.</p>
Rationale</h2>

Agent communication protocols</strong>: MCP and A2A are popular, and other protocols could emerge. For this reason, this protocol links from the blockchain to a flexible registration file including a list where endpoints can be added at will, combining AI primitives (MCP, A2A) and Web3 primitives such as wallet addresses, DIDs, and ENS names.</li>
Feedback</strong>: The protocol combines the leverage of nomenclature already established by A2A (such as tasks and skills) and MCP (such as tools and prompts) with complete flexibility in the feedback signal structure.</li>
Gas Sponsorship</strong>: Since clients don't need to be registered anymore, any application can implement frictionless feedback leveraging EIP-7702</a>.</li>
Indexing</strong>: Since feedback data is saved on-chain and we suggest using IPFS for full data, it's easy to leverage subgraphs to create indexers and improve UX.</li>
Deployment</strong>: We expect the registries to be deployed with singletons per chain. Note that an agent registered and receiving feedback on chain A can still operate and transact on other chains. Agents can also be registered on multiple chains if desired.</li>
</ul>


Security Considerations</h2>

Sybil attacks are possible, inflating the reputation of fake agents. The protocol's contribution is to make signals public and use the same schema. We expect many players to build reputation systems, for example, trusting or giving reputation to reviewers (and therefore filtering by reviewer, as the protocol already enables).</li>
On-chain pointers and hashes cannot be deleted, ensuring audit trail integrity</li>
Validator incentives and slashing are managed by specific validation protocols</li>
While this ERC cryptographically ensures the registration file corresponds to the on-chain agent, it cannot cryptographically guarantee that advertised capabilities are functional and non-malicious. The three trust models (reputation, validation, and TEE attestation) are designed to support this verification need</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Simplified Payment Verification Gateway
2025-08-07T00:00:00+00:00
Abstract</h2>
Introduce a singleton contract for on-chain verification of transactions that happened on Bitcoin. The contract is available at "0xTODO" , acting as a trustless Simplified Payment Verification (SPV) gateway where anyone can submit Bitcoin block headers. The gateway maintains the mainchain of blocks and allows the existence of Bitcoin transactions to be verified via Merkle proofs.</p>
Motivation</h2>
Ethereum's long-term mission has always been to revolutionize the financial world through decentralization, trustlessness, and programmable value enabled by smart contracts. Many great use cases have been discovered so far, including the renaissance of Decentralized Finance (DeFi), emergence of Real-World Assets (RWA), and rise of privacy-preserving protocols.</p>
However, one gem has been unreachable to date -- Bitcoin. Due to its extremely constrained programmability, one can only hold and transfer bitcoins in a trustless manner. This EIP tries to expand its capabilities by laying a solid foundation for bitcoins to be also used in various EVM-based DeFi protocols, unlocking a whole new trillion-dollar market.</p>
The singleton SPV gateway contract defined in this proposal acts as a trustless one-way bridge between Bitcoin and Ethereum, already enabling use cases such as using native</em> BTC as a lending collateral for stablecoin loans. Moreover, with the recent breakthroughs in the BitVM technology, the full-fledged, ownerless two-way bridge may soon become a reality, powering the permissionless and wrapless issuance of BTC on Ethereum.</p>
Specification</h2>
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.</p>
General</h3>
Bitcoin Block Header Structure</h4>
In Bitcoin, each block contains a header, which has a fixed size of 80 bytes and follows the following structure:</p>
Field</th> Size</th> Format</th> Description</th></tr></thead>

Version</td> 4 bytes</td> little-endian</td> The version number of the block.</td></tr>
Previous Block</td> 32 bytes</td> natural byte order</td> The block hash of a previous block this block is building on top of.</td></tr>
Merkle Root</td> 32 bytes</td> natural byte order</td> A fingerprint for all of the transactions included in the block.</td></tr>
Time</td> 4 bytes</td> little-endian</td> The current time as a Unix timestamp.</td></tr>
Bits</td> 4 bytes</td> little-endian</td> A compact representation of the current target (difficulty).</td></tr>
Nonce</td> 4 bytes</td> little-endian</td> A 32-bit number which miners compute to find a valid block hash.</td></tr>
</tbody></table>
The fields within the block header are sequentially ordered as presented in the table above.</p>
Difficulty Adjustment Mechanism</h4>
Bitcoin's Proof-of-Work (PoW) consensus mechanism has a probabilistic finality, thus relying on a dynamic difficulty target</strong> adjustments. The target's initial value is set to 0x00000000ffff0000000000000000000000000000000000000000000000000000</code>, which also serves as the minimum difficulty threshold.</p>
The target</code> is recalculated every 2016 blocks (approximately every two weeks), a period commonly referred to as a difficulty adjustment period</strong>.</p>
The expected duration for each adjustment period is 1,209,600 seconds (2016 blocks * 10 minutes/block). The new target</code> value is derived by multiplying the current target</code> by the ratio of the actual time taken to mine the preceding 2016 blocks to this expected duration.</p>
To prevent drastic difficulty fluctuations, the adjustment multiplier is capped at 4x</code> and 1/4x</code> respectively.</p>
Block Header Validation Rules</h4>
For a Bitcoin block header to be considered valid and accepted into the chain, it MUST adhere to the following consensus rules:</p>


Chain Cohesion</strong>: The Previous Block</code> hash field MUST reference the hash of a valid block that is present in the set of existing block headers.</p>
</li>

Timestamp Rules</strong>:</p>

The Time</code> field MUST be strictly greater than the Median Time Past (MTP)</strong> of the previous 11 blocks.</li>
The Time</code> field MUST NOT be more than 2 hours in the future relative to the validating node's network-adjusted time.</li>
</ul>
</li>

PoW Constraint</strong>: When the block header is hashed twice using SHA256</code>, the resulting hash MUST be less than or equal to the current target</code> value, as derived from the difficulty adjustment mechanism.</p>
</li>
</ol>
Transaction Inclusion Structure</h4>
Every Bitcoin block header has a field Merkle Root</code> that corresponds to a Merkle root of the transactions tree included in this block.</p>
The transactions Merkle tree is built recursively performing double SHA256</code> hash on each pair of sibling nodes, where the tree leaves are the double SHA256</code> hash of the raw transaction bytes. In case the node has no siblings, the hashing is done over the node with itself.</p>
To verify the transaction inclusion into the block, one SHOULD build the Merkle root from the ground up and compare it with the Merkle Root</code> stored in the selected block header. The corresponding Merkle path and hashing direction bits can be obtained and processed by querying a Bitcoin full node.</p>
Mainchain Definition</h4>
Bitcoin's mainchain</strong> is determined not just by its length, but by the greatest cumulative PoW</strong> among all valid competing chains. This cumulative work represents the total computational effort expended to mine all blocks within a specific chain.</p>
The work contributed by a single block is inversely proportional to its target</code> value. Specifically, the work of a block can be calculated as (2**256 - 1) / (target + 1)</code>. The target</code> value for a block is derived from its Bits</code> field, where the first byte encodes the required left hand bit shift, and the other three bytes the actual target value.</p>
The total cumulative work of a chain is the sum of the work values of all blocks within that chain. A block is considered part of the mainchain if it extends the chain with the greatest cumulative PoW.</p>
SPV Gateway</h3>
The SPVGateway</code> contract MUST provide a permissionless mechanism for its initialization. This mechanism MUST allow for the submission of a valid Bitcoin block header, its corresponding block height, and the cumulative PoW up to that block, without requiring special permissions.</p>
The SPVGateway</code> MUST implement the following interface:</p>
pragma</span> solidity</span> ^0.8.0</span>;</span></span>
</span>
/**</span></span>
 * </span>@notice</span> Interface for a Simplified Payment Verification Gateway contract.</span></span>
 */</span></span>
interface</span> ISPVGateway</span> {</span></span>
    /**</span></span>
     * </span>@notice</span> Represents the essential data contained within a Bitcoin block header</span></span>
     * </span>@param</span> prevBlockHash</span> The hash of the previous block</span></span>
     * </span>@param</span> merkleRoot</span> The Merkle root of the transactions in the block</span></span>
     * </span>@param</span> version</span> The block version number</span></span>
     * </span>@param</span> time</span> The block's timestamp</span></span>
     * </span>@param</span> nonce</span> The nonce used for mining</span></span>
     * </span>@param</span> bits</span> The encoded difficulty target for the block</span></span>
     */</span></span>
    struct</span> BlockHeaderData</span> {</span></span>
        bytes32</span> prevBlockHash</span>;</span></span>
        bytes32</span> merkleRoot</span>;</span></span>
        uint32</span> version</span>;</span></span>
        uint32</span> time</span>;</span></span>
        uint32</span> nonce</span>;</span></span>
        bytes4</span> bits</span>;</span></span>
    }</span></span>
</span>
    /**</span></span>
     * MUST be emitted whenever the mainchain head </span>changed</span> (e.g. in the `addBlockHeader`, `addBlockHeaderBatch` functions)</span></span>
     */</span></span>
    event</span> MainchainHeadUpdated</span>(</span></span>
        uint64</span> indexed</span> newMainchainHeight</span>,</span></span>
        bytes32</span> indexed</span> newMainchainHead</span></span>
    )</span>;</span></span>
</span>
    /**</span></span>
     * MUST be emitted whenever the new block header added to the SPV contract state</span></span>
     * (e.g. in the `addBlockHeader`, `addBlockHeaderBatch` functions)</span></span>
     */</span></span>
    event</span> BlockHeaderAdded</span>(</span>uint64</span> indexed</span> blockHeight</span>, </span>bytes32</span> indexed</span> blockHash</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Adds a single raw block header to the contract.</span></span>
     * The block header is validated before being added</span></span>
     * </span>@param</span> blockHeaderRaw</span> The raw block header bytes</span></span>
     */</span></span>
    function</span> addBlockHeader</span>(</span>bytes</span> calldata</span> blockHeaderRaw</span>)</span> external</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> OPTIONAL Function that adds a batch of the block headers to the contract.</span></span>
     * Each block header is validated and added sequentially</span></span>
     * </span>@param</span> blockHeaderRawArray</span> An array of raw block header bytes</span></span>
     */</span></span>
    function</span> addBlockHeaderBatch</span>(</span>bytes</span>[</span>]</span> calldata</span> blockHeaderRawArray</span>)</span> external</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Checks that given txId is included in the specified block with a minimum number of confirmations.</span></span>
     * </span>@param</span> merkleProof</span> The array of hashes used to build the Merkle root</span></span>
     * </span>@param</span> blockHash</span> The hash of the block in which to verify the transaction</span></span>
     * </span>@param</span> txId</span> The transaction id to verify</span></span>
     * </span>@param</span> txIndex</span> The index of the transaction in the block's Merkle tree</span></span>
     * </span>@param</span> minConfirmationsCount</span> The minimum number of confirmations required for the block</span></span>
     * </span>@return</span> True</span> if the txId is present in the block's Merkle tree and the block has at least minConfirmationsCount confirmations, false otherwise</span></span>
     */</span></span>
    function</span> checkTxInclusion</span>(</span></span>
        bytes32</span>[</span>]</span> memory</span> merkleProof</span>,</span></span>
        bytes32</span> blockHash</span>,</span></span>
        bytes32</span> txId</span>,</span></span>
        uint256</span> txIndex</span>,</span></span>
        uint256</span> minConfirmationsCount</span></span>
    )</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Returns the hash of the current mainchain head.</span></span>
     * This represents the highest block on the most accumulated work chain</span></span>
     * </span>@return</span> The</span> hash of the mainchain head</span></span>
     */</span></span>
    function</span> getMainchainHead</span>(</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Returns the height of the current mainchain head.</span></span>
     * This represents the highest block number on the most accumulated work chain</span></span>
     * </span>@return</span> The</span> height of the mainchain head</span></span>
     */</span></span>
    function</span> getMainchainHeight</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint64</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Returns the block header data for a given block hash.</span></span>
     * </span>@param</span> blockHash</span> The hash of the block</span></span>
     * </span>@return</span> The</span> block header data</span></span>
     */</span></span>
    function</span> getBlockHeader</span>(</span>bytes32</span> blockHash</span>)</span> external</span> view</span> returns</span> (</span>BlockHeaderData</span> memory</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Returns the current status of a given block</span></span>
     * </span>@param</span> blockHash</span> The hash of the block to check</span></span>
     * </span>@return</span> isInMainchain</span> True if the block is in the mainchain, false otherwise</span></span>
     * </span>@return</span> confirmationsCount</span> The number of blocks that have been mined on top of </span></span>
     * the given block if the block is in the mainchain</span></span>
     */</span></span>
    function</span> getBlockStatus</span>(</span>bytes32</span> blockHash</span>)</span> external</span> view</span> returns</span> (</span>bool</span>,</span> uint64</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Returns the Merkle root of a given block hash.</span></span>
     * This function retrieves the Merkle root from the stored block header data</span></span>
     * </span>@param</span> blockHash</span> The hash of the block</span></span>
     * </span>@return</span> The</span> Merkle root of the block</span></span>
     */</span></span>
    function</span> getBlockMerkleRoot</span>(</span>bytes32</span> blockHash</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Returns the block height for a given block hash</span></span>
     * This function retrieves the height at which the block exists in the chain</span></span>
     * </span>@param</span> blockHash</span> The hash of the block</span></span>
     * </span>@return</span> The</span> height of the block</span></span>
     */</span></span>
    function</span> getBlockHeight</span>(</span>bytes32</span> blockHash</span>)</span> external</span> view</span> returns</span> (</span>uint64</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Returns the block hash for a given block height.</span></span>
     * This function retrieves the hash of the block from the mainchain at the specified height</span></span>
     * </span>@param</span> blockHeight</span> The height of the block</span></span>
     * </span>@return</span> The</span> hash of the block</span></span>
     */</span></span>
    function</span> getBlockHash</span>(</span>uint64</span> blockHeight</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Checks if a block exists in the contract's storage.</span></span>
     * This function verifies the presence of a block by its hash</span></span>
     * </span>@param</span> blockHash</span> The hash of the block to check</span></span>
     * </span>@return</span> True</span> if the block exists, false otherwise</span></span>
     */</span></span>
    function</span> blockExists</span>(</span>bytes32</span> blockHash</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
}</span></span></code></pre>
All fields within the BlockHeaderData</code> struct MUST be converted to big-endian byte order for internal representation and processing within the smart contract.</p>
The addBlockHeader</code> function MUST perform the following checks:</p>

Validate that the submitted raw block header has a fixed size of 80 bytes.</li>
Enforce all block header validation rules as specified in the "Block Header Validation Rules" section.</li>
Integrate the new block header into the known chain by calculating its cumulative PoW and managing potential chain reorganizations as defined in the "Mainchain Definition" section.</li>
Emit a BlockHeaderAdded</code> event upon successful addition of the block header.</li>
Emit a MainchainHeadUpdated</code> event if the mainchain was updated.</li>
</ul>
The checkTxInclusion</code> function MUST perform the following steps:</p>

Check whether the provided blockHash</code> is part of the mainchain and ensure its number of confirmations is at least equal to the minConfirmationsCount</code> parameter. If any of these checks fail, the function MUST return false</code>.</li>
Using the provided merkleProof</code>, txId</code>,  and txIndex</code>, the function MUST compute the Merkle root.</li>
The computed Merkle root MUST be compared against the Merkle Root</code> field stored within the block header identified by blockHash</code>.</li>
If the computed Merkle root matches the stored Merkle Root</code>, the function MUST return true</code>. Otherwise, it MUST return false</code>.</li>
</ul>
Rationale</h2>
During the design process of the SPVGateway</code> contract, several decisions have been made that require clarification. The following initialization options of the smart contract were considered:</p>

Hardcoding the Bitcoin genesis block:</strong> This approach is the simplest for contract deployment as it embeds the initial state directly in the code. While offering absolute trustlessness of the starting point, it limits availability, as the full sync of the gateway would cost around ~100 ETH at the gas price of 1 gwei.</li>
Initialization from an arbitrary block height by trusting provided cumulative work and height:</strong> Currently, the gateway adopts this method as its initialization mechanism. While implying trust in the initial submitted values, it's a common practice for bootstrapping light clients and can be secured via off-chain mechanisms for initial validation (e.g., community-verified checkpoints).</li>
Initialization with Zero-Knowledge Proof (ZKP) for historical correctness:</strong> This advanced method involves proving the entire history of Bitcoin up to a specific block using ZKP.</li>
</ol>
Upon submitting the raw block header, the gateway expects the BlockHeaderData</code> fields to be converted to big-endian byte order. This is required to maintain EVM's efficiency, which is contrary to Bitcoin's native little-endian integer serialization.</p>
There are no "finality" rules in the SPVGateway</code> contract. The determination of such is left to consuming protocols, allowing individual definition to meet required security thresholds.</p>
The inclusion of an OPTIONAL addBlockHeaderBatch</code> function offers significant gas optimizations. For batches exceeding 11 blocks, MTP can be calculated using timestamps from calldata</code>, substantially reducing storage reads and transaction costs.</p>
Backwards Compatibility</h2>
This EIP is fully backwards compatible.</p>
Deployment Method</h3>

TBD</p>
Test Cases</h2>

TBD</p>
Reference Implementation</h2>
A reference implementation of the SPVGateway</code> contract can be found here</a>.</p>
TargetsHelper</code></a> is a supporting library that provides utility functions for working with Bitcoin's difficulty targets. It includes methods to convert the Bits</code> field from a block header to the corresponding target</code> value and vice versa, as well as functions to calculate the new difficulty target during adjustment periods.</p>

Please note that the reference implementation depends on the @openzeppelin/contracts v5.2.0</code>, @solarity/solidity-lib v3.2.0</code> and solady v0.1.23</code>.</p>
</blockquote>
Security Considerations</h2>
Among potential security issues, the following can be noted:</p>
The security of the SPVGateway</code> is directly dependent on the security of Bitcoin's underlying PoW consensus. A successful 51% attack on the Bitcoin network would allow an attacker to submit fraudulent block headers that would be accepted by the contract, compromising its state.</p>
The block header validation rules require a Bitcoin node to check that the newly created block is not more than 2 hours ahead of the node's network-adjusted time. This check is impossible to implement on the SPVGateway</code> smart contract, hence it is omitted.</p>
Unlike other blockchain systems with deterministic finality, Bitcoin's consensus is probabilistic. The SPVGateway</code> contract SHOULD be designed to handle chain reorganizations of arbitrary depth, but it cannot prevent them. As a result, transactions included in a block may not be permanently final. All dApps and protocols relying on this contract MUST implement their own security policies to determine a sufficient number of block confirmations before a transaction is considered "final" for their specific use case.</p>
While the addBlockHeader</code> function is permissionless and validates each new header cryptographically, the contract's initial state (its starting block header, height, and cumulative PoW) is a point of trust. The integrity of the entire chain history within the contract is built upon the correctness of this initial data. Although the EIP's design allows for flexible bootstrapping, the responsibility for verifying the initial state falls on the community and the dApps that choose to use a specific deployment of the SPVGateway</code>.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Agent Coordination Framework
2025-08-02T00:00:00+00:00
Abstract</h2>
ERC-8001</a> defines a minimal, single-chain primitive for multi-party agent coordination</strong>. An initiator posts an intent and each participant provides a verifiable acceptance attestation. Once the required set of acceptances is present and fresh, the intent is executable. The standard specifies typed data, lifecycle, mandatory events, and verification rules compatible with EIP-712</a>, ERC-1271</a>, EIP-2098</a>, and EIP-5267</a>.</p>
ERC-8001</a> omits privacy, reputation, threshold policies, bonding, and cross-chain semantics. Those are expected as optional modules that reference this specification.</p>
Motivation</h2>
Agents in DeFi/MEV/Web3 Gaming and Agentic Commerce often need to act together without a trusted coordinator. Existing intent standards (e.g., ERC-7521</a>, ERC-7683</a>) define single-initiator flows and do not specify multi-party agreement.</p>
ERC-8001</a> specifies the smallest on-chain primitive for that gap: an initiator's EIP-712</a> intent plus per-participant EIP-712</a>/EIP-1271</a> acceptances. The intent becomes executable only when the required set of acceptances is present and unexpired. Canonical (sorted-unique) participant lists and standard typed data provide replay safety and wallet compatibility. Privacy, thresholds, bonding, and cross-chain are left to modules.</p>
Specification</h2>
The keywords “MUST”, “SHOULD”, and “MAY” are to be interpreted as described in RFC 2119 and RFC 8174.</p>
Implementations MUST expose the following canonical status codes for getCoordinationStatus</code>:</p>
Status Codes</h3>
Implementations MUST use the canonical enum defined below:</p>
enum</span> Status</span> {</span> None</span>,</span> Proposed</span>,</span> Ready</span>,</span> Executed</span>,</span> Cancelled</span>,</span> Expired</span> }</span></span></code></pre>


None</code> = default zero state (intent not found)</p>
</li>

Proposed</code> = intent proposed, not all acceptances yet</p>
</li>

Ready</code> = all participants have accepted, intent executable</p>
</li>

Executed</code> = intent successfully executed</p>
</li>

Cancelled</code> = intent explicitly cancelled</p>
</li>

Expired</code> = intent expired before execution</p>
</li>
</ul>
Overview</h3>
This ERC specifies:</p>

A canonicalised EIP-712 domain for agent coordination,</li>
Typed data structures (AgentIntent</code>, CoordinationPayload</code>, AcceptanceAttestation</code>),</li>
Deterministic hashing rules,</li>
A standard interface (IAgentCoordination</code>),</li>
Lifecycle semantics (propose → accept → execute/cancel),</li>
Error surface and status codes.</li>
</ul>
EIP-712 Domain</h3>
Implementations MUST use the following EIP-712 domain:</p>
{name: "ERC-8001", version: "1", chainId, verifyingContract}</span></span></code></pre>
Implementations SHOULD expose the domain via ERC-5267</a>.</p>
Primary Types</h3>
struct</span> AgentIntent</span> {</span></span>
    bytes32</span> payloadHash</span>;</span>           //</span> keccak256(CoordinationPayload)</span></span>
    uint64</span>  expiry</span>;</span>                //</span> unix seconds; MUST be > block.timestamp at propose</span></span>
    uint64</span>  nonce</span>;</span>                 //</span> per-agent nonce; MUST be > agentNonces[agentId]</span></span>
    address</span> agentId</span>;</span>               //</span> initiator and signer of the intent</span></span>
    bytes32</span> coordinationType</span>;</span>      //</span> domain-specific type id, e.g. keccak256("MEV_SANDWICH_COORD_V1")</span></span>
    uint256</span> coordinationValue</span>;</span>     //</span> informational in Core; modules MAY bind value</span></span>
    address</span>[</span>]</span> participants</span>;</span>        //</span> unique, ascending; MUST include agentId</span></span>
}</span></span>
</span>
struct</span> CoordinationPayload</span> {</span></span>
    bytes32</span> version</span>;</span>               //</span> payload format id</span></span>
    bytes32</span> coordinationType</span>;</span>      //</span> MUST equal AgentIntent.coordinationType</span></span>
    bytes</span>   coordinationData</span>;</span>      //</span> opaque to Core</span></span>
    bytes32</span> conditionsHash</span>;</span>        //</span> domain-specific</span></span>
    uint256</span> timestamp</span>;</span>             //</span> creation time (informational)</span></span>
    bytes</span>   metadata</span>;</span>              //</span> optional</span></span>
}</span></span>
</span>
struct</span> AcceptanceAttestation</span> {</span></span>
    bytes32</span> intentHash</span>;</span>            //</span> getIntentHash(intent)</span></span>
    address</span> participant</span>;</span>           //</span> signer</span></span>
    uint64</span>  nonce</span>;</span>                 //</span> optional in Core; see Nonces</span></span>
    uint64</span>  expiry</span>;</span>                //</span> acceptance validity; MUST be > now at accept and execute</span></span>
    bytes32</span> conditionsHash</span>;</span>        //</span> participant constraints</span></span>
    bytes</span>   signature</span>;</span>             //</span> ECDSA (65 or 64 bytes) or ERC-1271</span></span>
}</span></span></code></pre>Typed Data Hashes</h3>
</span>
bytes32</span> constant</span> AGENT_INTENT_TYPEHASH </span>=</span> keccak256</span>(</span></span>
  "AgentIntent(bytes32 payloadHash,uint64 expiry,uint64 nonce,address agentId,bytes32 coordinationType,uint256 coordinationValue,address[] participants)"</span></span>
)</span>;</span></span>
</span>
bytes32</span> constant</span> ACCEPTANCE_TYPEHASH </span>=</span> keccak256</span>(</span></span>
//</span> Field names MUST exactly match the Solidity struct.</span></span>
  "AcceptanceAttestation(bytes32 intentHash,address participant,uint64 nonce,uint64 expiry,bytes32 conditionsHash)"</span></span>
)</span>;</span></span>
</span>
//</span> participants MUST be unique and strictly ascending by uint160(address).</span></span>
  function</span> _participantsHash</span>(</span>address</span>[</span>]</span> memory</span> ps</span>)</span> internal</span> pure</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
    return</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>ps</span>)</span>)</span>;</span></span>
  }</span></span>
</span>
  function</span> _agentIntentStructHash</span>(</span>AgentIntent</span> calldata</span> i</span>)</span> internal</span> pure</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
    return</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span>
      AGENT_INTENT_TYPEHASH</span>,</span></span>
      i</span>.</span>payloadHash</span>,</span></span>
      i</span>.</span>expiry</span>,</span></span>
      i</span>.</span>nonce</span>,</span></span>
      i</span>.</span>agentId</span>,</span></span>
      i</span>.</span>coordinationType</span>,</span></span>
      i</span>.</span>coordinationValue</span>,</span></span>
      _participantsHash</span>(</span>i</span>.</span>participants</span>)</span></span>
    )</span>)</span>;</span></span>
  }</span></span>
</span>
//</span> Full EIP-712 digest for the initiator’s signature.</span></span>
  function</span> _agentIntentDigest</span>(</span>bytes32</span> domainSeparator</span>,</span> AgentIntent</span> calldata</span> i</span>)</span> internal</span> pure</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
    return</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>"\x19\x01"</span>,</span> domainSeparator</span>,</span> _agentIntentStructHash</span>(</span>i</span>)</span>)</span>)</span>;</span></span>
  }</span></span>
</span>
  function</span> _acceptanceStructHash</span>(</span>AcceptanceAttestation</span> calldata</span> a</span>)</span> internal</span> pure</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
    //</span> a.intentHash MUST be the AgentIntent struct hash, not the digest.</span></span>
    return</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span>
      ACCEPTANCE_TYPEHASH</span>,</span></span>
      a</span>.</span>intentHash</span>,</span></span>
      a</span>.</span>participant</span>,</span></span>
      a</span>.</span>nonce</span>,</span></span>
      a</span>.</span>expiry</span>,</span></span>
      a</span>.</span>conditionsHash</span></span>
    )</span>)</span>;</span></span>
  }</span></span>
</span>
  function</span> _acceptanceDigest</span>(</span>bytes32</span> domainSeparator</span>,</span> AcceptanceAttestation</span> calldata</span> a</span>)</span> internal</span> pure</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
    return</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>"\x19\x01"</span>,</span> domainSeparator</span>,</span> _acceptanceStructHash</span>(</span>a</span>)</span>)</span>)</span>;</span></span>
  }</span></span>
</span></code></pre>
Computation (normative):</p>
participantsHash </span>=</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>participants</span>)</span>)</span>;</span> //</span> sorted unique</span></span>
intentStructHash </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span>
  AGENT_INTENT_TYPEHASH</span>,</span></span>
  payloadHash</span>,</span> expiry</span>,</span> nonce</span>,</span> agentId</span>,</span> coordinationType</span>,</span> coordinationValue</span>,</span> participantsHash</span></span>
)</span>)</span>;</span></span>
intentDigest </span>=</span> keccak256</span>(</span>"\x19\x01"</span> ||</span> domainSeparator </span>||</span> intentStructHash</span>)</span>;</span></span>
</span></code></pre>
Clarifications (normative):</p>

getIntentHash(intent)</code> MUST return intentStructHash</code> (struct hash), not the full digest.</li>
AcceptanceAttestation.intentHash</code> MUST be that struct hash.</li>
Each acceptance is signed over its own EIP-712 digest that includes this field.</li>
participants</code> MUST be strictly ascending by uint160(address)</code> and deduplicated.</li>
</ul>
Interface</h3>
Implementations MUST</strong> expose the following interface and events.</p>
interface</span> IAgentCoordination</span> {</span></span>
    event</span> CoordinationProposed</span>(</span>bytes32</span> indexed</span> intentHash</span>, </span>address</span> indexed</span> proposer</span>, </span>bytes32</span> coordinationType</span>, </span>uint256</span> participantCount</span>, </span>uint256</span> coordinationValue</span>)</span>;</span></span>
    event</span> CoordinationAccepted</span>(</span>bytes32</span> indexed</span> intentHash</span>, </span>address</span> indexed</span> participant</span>, </span>bytes32</span> acceptanceHash</span>, </span>uint256</span> acceptedCount</span>, </span>uint256</span> requiredCount</span>)</span>;</span></span>
    event</span> CoordinationExecuted</span>(</span>bytes32</span> indexed</span> intentHash</span>, </span>address</span> indexed</span> executor</span>, </span>bool</span> success</span>, </span>uint256</span> gasUsed</span>, </span>bytes</span> result</span>)</span>;</span></span>
    event</span> CoordinationCancelled</span>(</span>bytes32</span> indexed</span> intentHash</span>, </span>address</span> indexed</span> canceller</span>, </span>string</span> reason</span>, </span>uint8</span> finalStatus</span>)</span>;</span></span>
</span>
    function</span> proposeCoordination</span>(</span>AgentIntent</span> calldata</span> intent</span>,</span> bytes</span> calldata</span> signature</span>,</span> CoordinationPayload</span> calldata</span> payload</span>)</span> external</span> returns</span> (</span>bytes32</span> intentHash</span>)</span>;</span></span>
    function</span> acceptCoordination</span>(</span>bytes32</span> intentHash</span>,</span> AcceptanceAttestation</span> calldata</span> attestation</span>)</span> external</span> returns</span> (</span>bool</span> allAccepted</span>)</span>;</span></span>
    function</span> executeCoordination</span>(</span>bytes32</span> intentHash</span>,</span> CoordinationPayload</span> calldata</span> payload</span>,</span> bytes</span> calldata</span> executionData</span>)</span> external</span> returns</span> (</span>bool</span> success</span>,</span> bytes</span> memory</span> result</span>)</span>;</span></span>
    function</span> cancelCoordination</span>(</span>bytes32</span> intentHash</span>,</span> string</span> calldata</span> reason</span>)</span> external</span>;</span></span>
</span>
    function</span> getCoordinationStatus</span>(</span>bytes32</span> intentHash</span>)</span> external</span> view</span> returns</span> (</span>Status</span> status</span>,</span> address</span> proposer</span>,</span> address</span>[</span>]</span> memory</span> participants</span>,</span> address</span>[</span>]</span> memory</span> acceptedBy</span>,</span> uint256</span> expiry</span>)</span>;</span></span>
    function</span> getRequiredAcceptances</span>(</span>bytes32</span> intentHash</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
    function</span> getAgentNonce</span>(</span>address</span> agent</span>)</span> external</span> view</span> returns</span> (</span>uint64</span>)</span>;</span></span>
}</span></span></code></pre>Semantics</h3>
The functions defined in this specification MUST exhibit the following externally observable behaviours.

This standard does NOT prescribe storage layout, execution model, or internal mechanisms.</p>
proposeCoordination</code></h4>
proposeCoordination</code> MUST revert if:</p>

the signature does not validate the supplied AgentIntent</code> under the ERC-8001 EIP-712 domain;</li>
intent.expiry <= block.timestamp</code>;</li>
intent.nonce</code> is not strictly greater than getAgentNonce(intent.agentId)</code>;</li>
participants</code> is not strictly ascending and unique;</li>
intent.agentId</code> is not included in the participants list.</li>
</ul>
If valid:</p>

CoordinationProposed</code> MUST be emitted;</li>
getCoordinationStatus</code> MUST report Proposed</code>;</li>
getAgentNonce(intent.agentId)</code> MUST equal the supplied nonce;</li>
getRequiredAcceptances(intentHash)</code> MUST equal the number of participants.</li>
</ul>
acceptCoordination</code></h4>
acceptCoordination</code> MUST revert if:</p>

the intent does not exist or has expired;</li>
the caller is not listed as a participant;</li>
the participant has already accepted;</li>
the attestation signature does not validate under the ERC-8001 domain;</li>
attestation.expiry <= block.timestamp</code>.</li>
</ul>
If valid:</p>

CoordinationAccepted</code> MUST be emitted;</li>
the participant MUST appear in the acceptedBy</code> list returned by getCoordinationStatus</code>;</li>
if all participants have accepted:

the function MUST return true</code>;</li>
status MUST be Ready</code>.</li>
</ul>
</li>
</ul>
Otherwise the function MUST return false</code>.</p>
executeCoordination</code></h4>
executeCoordination</code> MUST revert if:</p>

the intent is not in Ready</code> state;</li>
intent.expiry <= block.timestamp</code>;</li>
any acceptance has expired;</li>
the supplied payload does not hash to payloadHash</code>.</li>
</ul>
If valid:</p>

the implementation MUST attempt execution of the behaviour represented by executionData</code>;</li>
the function MUST return (success, result)</code>;</li>
CoordinationExecuted</code> MUST be emitted;</li>
getCoordinationStatus</code> MUST report Executed</code>.</li>
</ul>
cancelCoordination</code></h4>

If the intent has not expired, only the proposer MUST be permitted to cancel.</li>
After expiry, any caller MUST be permitted to cancel.</li>
</ul>
On success:</p>

CoordinationCancelled</code> MUST be emitted;</li>
status MUST be Cancelled</code>.</li>
</ul>
getCoordinationStatus</code></h4>
getCoordinationStatus(intentHash)</code> MUST return:</p>

None</code> if the intent does not exist;</li>
Proposed</code> if not all participants have accepted and the intent has not expired;</li>
Ready</code> if all participants have accepted and expiries have not elapsed;</li>
Executed</code> if execution has occurred;</li>
Cancelled</code> if cancellation has occurred;</li>
Expired</code> if the intent has expired and was not executed or cancelled.</li>
</ul>
Nonces</h4>

getAgentNonce(agent)</code> MUST increase for every valid new intent.</li>
proposeCoordination</code> MUST reject nonces not strictly greater than the stored nonce.</li>
Acceptance-level nonces MAY be implemented; if so, they MUST be strictly monotonic per participant.</li>
</ul>
Errors</h3>
Implementations SHOULD revert with descriptive custom errors (or equivalent revert strings) for the following baseline conditions, and MAY define additional errors for domain-specific modules (e.g. slashing, reputation, or privacy conditions):</p>

Expired intent</li>
Bad signature</li>
Non-participant</li>
Duplicate acceptance</li>
Acceptance expired at execute</li>
Payload hash mismatch</li>
</ul>
error</span> ERC8001_NotProposer</span>(</span>)</span>;</span></span>
error</span> ERC8001_ExpiredIntent</span>(</span>)</span>;</span></span>
error</span> ERC8001_ExpiredAcceptance</span>(</span>address</span> participant</span>)</span>;</span></span>
error</span> ERC8001_BadSignature</span>(</span>)</span>;</span></span>
error</span> ERC8001_NotParticipant</span>(</span>)</span>;</span></span>
error</span> ERC8001_DuplicateAcceptance</span>(</span>)</span>;</span></span>
error</span> ERC8001_ParticipantsNotCanonical</span>(</span>)</span>;</span></span>
error</span> ERC8001_NonceTooLow</span>(</span>)</span>;</span></span>
error</span> ERC8001_PayloadHashMismatch</span>(</span>)</span>;</span></span>
error</span> ERC8001_NotReady</span>(</span>)</span>;</span></span></code></pre>Rationale</h2>

Sorted participant lists remove hash malleability and allow off-chain deduplication.</li>
Separation of intent and acceptance allows off-chain collation and a single on-chain check.</li>
Keeping ERC-8001</a> single-chain avoids coupling to bridge semantics and keeps the primitive audit-friendly.</li>
Wallet friendliness: EIP-712 arrays let signers see actual participant addresses.</li>
</ul>
Backwards Compatibility</h2>
ERC-8001</a> introduces a new interface. It is compatible with EOA and contract wallets via ECDSA and ERC-1271. It does not modify existing standards.</p>
Reference Implementation</h2>
A permissive reference implementation is provided in contracts/AgentCoordination.sol</code></a>. It uses a minimal ECDSA helper and supports ERC-1271 signers. It enforces participant canonicalisation, intent nonces, acceptance freshness, and all-participants policy.</p>
Security Considerations</h2>

Replay</strong>: EIP-712 domain binding and monotonic nonces prevent cross-contract replay.</li>
Malleability</strong>: Low-s enforcement and 64/65-byte signature support are required.</li>
Equivocation</strong>: A participant can sign conflicting intents. Mitigate with module-level slashing or reputation.</li>
Liveness</strong>: Enforce TTL on both intent and acceptances. Executors should ensure enough time remains.</li>
MEV</strong>: If coordinationData</code> reveals strategy, use a Privacy module with commit-reveal or encryption.</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Purpose-Bound ERC-20 with Conditional Unlock
2025-07-29T00:00:00+00:00
Abstract</h2>
This ERC extends the concept introduced in ERC-7291</a> by enabling ERC-20</a>-compatible tokens to carry multi-condition unlocking constraints, combining temporal, identity, and usage restrictions into a programmable structure. It aims to support controlled disbursement of tokens where funds are only accessible under predefined, auditable, and verifiable conditions.</p>
Motivation</h2>
ERC-7291 introduced purpose-bound money by restricting how and where tokens can be spent. However, many real-world applications require multiple conditions to be satisfied simultaneously before tokens can be used. Examples include:</p>

Scholarships requiring the recipient to be KYC-verified, under 25 years of age, and registered at a university.</li>
NGO aid to be used only for food and medicine, after a specific unlock date.</li>
Payroll tokens that unlock monthly and only for whitelisted vendors (e.g., banks, healthcare providers).</li>
</ul>
This proposal generalizes and formalizes such use cases by layering unlocking conditions on top of the ERC-20 standard.</p>
Specification</h2>
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.</p>
Interface</h3>
The IPurposeBoundERC20</code> interface defines the standard for programmable token transfers that are conditional. Each transfer, referred to as a purpose binding</em>, includes:</p>

A recipient</code> and amount</code>.</li>
A set of UnlockCondition</code> objects, each consisting of a conditionType</code> (like "TIME"</code>, "KYC"</code>, or "WHITELIST"</code>) and conditionData</code> used to evaluate the condition.</li>
An optional expiry</code> timestamp after which the transfer can no longer be claimed.</li>
</ul>
The interface provides the following functions:</p>

bindPurpose(...)</code>: Locks a specified amount of tokens to a recipient with defined conditions.</li>
claim(...)</code>: Allows the recipient to claim the tokens once all conditions are fulfilled.</li>
isUnlocked(...)</code>: Returns whether all associated conditions have been satisfied.</li>
</ul>
This enables flexible, composable transfer mechanisms for various use cases including compliance, grants, payroll, and more.</p>
pragma</span> solidity</span> 0.8.23</span>;</span></span>
</span>
interface</span> IPurposeBoundERC20</span> {</span></span>
    struct</span> UnlockCondition</span> {</span></span>
        bytes32</span> conditionType</span>;</span> //</span> e.g., "TIME", "KYC", "WHITELIST"</span></span>
        bytes</span> conditionData</span>;</span>   //</span> e.g., timestamp, Merkle root, etc.</span></span>
    }</span></span>
</span>
    function</span> bindPurpose</span>(</span></span>
        address</span> recipient</span>,</span></span>
        uint256</span> amount</span>,</span></span>
        UnlockCondition</span>[</span>]</span> calldata</span> conditions</span>,</span></span>
        uint256</span> expiry</span></span>
    )</span> external</span> returns</span> (</span>bytes32</span> bindingId</span>)</span>;</span></span>
</span>
    function</span> claim</span>(</span>bytes32</span> bindingId</span>)</span> external</span>;</span></span>
</span>
    function</span> isUnlocked</span>(</span>bytes32</span> bindingId</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
}</span></span></code></pre>Rationale</h2>
Flexibility: Conditions are modular and extensible.</p>
Composability: Can be integrated into DAOs, payroll, education, and compliance tokens.</p>
Security: Off-chain verification (e.g., KYC) backed by on-chain proofs (e.g., Merkle roots).</p>
Reference Implementation</h2>
pragma</span> solidity</span> 0.8.23</span>;</span></span>
</span>
///</span> @title</span> Reference Implementation - Purpose-Bound ERC20 with Multi-Condition Unlocking</span></span>
///</span> @notice</span> Implements IPurposeBoundERC20 with conditionType mapping to on-chain checkers.</span></span>
</span>
import</span> "@openzeppelin/contracts/token/ERC20/ERC20.sol"</span>;</span></span>
import</span> "./IPurposeBoundERC20.sol"</span>;</span></span>
</span>
///</span> @dev</span> Interface for pluggable condition checker contracts</span></span>
interface</span> IConditionChecker</span> {</span></span>
    function</span> isConditionMet</span>(</span>address</span> recipient</span>,</span> bytes</span> calldata</span> conditionData</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
}</span></span>
</span>
///</span> @title</span> PurposeBoundERC20 Implementation</span></span>
contract</span> PurposeBoundERC20</span> is</span> ERC20</span>, </span>IPurposeBoundERC20</span> {</span></span>
    struct</span> StoredBinding</span> {</span></span>
        address</span> recipient</span>;</span></span>
        uint256</span> amount</span>;</span></span>
        UnlockCondition</span>[</span>]</span> conditions</span>;</span></span>
        bool</span> claimed</span>;</span></span>
        uint256</span> expiry</span>;</span></span>
    }</span></span>
</span>
    ///</span> @dev</span> Maps conditionType → on-chain checker contract</span></span>
    mapping</span>(</span>bytes32</span> =></span> address</span>)</span> public</span> conditionResolvers</span>;</span></span>
</span>
    ///</span> @dev</span> Maps bindingId → locked transfer</span></span>
    mapping</span>(</span>bytes32</span> =></span> StoredBinding</span>)</span> public</span> boundTransfers</span>;</span></span>
</span>
    event</span> PurposeBound</span>(</span>bytes32</span> indexed</span> bindingId</span>, </span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> amount</span>)</span>;</span></span>
    event</span> Claimed</span>(</span>bytes32</span> indexed</span> bindingId</span>, </span>address</span> indexed</span> recipient</span>)</span>;</span></span>
</span>
    constructor</span>(</span>string</span> memory</span> name_</span>,</span> string</span> memory</span> symbol_</span>)</span> ERC20</span>(</span>name_, symbol_) </span>{</span></span>
        _mint</span>(</span>msg.sender</span>,</span> 1_000_000</span> ether</span>)</span>;</span> //</span> for demo purposes</span></span>
    }</span></span>
</span>
    ///</span> @notice</span> Admin can register or update condition checkers for condition types</span></span>
    function</span> setConditionResolver</span>(</span>bytes32</span> conditionType</span>,</span> address</span> checker</span>)</span> external</span> {</span></span>
        //</span> For demo purposes: public function. In production: onlyOwner or AccessControl.</span></span>
        conditionResolvers</span>[</span>conditionType</span>]</span> =</span> checker</span>;</span></span>
    }</span></span>
</span>
    ///</span> @inheritdoc</span> IPurposeBoundERC20</span></span>
    function</span> bindPurpose</span>(</span></span>
        address</span> recipient</span>,</span></span>
        uint256</span> amount</span>,</span></span>
        UnlockCondition</span>[</span>]</span> calldata</span> conditions</span>,</span></span>
        uint256</span> expiry</span></span>
    )</span> external</span> override</span> returns</span> (</span>bytes32</span> bindingId</span>)</span> {</span></span>
        require</span>(</span>recipient </span>!=</span> address</span>(</span>0</span>)</span>,</span> "Invalid recipient"</span>)</span>;</span></span>
        require</span>(</span>amount </span>></span> 0</span>,</span> "Invalid amount"</span>)</span>;</span></span>
</span>
        bindingId </span>=</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>msg.sender</span>,</span> recipient</span>,</span> amount</span>,</span> conditions</span>,</span> expiry</span>,</span> block</span>.</span>timestamp</span>)</span>)</span>;</span></span>
        StoredBinding </span>storage</span> stored </span>=</span> boundTransfers</span>[</span>bindingId</span>]</span>;</span></span>
        require</span>(</span>stored</span>.</span>amount </span>==</span> 0</span>,</span> "Binding exists"</span>)</span>;</span></span>
</span>
        _transfer</span>(</span>msg.sender</span>,</span> address</span>(</span>this</span>)</span>,</span> amount</span>)</span>;</span></span>
</span>
        for</span> (</span>uint</span> i </span>=</span> 0</span>;</span> i </span><</span> conditions</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span>
            stored</span>.</span>conditions</span>.</span>push</span>(</span>conditions</span>[</span>i</span>]</span>)</span>;</span></span>
        }</span></span>
</span>
        stored</span>.</span>recipient </span>=</span> recipient</span>;</span></span>
        stored</span>.</span>amount </span>=</span> amount</span>;</span></span>
        stored</span>.</span>expiry </span>=</span> expiry</span>;</span></span>
</span>
        emit</span> PurposeBound</span>(</span>bindingId</span>,</span> msg.sender</span>,</span> recipient</span>,</span> amount</span>)</span>;</span></span>
    }</span></span>
</span>
    ///</span> @inheritdoc</span> IPurposeBoundERC20</span></span>
    function</span> isUnlocked</span>(</span>bytes32</span> bindingId</span>)</span> public</span> view</span> override</span> returns</span> (</span>bool</span>)</span> {</span></span>
        StoredBinding </span>storage</span> binding </span>=</span> boundTransfers</span>[</span>bindingId</span>]</span>;</span></span>
        if</span> (</span>binding</span>.</span>claimed</span>)</span> return</span> false</span>;</span></span>
        if</span> (</span>binding</span>.</span>expiry </span>></span> 0</span> &&</span> block</span>.</span>timestamp </span>></span> binding</span>.</span>expiry</span>)</span> return</span> false</span>;</span></span>
</span>
        for</span> (</span>uint</span> i </span>=</span> 0</span>;</span> i </span><</span> binding</span>.</span>conditions</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span>
            UnlockCondition </span>storage</span> cond </span>=</span> binding</span>.</span>conditions</span>[</span>i</span>]</span>;</span></span>
            address</span> checker </span>=</span> conditionResolvers</span>[</span>cond</span>.</span>conditionType</span>]</span>;</span></span>
            require</span>(</span>checker </span>!=</span> address</span>(</span>0</span>)</span>,</span> "Checker not set"</span>)</span>;</span></span>
            if</span> (</span>!</span>IConditionChecker</span>(</span>checker</span>)</span>.</span>isConditionMet</span>(</span>binding</span>.</span>recipient</span>,</span> cond</span>.</span>conditionData</span>)</span>)</span> {</span></span>
                return</span> false</span>;</span></span>
            }</span></span>
        }</span></span>
</span>
        return</span> true</span>;</span></span>
    }</span></span>
</span>
    ///</span> @inheritdoc</span> IPurposeBoundERC20</span></span>
    function</span> claim</span>(</span>bytes32</span> bindingId</span>)</span> external</span> override</span> {</span></span>
        StoredBinding </span>storage</span> binding </span>=</span> boundTransfers</span>[</span>bindingId</span>]</span>;</span></span>
        require</span>(</span>msg.sender</span> ==</span> binding</span>.</span>recipient</span>,</span> "Not recipient"</span>)</span>;</span></span>
        require</span>(</span>!</span>binding</span>.</span>claimed</span>,</span> "Already claimed"</span>)</span>;</span></span>
        require</span>(</span>isUnlocked</span>(</span>bindingId</span>)</span>,</span> "Conditions not met"</span>)</span>;</span></span>
</span>
        binding</span>.</span>claimed </span>=</span> true</span>;</span></span>
        _transfer</span>(</span>address</span>(</span>this</span>)</span>,</span> binding</span>.</span>recipient</span>,</span> binding</span>.</span>amount</span>)</span>;</span></span>
</span>
        emit</span> Claimed</span>(</span>bindingId</span>,</span> binding</span>.</span>recipient</span>)</span>;</span></span>
    }</span></span>
}</span></span>
</span>
///</span> @dev</span> Example of Time-Based Condition Checker</span></span>
contract</span> TimeConditionChecker</span> is</span> IConditionChecker</span> {</span></span>
    function</span> isConditionMet</span>(</span>address</span>,</span> bytes</span> calldata</span> conditionData</span>)</span> external</span> view</span> override</span> returns</span> (</span>bool</span>)</span> {</span></span>
        uint256</span> unlockTime </span>=</span> abi</span>.</span>decode</span>(</span>conditionData</span>,</span> (</span>uint256</span>)</span>)</span>;</span></span>
        return</span> block</span>.</span>timestamp </span>></span>=</span> unlockTime</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Security Considerations</h2>
Condition-checking mechanisms (e.g., Merkle roots, timestamps) must be secure against tampering.</p>
The claim()</code> function must ensure atomic verification of all conditions.</p>
Replay attacks must be mitigated using unique binding IDs and expiration fields.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Verifiable ML Model Inference (ZKML)
2025-07-23T00:00:00+00:00
Abstract</h2>
This ERC standardizes how smart contracts reference machine-learning (ML) models and accept zero-knowledge attestations of their inferences. It defines a registry that issues a modelId</code> for a ModelCommitment</code>, hashes of the model’s weights/architecture, proving circuit/AIR, and verifying key, along with a proofSystemId</code> for the proving system, and exposes discoverability via ERC-165</a>. A verifier interface provides verifyInference(modelId, inputCommitment, output, proof)</code>: it retrieves the model commitment, dispatches verification to the declared proof system, and reverts on any mismatch or invalid proof; success implies validity and emits InferenceVerified</code>. Inputs are bound by domain-separated commitments (nonceable for replay protection), outputs are ABI-encoded bytes whose schema can be application-defined or additionally committed on-chain, and proof systems (e.g., Groth16/Plonk/STARK) are pluggable without ABI changes. An optional extension persists verified inference records to enable auditability and deterministic settlement.</p>
Motivation</h2>
Smart contracts can’t run large ML models, and they can’t trust an oracle’s claim about a model’s output.
Today, projects either (1) trust a centralized server, (2) cripple models to fit on-chain,  or (3) rely on social committees. None provide cryptographic assurance.</p>
Zero-knowledge ML (ZKML) fixes the trust gap by letting a prover show—succinctly and privately—that a specific model, with specific inputs, produced a specific output.
But without a shared interface, every dApp/verifier pair is bespoke: different ABIs, different registry schemas, poor composability.</p>
This ERC standardizes that on-chain boundary:</p>

Registry: publish immutable commitments to model weights/architecture/circuits so callers know exactly which model they’re referencing.</li>
Verifier: a uniform function to validate inference proofs, independent of proof system (Groth16, Plonk, STARKs, …).</li>
</ul>
Benefits include:</p>

Trustless, composable “AI oracles” for DeFi risk, prediction markets, insurance, etc.</li>
Protection of proprietary models and private inputs while still guaranteeing correctness.</li>
Deterministic, dispute-free settlement for complex computations.</li>
Lower integration and audit overhead via consistent events, structs, and revert semantics.</li>
Future-proofing as proving systems evolve—only implementations change, not integrators.</li>
Clear security expectations (e.g., nonce usage to prevent replays) baked into the spec.</li>
</ul>
In short, this ERC turns verifiable ML inference into a reusable primitive—doing for AI outputs what ERC-20</a>/ERC-721</a> did for assets.</p>
Specification</h2>
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</a> and RFC 8174</a>.</p>
Terminology & IDs</h3>

Model Commitment: A bundle of hashes that ties together the model’s weights, architecture, proving circuit/Algebraic intermediate representation (AIR), and verifying key.</li>
modelId</code> (uint256</code>): A unique identifier returned by the registry upon model registration.</li>
inputCommitment</code> (bytes32</code>): A hash commitment to all private inputs (and any declared public inputs) for an inference. Implementations MUST domain-separate and SHOULD include a nonce/salt when single-use or non-deterministic behavior is possible.</li>
output</code> (bytes</code>): ABI-encoded public outputs of the inference. Consumers MUST agree on its schema and MAY validate it via an outputCommitment (not included in the minimal interface).</li>
proof</code> (bytes</code>): The ZK proof blob.</li>
proofSystemId</code> (bytes4</code>): Identifier of the proving system + curve + version used by the circuit.</li>
</ul>
proofSystemId</code> MUST equal the first four bytes of:</p>
bytes4(keccak256(abi.encodePacked(<canonical-proof-system-name-and-version>)))</code></p>
Where <canonical-proof-system-name-and-version></code> is a lowercase, hyphen-separated string, e.g.:</p>

"groth16-bn254-v1"</li>
"plonk-bn254-v2"</li>
"stark-airfoo-v1"</li>
</ul>
This method ensures deterministic, collision-resistant identifiers across implementations.</p>
Interfaces</h3>
ZKML Registry</h4>
//</span> SPDX-License-Identifier: CC0-1.0</span></span>
pragma</span> solidity</span> ^0.8.20</span>;</span></span>
</span>
interface</span> IERCZKMLRegistry</span> /*</span> is IERC165 </span>*/</span> {</span></span>
    struct</span> ModelCommitment</span> {</span></span>
        bytes32</span> modelHash</span>;</span>     //</span> weights + architecture hash</span></span>
        bytes32</span> circuitHash</span>;</span>   //</span> arithmetic circuit / AIR hash</span></span>
        bytes32</span> vkHash</span>;</span>        //</span> verifying key hash</span></span>
        bytes4</span>  proofSystemId</span>;</span> //</span> keccak-based identifier</span></span>
        string</span>  uri</span>;</span>           //</span> optional off-chain metadata (IPFS/HTTP)</span></span>
    }</span></span>
</span>
    event</span> ModelRegistered</span>(</span></span>
        uint256</span> indexed</span> modelId</span>,</span></span>
        address</span> indexed</span> owner</span>,</span></span>
        ModelCommitment</span> commitment</span></span>
    )</span>;</span></span>
</span>
    event</span> ModelUpdated</span>(</span></span>
        uint256</span> indexed</span> modelId</span>,</span></span>
        ModelCommitment</span> oldCommitment</span>,</span></span>
        ModelCommitment</span> newCommitment</span></span>
    )</span>;</span></span>
</span>
    event</span> ModelDeprecated</span>(</span>uint256</span> indexed</span> modelId</span>)</span>;</span></span>
</span>
    error</span> ModelNotFound</span>(</span>uint256</span> modelId</span>)</span>;</span></span>
    error</span> NotModelOwner</span>(</span>uint256</span> modelId</span>,</span> address</span> caller</span>)</span>;</span></span>
    error</span> ModelDeprecated</span>(</span>uint256</span> modelId</span>)</span>;</span></span>
</span>
    function</span> registerModel</span>(</span>ModelCommitment</span> calldata</span> commitment</span>)</span></span>
        external</span></span>
        returns</span> (</span>uint256</span> modelId</span>)</span>;</span></span>
</span>
    function</span> updateModel</span>(</span>uint256</span> modelId</span>,</span> ModelCommitment</span> calldata</span> newCommitment</span>)</span></span>
        external</span>;</span></span>
</span>
    function</span> deprecateModel</span>(</span>uint256</span> modelId</span>)</span> external</span>;</span></span>
</span>
    function</span> getModel</span>(</span>uint256</span> modelId</span>)</span></span>
        external</span></span>
        view</span></span>
        returns</span> (</span>ModelCommitment</span> memory</span> commitment</span>,</span> bool</span> deprecated</span>,</span> address</span> owner</span>)</span>;</span></span>
}</span></span></code></pre>

registerModel</code> MUST return a unique modelId</code>.</li>
updateModel</code> and deprecateModel</code> MUST only be callable by the model owner</code>.</li>
getModel</code> MUST return the current commitment</code>, deprecation status, and owner</code> address.</li>
Implementations MAY allow versioning under one modelId</code> or require a new modelId</code> per change. The chosen policy MUST be documented.</li>
</ul>
ZKML Verifier</h4>
//</span> SPDX-License-Identifier: CC0-1.0</span></span>
pragma</span> solidity</span> ^0.8.20</span>;</span></span>
</span>
interface</span> IERCZKMLVerifier</span> /*</span> is IERC165 </span>*/</span> {</span></span>
    event</span> InferenceVerified</span>(</span></span>
        uint256</span> indexed</span> modelId</span>,</span></span>
        bytes32</span> indexed</span> inputCommitment</span>,</span></span>
        bytes</span>   output</span>,</span></span>
        address</span> indexed</span> caller</span></span>
    )</span>;</span></span>
</span>
    error</span> InvalidProof</span>(</span>)</span>;</span></span>
    error</span> ModelMismatch</span>(</span>)</span>;</span>            //</span> proof verifies but not tied to given modelId</span></span>
    error</span> InputCommitmentMismatch</span>(</span>)</span>;</span></span>
    error</span> OutputMismatch</span>(</span>)</span>;</span>           //</span> if verifier checks output commitment/schema</span></span>
    error</span> UnsupportedProofSystem</span>(</span>bytes4</span> proofSystemId</span>)</span>;</span></span>
    error</span> VerificationRefused_ModelDeprecated</span>(</span>uint256</span> modelId</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Verifies a ZK proof for an inference.</span></span>
     * </span>@dev</span> MUST revert on any failure path. Successful execution implies validity.</span></span>
     * </span>@param</span> modelId</span>         Registry model identifier</span></span>
     * </span>@param</span> inputCommitment</span> Commitment to private inputs</span></span>
     * </span>@param</span> output</span>          ABI-encoded public outputs</span></span>
     * </span>@param</span> proof</span>           ZK proof bytes</span></span>
     */</span></span>
    function</span> verifyInference</span>(</span></span>
        uint256</span> modelId</span>,</span></span>
        bytes32</span> inputCommitment</span>,</span></span>
        bytes</span> calldata</span> output</span>,</span></span>
        bytes</span> calldata</span> proof</span></span>
    )</span> external</span>;</span></span>
</span>
    ///</span> Optional helper views:</span></span>
    function</span> proofSystemOf</span>(</span>uint256</span> modelId</span>)</span> external</span> view</span> returns</span> (</span>bytes4</span>)</span>;</span></span>
    function</span> registry</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span> registryAddress</span>)</span>;</span></span>
}</span></span></code></pre>
The verifyInference</code>:</p>

MUST fetch the model commitment</code> from the registry and validate the proof</code> against it.</li>
MUST revert on any failure (invalid proof, mismatched commitments, unsupported proof system, deprecated model, etc.).</li>
SHOULD emit  InferenceVerified</code> on success.</li>
SHOULD remain stateless except for emitting events. Statefulness MAY be introduced by extensions.</li>
</ul>
Optional Storage Extension</h4>
//</span> SPDX-License-Identifier: CC0-1.0</span></span>
pragma</span> solidity</span> ^0.8.20</span>;</span></span>
</span>
interface</span> IERCZKMLStorageExtension</span> {</span></span>
    event</span> InferenceStored</span>(</span>bytes32</span> indexed</span> inferenceId</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Verify and store an inference record.</span></span>
     * </span>@dev</span> MUST revert on invalid proof.</span></span>
     * </span>@return</span> inferenceId</span> keccak256(abi.encodePacked(modelId, inputCommitment, output))</span></span>
     */</span></span>
    function</span> verifyAndStoreInference</span>(</span></span>
        uint256</span> modelId</span>,</span></span>
        bytes32</span> inputCommitment</span>,</span></span>
        bytes</span> calldata</span> output</span>,</span></span>
        bytes</span> calldata</span> proof</span></span>
    )</span> external</span> returns</span> (</span>bytes32</span> inferenceId</span>)</span>;</span></span>
</span>
    function</span> getInference</span>(</span>bytes32</span> inferenceId</span>)</span></span>
        external</span></span>
        view</span></span>
        returns</span> (</span>uint256</span> modelId</span>,</span> bytes32</span> inputCommitment</span>,</span> bytes</span> memory</span> output</span>)</span>;</span></span>
}</span></span></code></pre>
Replay Protection Note: Implementations that rely on
inferenceId = keccak256(modelId, inputCommitment, output)</code>
MUST ensure that inputCommitment</code> embeds a nonce/salt</code> or other uniqueness source
if replays are a concern (e.g., non-deterministic models or single-use inferences).</p>
The registry interface exposes an owner</code> per modelId</code>.
Implementations MUST include some ownership/access-control mechanism
(e.g., simple owner storage, ERC-173</a>, ERC-721</a> representation, or role-based control).
The returned owner</code> address SHOULD be treated as the canonical authority to mutate or deprecate that model.</p>
Rationale</h2>

Void Return on verifyInference</code>: Reverting on failure and returning nothing on success removes redundant gas-expensive booleans and matches modern Solidity patterns (e.g., OpenZeppelin’s SafeERC20</code>).</li>
Separated Registry & Verifier: Encourages modularity—teams can upgrade verifiers or registries independently.</li>
Opaque bytes for Proof/Output: Avoids lock-in to a specific proof system or output schema.</li>
Deterministic proofSystemId</code>: Prevents collisions and ambiguity; enables predictable dispatch in mixed-system verifiers.</li>
Nonce in inputCommitment</code>: Explicitly mitigates replay attacks when inference uniqueness matters.</li>
</ul>
Backwards Compatibility</h2>
Fully backwards compatible:</p>

Uses ERC-165</a> like popular ERC-721</a> or ERC-1155</a> for discoverability.</li>
No dependency on token ownership standards; minimal collision with existing protocols.</li>
</ul>
Reference Implementation</h2>
//</span> SPDX-License-Identifier: CC0-1.0</span></span>
pragma</span> solidity</span> ^0.8.20</span>;</span></span>
</span>
import</span> "./IERCZKMLRegistry.sol"</span>;</span></span>
import</span> "./IERCZKMLVerifier.sol"</span>;</span></span>
</span>
contract</span> ZKMLVerifier</span> is</span> IERCZKMLVerifier</span> {</span></span>
    IERCZKMLRegistry </span>public</span> immutable</span> override</span> registry</span>;</span></span>
</span>
    constructor</span>(</span>IERCZKMLRegistry</span> _registry</span>)</span> {</span></span>
        registry </span>=</span> _registry</span>;</span></span>
    }</span></span>
</span>
    function</span> verifyInference</span>(</span></span>
        uint256</span> modelId</span>,</span></span>
        bytes32</span> inputCommitment</span>,</span></span>
        bytes</span> calldata</span> output</span>,</span></span>
        bytes</span> calldata</span> proof</span></span>
    )</span> external</span> override</span> {</span></span>
        (</span>IERCZKMLRegistry</span>.</span>ModelCommitment </span>memory</span> cm</span>,</span> bool</span> deprecated</span>,</span>)</span> =</span></span>
            registry</span>.</span>getModel</span>(</span>modelId</span>)</span>;</span></span>
</span>
        if</span> (</span>deprecated</span>)</span> revert</span> ModelDeprecated</span>(</span>modelId</span>)</span>;</span></span>
</span>
        //</span> Dispatch based on proofSystemId. Example only.</span></span>
        //</span> bool ok = VerifierLib.verify(proof, cm.vkHash, inputCommitment, output);</span></span>
        bool</span> ok </span>=</span> _dummyVerify</span>(</span>proof</span>,</span> cm</span>.</span>vkHash</span>,</span> inputCommitment</span>,</span> output</span>)</span>;</span></span>
        if</span> (</span>!</span>ok</span>)</span> revert</span> InvalidProof</span>(</span>)</span>;</span></span>
</span>
        emit</span> InferenceVerified</span>(</span>modelId</span>,</span> inputCommitment</span>,</span> output</span>,</span> msg.sender</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> proofSystemOf</span>(</span>uint256</span> modelId</span>)</span> external</span> view</span> override</span> returns</span> (</span>bytes4</span>)</span> {</span></span>
        (</span>IERCZKMLRegistry</span>.</span>ModelCommitment </span>memory</span> cm</span>,</span>,</span>)</span> =</span> registry</span>.</span>getModel</span>(</span>modelId</span>)</span>;</span></span>
        return</span> cm</span>.</span>proofSystemId</span>;</span></span>
    }</span></span>
</span>
    function</span> _dummyVerify</span>(</span></span>
        bytes</span> calldata</span>,</span></span>
        bytes32</span>,</span></span>
        bytes32</span>,</span></span>
        bytes</span> calldata</span></span>
    )</span> private</span> pure</span> returns</span> (</span>bool</span>)</span> {</span></span>
        return</span> true</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Security Considerations</h2>
Security</h3>


Replay Attacks: Inputs must embed a nonce/salt where uniqueness matters. Contracts may also track consumed inferenceIds</code>.</li>
Model Commitment Drift: Updating commitments can invalidate proofs; consumers should pin specific modelId</code> + commitment</code> hashes or check deprecated.</li>
Hash Domain Separation: Use distinct prefixes (e.g., "ZKML_MODEL_V1") to avoid collisions across contexts.</li>
Output Ambiguity: Contracts must validate or commit to output schemas to avoid maliciously crafted bytes.</li>
DoS via Heavy Verification: Consider off-chain verification with on-chain succinct attestations, or batching/aggregation.</li>
</ul>
Gas</h3>

Proof verification can dominate gas costs; splitting verification-only calls from storage writes lets integrators choose.</li>
Events are cheaper than persistent storage for audit trails.</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Minimal Avatar Smart Wallet (MASW)
2025-07-08T00:00:00+00:00
Abstract</h2>
Minimal Avatar Smart Wallet (MASW) is an immutable delegate‑wallet that any EOA can designate via EIP‑7702</a> (txType 0x04</code>). Once designated, the wallet's code remains active for every subsequent transaction until the owner sends a new 0x04</code> to clear or replace it. During each delegated call the EOA is the avatar and MASW's code executes as the delegate at the same address, enabling atomic batched calls (EIP‑712</a> signed) and optional sponsor gas reimbursement in ETH or ERC‑20</a>.</p>
The contract offers one primary function, executeBatch</code>, plus two plug‑in hooks: a Policy Module for pre/post guards and a Recovery Module for alternate signature validation. Replay attacks are prevented by a global metaNonce, an expiry, and a chain‑bound EIP‑712</code> domain separator. Standardising this seven‑parameter ABI removes wallet fragmentation while still allowing custom logic through modules.</p>
Motivation</h2>
A single‑transaction code‑injection model (EIP‑7702) grants EOAs full implementation freedom, but unconstrained diversity would impose high coordination costs:</p>

Interoperability</strong> – Divergent ABIs and fee‑settlement conventions force dApps and relayers to maintain per‑wallet adapters, increasing integration complexity and failure modes.</li>
Economic alignment</strong> – Gas‑sponsorship relies on deterministic fee‑reimbursement paths; heterogeneity erodes relayer incentives and throttles sponsored‑transaction volume.</li>
Tooling precision</strong> – Indexers, debuggers, and static‑analysis frameworks achieve optimal decoding and gas estimation when targeting a single, fixed byte‑code and seven‑field call schema.</li>
Extensibility focus</strong> – Constraining variability to two module boundaries (Policy, Recovery) localizes complexity, allowing research and hardening efforts to concentrate on higher‑level security primitives rather than re‑engineering core wallet logic.</li>
</ul>
By standardising the immutable byte‑code, signature domain, and minimal ABI while exposing clearly defined extension hooks, MASW minimizes fragmentation and maximizes composability across the Ethereum tooling stack.</p>
Specification</h2>
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.</p>
Overview of Delegation Flow</h3>

Deploy</strong> MASW</code> with constructor argument _owner = EOA</code>.</li>
The owner sends an EIP‑7702 transaction (txType 0x04</code>) referencing the contract's byte‑code hash.</li>
After that transaction the EOA acts as the avatar wallet</strong> while the MASW logic executes as the delegate wallet</strong> at the same</em> address.</li>
</ol>
Public Interface</h3>
function</span> executeBatch</span>(</span></span>
    address</span>[</span>]</span> calldata</span> targets</span>,</span></span>
    uint256</span>[</span>]</span> calldata</span> values</span>,</span></span>
    bytes</span>[</span>]</span>   calldata</span> calldatas</span>,</span></span>
    address</span> token</span>,</span></span>
    uint256</span> fee</span>,</span></span>
    uint256</span> expiry</span>,</span></span>
    bytes</span>   calldata</span> signature</span></span>
)</span> external</span>;</span></span>
</span>
function</span> setPolicyModule</span>(</span>address</span> newModule</span>)</span>   external</span>;</span></span>
function</span> setRecoveryModule</span>(</span>address</span> newModule</span>)</span> external</span>;</span></span>
</span>
event</span> BatchExecuted</span>(</span>bytes32</span> indexed</span> structHash</span>)</span>;</span></span>
event</span> ModuleChanged</span>(</span>bytes32</span> indexed</span> kind</span>, </span>address</span> oldModule</span>, </span>address</span> newModule</span>)</span>;</span></span></code></pre>Transaction Type Hash</h3>
bytes32</span> constant</span> BATCH_TYPEHASH </span>=</span> keccak256</span>(</span></span>
  "Batch(address[] targets,uint256[] values,bytes[] calldatas,address token,uint256 fee,uint256 exp,uint256 metaNonce)"</span></span>
)</span>;</span></span></code></pre>Storage Layout</h3>
Slot</th> Name</th> Type</th> Description</th></tr></thead>

0</td> metaNonce</code></td> uint256</td> Monotonically increasing meta‑nonce</td></tr>
1</td> _entered</code></td> uint256</td> Re‑entrancy guard flag</td></tr>
2</td> policyModule</code></td> address</td> Optional IPolicyModule</code> (zero = none)</td></tr>
3</td> recoveryModule</code></td> address</td> Optional IRecoveryModule</code> (zero = none)</td></tr>
</tbody></table>
owner</code> and DOMAIN_SEPARATOR</code> are immutable</code> and occupy no storage slots.</p>
Domain Separator Construction</h3>
DOMAIN_SEPARATOR </span>=</span> keccak256</span>(</span></span>
  abi</span>.</span>encode</span>(</span></span>
    keccak256</span>(</span>"EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"</span>)</span>,</span></span>
    keccak256</span>(</span>"MASW"</span>)</span>,</span></span>
    keccak256</span>(</span>"1"</span>)</span>,</span></span>
    block</span>.</span>chainid</span>,</span>   //</span> MUST be the live chain‑ID; using 0 is disallowed</span></span>
    _owner           </span>//</span> keeps separator stable before & after delegation</span></span>
  )</span></span>
)</span>;</span></span></code></pre>Batch Execution (executeBatch</code>)</h3>
Stage</th> Behaviour</th></tr></thead>

Validation</strong></td> ‑ targets.length == values.length == calldatas.length > 0</code>
‑ block.timestamp ≤ expiry</code>
‑ metaNonce</code> matches then increments
‑ EIP712</code> digest recovers owner</code> or</strong> is approved by recoveryModule</code></td></tr>
Policy pre‑hook</strong></td> If policyModule != address(0)</code>, preCheck</code> MUST</strong> return true</code>; a revert or false</code> vetoes the batch</td></tr>
Calls</strong></td> For each index i</em>: targets[i].call{value:values[i]}(calldatas[i])</code>; revert on first failure</td></tr>
Policy post‑hook</strong></td> Same semantics as pre‑hook</td></tr>
Fee reimbursement</strong></td> If fee > 0</code>: native transfer (token == address(0)</code>) or ERC20</code> transfer</code> with OpenZeppelin‑style return‑value check   </td></tr>
Emit</strong></td> BatchExecuted(structHash)</code></td></tr>
</tbody></table>
Gas Sponsorship</h4>
The relayer and owner agree off‑chain on (token, fee)</code> prior to submission.

Because the fee is part of the signed batch, a relayer cannot unilaterally raise it.

If a rival relayer broadcasts the same signed batch first, they earn the fee and the original relayer's transaction reverts—aligning incentives naturally.

Relayers MUST</strong> confirm the avatar's balance up‑front; insufficient funds render the transaction invalid in the mem‑pool.</p>
Modules</h3>
Policy Module</h4>
interface</span> IPolicyModule</span> {</span></span>
  function</span> preCheck</span> (</span>address</span> sender</span>,</span> bytes</span> calldata</span> rawData</span>,</span> uint256</span> value</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
  function</span> postCheck</span>(</span>address</span> sender</span>,</span> bytes</span> calldata</span> rawData</span>,</span> uint256</span> value</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
}</span></span></code></pre>

A module MAY</strong> veto by reverting or</em> by returning false</code>.</li>
The value</code> parameter represents the total ETH sent with the transaction (msg.value</code>), allowing the policy module to validate this against the batch requirements contained in rawData</code>.</li>
Aggregator designs are encouraged: forward to child policies and stop on first failure (revert or return false</code>).</li>
</ul>
Recovery Module</h4>
interface</span> IRecoveryModule</span> {</span></span>
  function</span> isValidSignature</span>(</span>bytes32</span> hash</span>,</span> bytes</span> calldata</span> sig</span>)</span> external</span> view</span> returns</span> (</span>bytes4</span>)</span>;</span></span>
}</span></span></code></pre>
Must return 0x1626ba7e</code>.</p>
Nonce‑Race Consideration</h3>
A single global metaNonce</code> is used. Two relayers submitting the same nonce concurrently results in one success and one revert. The expiry</code> field (wallets typically set ≤ 30 s) makes such races low‑impact, but UIs should surface the failure.</p>
Rationale</h2>

Immutable logic</strong> minimizes upgrade risk; a new version requires an explicit 7702 0x04</code> call.</li>
A two‑module</strong> boundary captures common customizations without growing byte‑code.</li>
No hard maxTargets</code>; advanced users can bundle many calls, while conservative users install a size‑capping Policy module.</li>
Domain separator binds the real chainId</code> to mitigate cross‑chain replays.</li>
</ul>
Reference Implementation</h2>
Reference implementation can be found here MASW.sol</code></a>.</p>
Security Considerations</h2>
Threat</th> Mitigation</th></tr></thead>

Same‑chain replay</td> Global metaNonce</code></td></tr>
Cross‑chain replay</td> Chain‑bound domain separator</td></tr>
Fee grief / over‑charge</td> Fee is part of signed data; front‑running risk sits with relayer</td></tr>
Batch gas grief</td> Optional Policy can reject oversized batches</td></tr>
ERC20</code> non‑standard returns</td> OpenZeppelin SafeERC20</code> transfer check</td></tr>
Re‑entrancy</td> nonReentrant</code> guard; state mutated only before external calls (nonce++) and after (fee transfer)</td></tr>
Malicious Module</td> Core logic immutable; swapping modules needs an owner‑signed tx</td></tr>
</tbody></table>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Contract Feature Detection
2025-07-07T00:00:00+00:00
Abstract</h2>
Creates a standard method supportsFeature(bytes4)</code> in the same spirit as supportsInterface(bytes4)</code> to publish and detect what features a smart contract implements that lack a derivable ERC-165</a> interface.</p>
Motivation</h2>
Ethereum Name Service (ENS) has maintained backwards compatibility with contracts created in 2016 through extensive use of ERC-165.  Unfortunately, not all contract capabilities can be expressed through an unique interface.</p>
Features allow expression of contract capabilities that preserve existing interfaces.  This proposal standardizes the concept of features and standardizes the identification (naming) of features.</p>
Defining a new standard avoids unnecessary pollution of the ERC-165 selector namespace with synthetic interfaces representing features.</p>
Specification</h2>
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</a> and RFC 8174</a>.</p>
How Features are Identified</h3>
For this standard, a feature</em> is any property of a contract that cannot be expressed via ERC-165.</p>
A feature name SHOULD be a reverse domain name that uniquely defines its implication, eg. eth.ens.resolver.extended.multicall</code> is the multicall feature for an extended ENS resolver contract.</p>
A feature identifier is defined as the first four-bytes of the keccak256-hash of its name, eg. bytes4(keccak256("eth.ens.resolver.extended.multicall")) = 0x96b62db8</code>.</p>
How a Contract will Publish the Features it Implements</h3>
A contract that is compliant with this specification SHALL implement the following interface:</p>
interface</span> IERC7996</span> {</span></span>
    ///</span> @notice</span> Check if a feature is supported.</span></span>
    ///</span> @param</span> featureId</span> The feature identifier.</span></span>
    ///</span> @return</span> `true` if the feature is supported by the contract.</span></span>
    function</span> supportsFeature</span>(</span>bytes4</span> featureId</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
}</span></span></code></pre>
The ERC-165 interface identifier for this interface is 0x582de3e7</code>.</p>
How to Detect if a Contract Implements Features</h3>

Check if the contract supports the interface above according to ERC-165</a>.</li>
</ol>
How to Detect if a Contract Implements any Given Feature</h3>

If you are not sure if the contract implements features, use the above procedure to confirm.</li>
If it implements features, then call supportsFeature(featureId)</code> to determine if it implements the desired feature.</li>
</ol>
Note: a contract that implements features MAY implement no features.</p>
Rationale</h2>
Since feature names cannot be derived from a contract interface, they are derived from a reverse domain name to reduce collisions and permit a human-readable representention that briefly describes its implication.</p>
Backwards Compatibility</h2>
Callers unaware of features or any specific feature experience no change in behavior.</p>
ENS already implements this ERC.</p>
Security Considerations</h2>
As with ERC-165, declaring support for a feature does not guarantee that the contract implements it.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Confidential Fungible Token
2025-07-03T00:00:00+00:00
Abstract</h2>
The following standard describes confidential fungible tokens via pointers. All amounts in this standard are represented by confidential pointers; therefore, balances and transfer amounts are confidential. Pointers refer to data stored elsewhere--onchain or offchain. The logistics of pointer resolution, operation, and location are implementation specific. The interface defines functions to transfer tokens with pointers, as well as approve operators, allowing the token to be transferred by a third party.</p>
Motivation</h2>
Confidential tokens enable private value transfer which is vital for many usecases such as payroll, confidential DeFi, institutional settlement, and more.
A standard interface allows pointer based confidential tokens on Ethereum to be reused by other applications: from privacy-focused wallets to decentralized exchanges, while keeping transaction amounts private from public view.</p>
Specification</h2>
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</a> and RFC 8174</a>.</p>
Nomenclature</h3>
All amounts in this ERC are pointer based amounts represented by bytes32</code> pointers unless otherwise specified. The resolution and manipulation of these pointers is implementation specific.</p>
Token</h3>
Compliant tokens MUST implement ERC-165</a>. The supportsInterface</code> function MUST return true</code> if 0x4958f2a4</code> is passed through the interfaceID</code> argument.</p>
Methods</h3>
Compliant tokens MUST implement the following methods, unless otherwise specified:</p>

name()</code></h4>
Returns the name of the token - e.g. "MyConfidentialToken"</code>.</p>
function</span> name</span>(</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span></span></code></pre></li>
symbol()</code></h4>
Returns the symbol of the token - e.g. "MCT"</code>.</p>
function</span> symbol</span>(</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span></span></code></pre></li>
decimals()</code></h4>
Returns the number of decimals the token uses (e.g. 6</code>) as a plaintext uint8</code>.</p>
function</span> decimals</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint8</span>)</span></span></code></pre></li>
contractURI()</code></h4>
Returns the metadata URI for the token. SHOULD follow the schema defined in ERC-7572</a>.</p>
function</span> contractURI</span>(</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span></span></code></pre></li>
confidentialTotalSupply()</code></h4>
Returns the total token supply.</p>
function</span> confidentialTotalSupply</span>(</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li>
confidentialBalanceOf(address)</code></h4>
Returns the balance of account</code>.</p>
function</span> confidentialBalanceOf</span>(</span>address</span> account</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li>
isOperator(address,address)</code></h4>
Returns true</code> if spender</code> is currently authorized to transfer tokens on behalf of holder</code>.</p>
function</span> isOperator</span>(</span>address</span> holder</span>,</span> address</span> spender</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span></span></code></pre></li>
setOperator(address,uint48)</code></h4>
Authorizes operator</code> to transfer tokens on behalf of the caller until timestamp until</code>--passed as a plaintext uint48</code>. An operator may transfer any amount of tokens on behalf of a holder while approved. Accounts may have multiple simultaneous operators.</p>
MUST emit the OperatorSet</code> event.</p>
function</span> setOperator</span>(</span>address</span> operator</span>,</span> uint48</span> until</span>)</span> external</span></span></code></pre></li>
confidentialTransfer(address,bytes32)</code></h4>
Transfers amount</code> of tokens to address to</code>. The function MAY revert if the caller's balance does not have enough tokens to spend.</p>
Returns the actual amount that was transferred.</p>
MUST emit the ConfidentialTransfer</code> event.</p>
function</span> confidentialTransfer</span>(</span>address</span> to</span>,</span> bytes32</span> amount</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li>
confidentialTransfer(address,bytes32,bytes)</code></h4>
Transfers amount</code> of tokens to address to</code>. The function MAY revert if the caller's balance does not have enough tokens to spend.</p>
The data</code> parameter contains implementation-specific information such as cryptographic proofs.</p>
Returns the actual amount that was transferred.</p>
MUST emit the ConfidentialTransfer</code> event.</p>
function</span> confidentialTransfer</span>(</span>address</span> to</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li>
confidentialTransferFrom(address,address,bytes32)</code></h4>
Transfers amount</code> of tokens from address from</code> to address to</code>. The function MAY revert if the from</code>'s account balance does not have enough tokens to spend.</p>
Returns the actual amount that was transferred.</p>
MUST revert if the caller is not an operator for from</code>.</p>
MUST emit the ConfidentialTransfer</code> event.</p>
function</span> confidentialTransferFrom</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li>
confidentialTransferFrom(address,address,bytes32,bytes)</code></h4>
Transfers amount</code> of tokens from address from</code> to address to</code>. The function MAY revert if the from</code>'s account balance does not have enough tokens to spend.</p>
The data</code> parameter contains implementation-specific information such as cryptographic proofs.</p>
Returns the actual amount that was transferred.</p>
MUST revert if the caller is not an operator for from</code>.</p>
MUST emit the ConfidentialTransfer</code> event.</p>
function</span> confidentialTransferFrom</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li>
confidentialTransferAndCall(address,bytes32,bytes)</code></h4>
Transfers amount</code> of tokens to address to</code>. The function MAY revert if the caller's balance does not have enough tokens to spend.</p>
The data</code> parameter contains implementation-specific information such as cryptographic proofs.</p>
See Callback Details</a> below for details on the callback flow.</p>
Returns the actual amount that was transferred.</p>
MUST emit the ConfidentialTransfer</code> event.</p>
function</span> confidentialTransferAndCall</span>(</span>address</span> to</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> callData</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li>
confidentialTransferAndCall(address,bytes32,bytes,bytes)</code></h4>
Transfers amount</code> of tokens to address to</code>. The function MAY revert if the caller's balance does not have enough tokens to spend.</p>
The data</code> parameter contains implementation-specific information such as cryptographic proofs.</p>
See Callback Details</a> below for details on the callback flow.</p>
Returns the actual amount that was transferred.</p>
MUST emit the ConfidentialTransfer</code> event.</p>
function</span> confidentialTransferAndCall</span>(</span>address</span> to</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> data</span>,</span> bytes</span> calldata</span> callData</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li>
confidentialTransferFromAndCall(address,address,bytes32,bytes)</code></h4>
Transfers amount</code> of tokens from address from</code> to address to</code>. The function MAY revert if the from</code>'s account balance does not have enough tokens to spend.</p>
See Callback Details</a> below for details on the callback flow.</p>
Returns the actual amount that was transferred.</p>
MUST revert if the caller is not an operator for from</code>.</p>
MUST emit the ConfidentialTransfer</code> event.</p>
function</span> confidentialTransferFromAndCall</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> callData</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li>
confidentialTransferFromAndCall(address,address,bytes32,bytes,bytes)</code></h4>
Transfers amount</code> of tokens from address from</code> to address to</code>. The function MAY revert if the from</code>'s account balance does not have enough tokens to spend.</p>
The data</code> parameter contains implementation-specific information such as cryptographic proofs.</p>
See Callback Details</a> below for details on the callback flow.</p>
Returns the actual amount that was transferred.</p>
MUST revert if the caller is not an operator for from</code>.</p>
MUST emit the ConfidentialTransfer</code> event.</p>
function</span> confidentialTransferFromAndCall</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> data</span>,</span> bytes</span> calldata</span> callData</span>)</span> external</span> returns</span> (</span>bytes32</span>)</span></span></code></pre></li>
</ul>
Events</h3>

ConfidentialTransfer</h4>
MUST trigger when confidential tokens are transferred, including zero value transfers.</p>
A token contract which creates new tokens SHOULD trigger a ConfidentialTransfer event with the from</code> address set to 0x0</code> when tokens are created.</p>
event</span> ConfidentialTransfer</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>bytes32</span> indexed</span> amount</span>)</span></span></code></pre></li>
OperatorSet</h4>
MUST trigger on any successful call to setOperator</code>.</p>
event</span> OperatorSet</span>(</span>address</span> indexed</span> holder</span>, </span>address</span> indexed</span> operator</span>, </span>uint48</span> until</span>)</span></span></code></pre></li>
AmountDisclosed</h4>
SHOULD trigger when a pointer amount is publicly disclosed through implementation-specific mechanisms.</p>
event</span> AmountDisclosed</span>(</span>bytes32</span> indexed</span> handle</span>, </span>uint256</span> amount</span>)</span></span></code></pre></li>
</ul>
Callback Details</h3>
Transfer functions suffixed with andCall</code> execute a callback to the to</code> address AFTER all transfer logic is completed. The callback calls the onConfidentialTransferReceived</code> function with the transfer initiator (operator), from address, actual amount sent, and given callData</code> bytes (the last parameter for andCall</code> functions). The callback flow is as follows:</p>

If address(to).code.length == 0</code> the callback is a no-op and returns successfully.</li>
Call onConfidentialTransferReceived(address, address, bytes32, bytes)</code></a> on to</code>.</li>
If the function call reverts, revert.</li>
If the function call returns the false boolean, attempt to transfer back the tokens to the original holder and return.</li>
</ul>
Contract Receivers</h3>
For a contract to receive a transfer with a callback, it MUST implement the onConfidentialTransferReceived</code> function:</p>
onConfidentialTransferReceived</h4>
If the callback is unsuccessful, the function SHOULD revert or return a pointer to the false boolean.</p>
The token will attempt to return tokens from the receiver to the sender if false is returned. Note that this reversal may fail if the receiver spends tokens as part of the callback.</p>
function</span> onConfidentialTransferReceived</span>(</span>address</span> operator</span>,</span> address</span> from</span>,</span> bytes32</span> amount</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> returns</span> (</span>bytes32</span> success</span>)</span>;</span></span></code></pre>Rationale</h2>
Technology Agnostic Design</h3>
Using bytes32</code> allows implementations using pointer based systems and privacy mechanisms including FHE systems, zero-knowledge proofs, secure enclaves, or future technologies to be compliant.</p>
Operator Model</h3>
Time-limited operators provide granular control while enabling DeFi protocol integration and natural permission expiration. This approach reduces the load on the external system by removing the need to track approval amounts.</p>
Data Parameter</h3>
The bytes calldata data</code> parameter in transfer functions allows implementations to include cryptographic proofs, access permissions, or other privacy-mechanism-specific information.</p>
Security Considerations</h2>
Security depends on the underlying pointer based mechanism. Implementations must guard against side-channel attacks and ensure proper key management for offchain operations.</p>
Token callbacks are associated with inherent security risks, including reentrancy and gas griefing. When utilizing callbacks, consider using reentrancy protection and setting a gas limit.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Operator contract for non delegated EOAs
2025-07-02T00:00:00+00:00
Abstract</h2>
This standard defines a contract interface that enables externally owned accounts (EOAs) to perform batch call executions via a standard Operator contract, without requiring them to delegate control or convert into smart contract accounts.</p>
Motivation</h2>
The ERC-7702</a> allows EOAs to become powerful smart contract accounts (SCA), which solves many UX issues, like the double approve</code> + transferFrom</code> transactions.

While this new technology is still reaching wider adoption over time, we need a way to improve UX for the users that decide to not have code attached to their EOAs.

This proposal introduces a lightweight, backward-compatible mechanism to enhance UX for such users. By leveraging a standardized Operator contract, EOAs can batch multiple contract calls into a single transaction—assuming the target contracts are compatible (i.e., implement the Operated pattern).</p>
Specification</h2>
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</a> and RFC 8174</a>.</p>
Definitions</h3>

Operator: The contract that executes calls on the sender's behalf.</li>
Operated: The contract that supports calls through the Operator.</li>
</ul>
It's OPTIONAL but HIGHLY RECOMMENDED to have the Operator</code> contract as a singleton.</p>
Operator</h3>
pragma</span> solidity</span> ^0.8.29</span>;</span></span>
</span>
interface</span> IOperator</span> {</span></span>
    struct</span> Call</span> {</span></span>
        address</span> target</span>;</span></span>
        uint256</span> value</span>;</span></span>
        bytes</span> callData</span>;</span></span>
    }</span></span>
</span>
    ///</span> @notice</span> Execute calls</span></span>
    ///</span> @param</span> calls</span> An array of Call structs</span></span>
    ///</span> @return</span> returnData</span> An array of bytes containing the responses</span></span>
    function</span> execute</span>(</span>Call</span>[</span>]</span> calldata</span> calls</span>)</span> external</span> payable</span> returns</span> (</span>bytes</span>[</span>]</span> memory</span> returnData</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> The address which initiated the executions</span></span>
    ///</span> @return</span> sender</span> The actual sender of the calls</span></span>
    function</span> onBehalfOf</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span> sender</span>)</span>;</span></span>
}</span></span></code></pre>Methods</h3>
execute</code>
Execute the calls sent by the actual sender.</p>
MUST revert if any of the calls fail.

MUST return data from the calls.</p>
onBehalfOf</code>
Used by the target contract to get the actual caller.</p>
MUST return the actual msg.sender</code> when called in the context of a call.

MUST revert when called outside of the context of a call.</p>
Operated</h3>
pragma</span> solidity</span> ^0.8.29</span>;</span></span>
</span>
import</span> { </span>Context</span> }</span> from</span> "@openzeppelin/contracts/utils/Context.sol"</span>;</span></span>
import</span> { </span>IOperator</span> }</span> from</span> "./interfaces/IOperator.sol"</span>;</span></span>
</span>
///</span> @title</span> Operated contract</span></span>
///</span> @dev</span> Supports calls through the Operator</span></span>
abstract</span> contract</span> Operated</span> is</span> Context</span> {</span></span>
    IOperator </span>public</span> immutable</span> operator</span>;</span></span>
</span>
    constructor</span>(</span>address</span> operator_</span>)</span> {</span></span>
        operator </span>=</span> IOperator</span>(</span>operator_</span>)</span>;</span></span>
    }</span></span>
</span>
    ///</span> @inheritdoc</span> Context</span></span>
    function</span> _msgSender</span>(</span>)</span> internal</span> view</span> virtual</span> override</span> returns</span> (</span>address</span>)</span> {</span></span>
        if</span> (</span>msg.sender</span> ==</span> address</span>(</span>operator</span>)</span>)</span> {</span></span>
            return</span> operator</span>.</span>onBehalfOf</span>(</span>)</span>;</span></span>
        }</span></span>
</span>
        return</span> msg.sender</span>;</span></span>
    }</span></span>
}</span></span></code></pre>
Any contract can become compatible to execute the batch call by EOA using operator if it extends the Operated</code> contract. The Operated</code> contract overrides _msgSender()</code> to return operator.onBehalfOf()</code> when the call originates from the Operator. This ensures that the target contract recognizes the EOA initiating the batch execution, preserving correct sender context.</p>
This behavior fits well with the usage of the _msgSender() function from ERC-2771</a>.</p>
Methods</h3>
_msgSender</code>
Returns msg.sender</code> or operator.onBehalfOf()</code></p>
Rationale</h2>
By having a trusted contract (Operator</code>) that may act on behalf of the EOA wallet, this ERC provides batch call capabilities and keeps the EOA as the caller of the target contracts.</p>
Backwards Compatibility</h2>
The main limitation of this ERC is that only contracts that implements the Operated</code> logic will be able to receive calls through the Operator</code>.</p>
Reference Implementation</h2>
Operator</h3>
pragma</span> solidity</span> ^0.8.29</span>;</span></span>
</span>
import</span> {</span>TransientSlot</span>}</span> from</span> "@openzeppelin/contracts/utils/TransientSlot.sol"</span>;</span></span>
import</span> {</span>Address</span>}</span> from</span> "@openzeppelin/contracts/utils/Address.sol"</span>;</span></span>
import</span> {</span>ReentrancyGuardTransient</span>}</span> from</span> "@openzeppelin/contracts/utils/ReentrancyGuardTransient.sol"</span>;</span></span>
import</span> {</span>IOperator</span>}</span> from</span> "./interfaces/IOperator.sol"</span>;</span></span>
</span>
///</span> @title</span> Operator contract</span></span>
///</span> @dev</span> Allows standard EOAs to perform batch calls</span></span>
contract</span> Operator</span> is</span> IOperator</span>, </span>ReentrancyGuardTransient</span> {</span></span>
    using</span> TransientSlot </span>for</span> *</span>;</span></span>
    using</span> Address</span> for</span> address</span>;</span></span>
</span>
    //</span> keccak256(abi.encode(uint256(keccak256("operator.actual.sender")) - 1)) & ~bytes32(uint256(0xff))</span></span>
    bytes32</span> private</span> constant</span> MSG_SENDER_STORAGE </span>=</span> 0x0de195ebe01a7763c35bcc87968c4e65e5a5ea50f2d7c33bed46c98755a66000</span>;</span></span>
</span>
    modifier</span> setMsgSender</span>(</span>)</span> {</span></span>
        MSG_SENDER_STORAGE</span>.</span>asAddress</span>(</span>)</span>.</span>tstore</span>(</span>msg.sender</span>)</span>;</span></span>
        _</span>;</span></span>
        MSG_SENDER_STORAGE</span>.</span>asAddress</span>(</span>)</span>.</span>tstore</span>(</span>address</span>(</span>0</span>)</span>)</span>;</span></span>
    }</span></span>
</span>
    ///</span> @inheritdoc</span> IOperator</span></span>
    function</span> onBehalfOf</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span> _actualMsgSender</span>)</span> {</span></span>
        _actualMsgSender </span>=</span> MSG_SENDER_STORAGE</span>.</span>asAddress</span>(</span>)</span>.</span>tload</span>(</span>)</span>;</span></span>
        require</span>(</span>_actualMsgSender </span>!=</span> address</span>(</span>0</span>)</span>,</span> "outside-call-context"</span>)</span>;</span></span>
    }</span></span>
</span>
    ///</span> @inheritdoc</span> IOperator</span></span>
    function</span> execute</span>(</span></span>
        Call</span>[</span>]</span> calldata</span> calls_</span></span>
    )</span> external</span> payable</span> override</span> nonReentrant</span> setMsgSender</span> returns</span> (</span>bytes</span>[</span>]</span> memory</span> _returnData</span>)</span> {</span></span>
        uint256</span> _length </span>=</span> calls_</span>.</span>length</span>;</span></span>
        _returnData </span>=</span> new</span> bytes</span>[](</span>_length</span>)</span>;</span></span>
</span>
        uint256</span> _sumOfValues</span>;</span></span>
        Call </span>calldata</span> _call</span>;</span></span>
        for</span> (</span>uint256</span> i</span>;</span> i </span><</span> _length</span>;</span> )</span> {</span></span>
            _call </span>=</span> calls_</span>[</span>i</span>]</span>;</span></span>
            uint256</span> _value </span>=</span> _call</span>.</span>value</span>;</span></span>
            unchecked</span> {</span></span>
                _sumOfValues </span>+</span>=</span> _value</span>;</span></span>
            }</span></span>
            _returnData</span>[</span>i</span>]</span> =</span> _call</span>.</span>target</span>.</span>functionCallWithValue</span>(</span>_call</span>.</span>callData</span>,</span> _value</span>)</span>;</span></span>
            unchecked</span> {</span></span>
                +</span>+</span>i</span>;</span></span>
            }</span></span>
        }</span></span>
</span>
        require</span>(</span>msg</span>.</span>value </span>==</span> _sumOfValues</span>,</span> "value-mismatch"</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>
Worth noting that the usage of transient storage (EIP-1153</a>) for storing the msg.sender</code> is highly RECOMMENDED.</p>
Operated</h3>
pragma</span> solidity</span> ^0.8.29</span>;</span></span>
</span>
import</span> {</span>Context</span>}</span> from</span> "@openzeppelin/contracts/utils/Context.sol"</span>;</span></span>
import</span> {</span>IERC20</span>}</span> from</span> "@openzeppelin/contracts/token/ERC20/IERC20.sol"</span>;</span></span>
import</span> {</span>IOperator</span>}</span> from</span> "./interfaces/IOperator.sol"</span>;</span></span>
import</span> {</span>Operated</span>}</span> from</span> "./Operated.sol"</span>;</span></span>
</span>
///</span> @title</span> Operated contract</span></span>
///</span> @dev</span> Supports calls through the Operator</span></span>
contract</span> OperatorCompatible</span> is</span> Operated</span> {</span></span>
    error</span> InsufficientBalance</span>(</span>)</span>;</span></span>
</span>
    mapping</span>(</span>address</span> =></span> mapping</span>(</span>address</span> =></span> uint256</span>)</span>)</span> public</span> balance</span>;</span></span>
</span>
    constructor</span>(</span>address</span> operator_</span>)</span> Operated</span>(</span>operator_) </span>{</span>}</span></span>
</span>
     function</span> deposit</span>(</span>address</span> token_</span>,</span> uint256</span> amount_</span>)</span> public</span> payable</span> {</span></span>
        if</span> (</span>token_ </span>==</span> address</span>(</span>0</span>)</span>)</span> revert</span> InvalidToken</span>(</span>)</span>;</span></span>
        address</span> _sender </span>=</span> _msgSender</span>(</span>)</span>;</span></span>
        IERC20</span>(</span>token_</span>)</span>.</span>transferFrom</span>(</span>_sender</span>,</span> address</span>(</span>this</span>)</span>,</span> amount_</span>)</span>;</span></span>
        balance</span>[</span>token_</span>]</span>[</span>_sender</span>]</span> +</span>=</span> amount_</span>;</span></span>
    }</span></span>
</span>
    function</span> withdraw</span>(</span>address</span> token_</span>,</span> uint256</span> amount_</span>)</span> public</span> {</span></span>
        if</span> (</span>token_ </span>==</span> address</span>(</span>0</span>)</span>)</span> revert</span> InvalidToken</span>(</span>)</span>;</span></span>
        address</span> _sender </span>=</span> _msgSender</span>(</span>)</span>;</span></span>
        if</span> (</span>balance</span>[</span>token_</span>]</span>[</span>_sender</span>]</span> <</span> amount_</span>)</span> revert</span> InsufficientBalance</span>(</span>)</span>;</span></span>
        balance</span>[</span>token_</span>]</span>[</span>_sender</span>]</span> -</span>=</span> amount_</span>;</span></span>
        IERC20</span>(</span>token_</span>)</span>.</span>transfer</span>(</span>_sender</span>,</span> amount_</span>)</span>;</span></span>
    }</span></span>
}</span></span>
</span></code></pre>Security Considerations</h2>

The execute</code> function MUST implement reentracy control to avoid having a callback call overriding the sender's storage.</li>
The Operated</code> contract MUST interact with a trusted Operator</code> contract.</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Owner-Authorized Token Transfer Protocol
2025-06-11T00:00:00+00:00
Abstract</h2>
This proposal introduces an innovative token transfer processing model designed for third parties, enabling seamless use of Ethereum-based tokens (e.g., ERC-20</a>) by non-crypto-native actors. The concept allows a third-party payment processor to initiate token transfers on behalf of another party and to cover the associated transaction (gas) fees. The main party (user) always remains the explicit owner of the tokens, which are securely held and referenced under their ownership in the smart contract.</p>
The transfer process is two-phased:</p>

Initiation:</strong> The payment processor proposes a token transfer via the smart contract. This proposal is emitted as an on-chain event, including all relevant transfer details and a unique hash of the transaction (“proposal hash”).</li>
Approval:</strong> The authorized party (owner) reviews the proposal off-chain and, if in agreement, signs the proposal hash with their private key. This signature is sent to the payment processor, who then submits it to the smart contract. There, the contract verifies the signature and, upon approval, carries out the token transfer in the owner’s name.</li>
</ol>
To increase security and usability, each proposal includes an explicit expiration time. If the signature is not submitted and verified within the defined validity period, the proposal becomes void and the transfer cannot be executed.</p>
To further enhance user safety, the owner is provided with a function that allows transferring all token balances directly to their own address in case the payment processor becomes unresponsive, acts improperly, or if external conditions such as transaction costs change unfavorably.</p>
This model empowers entities to integrate blockchain-based payments into their workflows without directly holding or managing cryptocurrencies. All token movements require explicit owner approval, ensuring security and retaining full user control. The payment processor is compensated “off-chain” (e.g., in fiat currency) and is responsible for gas costs.</p>
By removing the technical and operational burdens of crypto management from the end user, this approach facilitates broader adoption of tokenized business cases and simplifies enterprise integration.</p>
Motivation</h2>
Adoption of blockchain-based payments and tokenized assets in enterprise and conventional business contexts is still often hindered by the need for end-users or business partners to directly manage cryptocurrencies, wallets, and on-chain transactions. For many organizations, the technical, regulatory, and operational burdens associated with self-custody and on-chain fee management present significant entry barriers.</p>
This proposal aims to lower these barriers by introducing a model in which a trusted third-party payment processor can manage all blockchain transactions on behalf of a token owner, including paying transaction fees. The owner maintains full control and explicit on-chain ownership of the assets, and must approve all outgoing transfers cryptographically. Payment for the processor's services (including gas reimbursement) can take place off-chain and in fiat currency, which aligns with existing financial workflows and compliance expectations.</p>
With an explicit fallback function, owners are further protected, ensuring they can always reclaim direct control over their assets if the processor becomes unresponsive or external conditions change.</p>
In summary, this standard facilitates broader and more secure adoption of token-based processes by offloading complexity from end-users, while preserving security, transparency, and user sovereignty.</p>
Specification</h2>
Methods</h3>
Smart Contract that holds the assets (ITokenStorage.sol</code>)</h4>
Transfer proposal: proposeTransaction</code></h5>
function</span> proposeTransaction</span>(</span>address</span> tokenAddress</span>,</span> uint256</span> amountToSent</span>,</span> address</span> destinationAddress</span>)</span> external</span>;</span></span></code></pre>
Called from the paymentProcessor/transactionProvider of the storage to initiate a token transfer. Emits a TransactionProposed</code> event.
The parameter tokenAddress</code> is the address of the token which should be transferred.
The parameter amountToSent</code> is the amount which should be transferred to the desired destination address.
The parameter destinationAddress</code> defines the receiver of the defined token.
The proposal is stored in the contract and a unique (uint256) hash is generated for it, which is used for the approval process.</p>
Transfer completion: completeTransaction</code></h5>
function</span> completeTransaction</span>(</span>uint256</span> hash</span>,</span> bytes</span> memory</span> signature</span>)</span> external</span>;</span></span></code></pre>
Called from the paymentProcessor/transactionProvider of the storage to perform a token transfer. Emits a TransactionCompleted</code> event.
The parameter hash</code> is unique identifier of the transaction.
The parameter signature</code> is a signed message which only includes the hash. This message is signed by the credentials of the owner, which are used to verify that the owner has approved the transaction.
This function includes a verification step to ensure that the signature is valid and corresponds to the owner of the tokens.
If the signature is valid, the contract executes the transfer of tokens from the smart contract to the destinationAddress</code> specified in the proposal.</p>
Fallback function: sendFundsToOwner</code></h5>
function</span> sendFundsToOwner</span>(</span>address</span> tokenAddress</span>)</span> external</span>;</span></span></code></pre>
This function allows the owner to transfer all tokens held in the contract back to his/her own address.
This is a safety measure to ensure that the owner can reclaim their assets if the payment processor becomes unresponsive or if external conditions change unfavorably.
Emits a FallbackScenarioExecuted</code> event.
The parameter tokenAddress</code> is the address of the token which should be transferred to the owner.
In case this method is called, the contract will transfer all tokens of the given type to the owner address.</p>
Verification of the signature: 'verifySignature'</h4>
function</span> verifySignature</span>(</span></span>
    address</span> _signer</span>,</span></span>
    address</span> tokenAddress</span>,</span></span>
    uint256</span> amountToSent</span>,</span></span>
    address</span> destinationAddress</span>,</span></span>
    bytes</span> memory</span> signature</span></span>
)</span> public</span> pure</span> returns</span> (</span>bool</span>)</span>;</span></span></code></pre>
This function is used to verify the signature of the owner. It checks if the signature corresponds to the provided parameters and the owner's address.
The parameter _signer</code> is the address of the owner who signed the proposal.
The parameter tokenAddress</code> is the address of the token which should be transferred.
The parameter amountToSent</code> is the amount which should be transferred to the desired destination address.
The parameter destinationAddress</code> defines the receiver of the defined token.
The parameter signature</code> is the signed message which only includes the hash of the proposal.</p>
This function can be called by the owner to verify the signature before forwarding it to the paymentProcessor / transactionProvider.
Also this function should be called within the completeTransaction</code> function to ensure that the signature is valid before executing the transfer.</p>
Summary</h5>
The interface ITokenStorage.sol</code>:</p>
interface</span> ITokenStorage</span> {</span></span>
    event</span> TransactionProposed</span>(</span>uint256</span> hash</span>)</span>;</span></span>
    event</span> TransactionCompleted</span>(</span>uint256</span> hash</span>)</span>;</span></span>
    event</span> FallbackScenarioExecuted</span>(</span>address</span> tokenAddress</span>)</span>;</span></span>
</span>
    function</span> proposeTransaction</span>(</span>address</span> tokenAddress</span>,</span> uint256</span> amountToSent</span>,</span> address</span> destinationAddress</span>)</span> external</span>;</span></span>
    function</span> completeTransaction</span>(</span>uint256</span> hash</span>,</span> bytes</span> memory</span> signature</span>)</span> external</span>;</span></span>
    function</span> sendFundsToOwner</span>(</span>address</span> tokenAddress</span>)</span> external</span>;</span></span>
}</span></span></code></pre>Rationale</h2>
tbd </p>
Backwards Compatibility</h2>
No backward compatibility issues found.</p>


Security Considerations</h2>
Needs discussion. </p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


DomainKeys Identified Mail (DKIM) Registry
2025-06-11T00:00:00+00:00
Abstract</h2>
This EIP proposes a standard interface for registering and validating DomainKeys Identified Mail (DKIM) public key hashes on the Ethereum blockchain. The interface allows domain owners to register their DKIM public key hashes and enables third parties to verify the validity of these hashes.</p>
The registry operates by storing hashes of both domain names and DKIM public keys, creating a mapping that enables on-chain verification of DKIM signatures. Domain owners register their DKIM public key hashes by extracting the public key from their DNS TXT records (as specified in RFC 6376</a>), computing the hash, and submitting it to the registry. DKIM clients can then query the registry to verify that a given public key hash is authorized for a specific domain, enabling trustless email ownership verification for applications such as account abstraction and social recovery mechanisms.</p>
Motivation</h2>
With the growing adoption of Account Abstraction ERC-4337</a> and the emergence of ZK Email Technology, there is a need for a standardized way to verify email ownership on-chain. This EIP provides a crucial building block for these technologies by enabling the verification of DKIM signatures through on-chain registries.</p>
This standard enables several important use cases:</p>

Account Abstraction</strong>: When combined with zkEmail, this registry enables email-based account abstraction. Users can prove ownership of their email address through DKIM signatures, allowing them to:

Create and manage smart contract wallets</li>
Sign transactions using their email credentials</li>
Implement social recovery mechanisms</li>
</ul>
</li>
Account Recovery</strong>: The registry facilitates secure account recovery mechanisms:

Users can recover their wallet access by on-chain proving email ownership</li>
The process is trustless and secure due to the cryptographic nature of DKIM</li>
</ul>
</li>
</ol>
Specification</h2>
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.</p>
Interface</h3>
pragma</span> solidity</span> ^0.8.25</span>;</span></span>
///</span> @title</span> ERC-</span>XXX</span> DKIM Registry Interface</span></span>
///</span> @dev</span> See https://eips.ethereum.org/EIPS/eip-</span>xxx</span></span>
///</span> Note</span>: the ERC-165 identifier for this interface is 0xdee3d600.</span></span>
interface</span> IDKIMRegistry</span> {</span></span>
    event</span> KeyHashRegistered</span>(</span>bytes32</span> domainHash</span>, </span>bytes32</span> keyHash</span>)</span>;</span></span>
    event</span> KeyHashRevoked</span>(</span>bytes32</span> domainHash</span>)</span>;</span></span>
    function</span> isKeyHashValid</span>(</span></span>
        bytes32</span> domainHash</span>,</span></span>
        bytes32</span> keyHash</span></span>
    )</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
}</span></span></code></pre>Domain Hash</h3>
The domainHash</code> parameter MUST be the hash of the lowercase domain name or subdomain name. For example:</p>

For the domain "example.com" using keccak256:</li>
</ul>
domainHash </span>=</span> keccak256</span>(</span>bytes</span>(</span>"example.com"</span>)</span>)</span></span></code></pre>

For the subdomain "mail.example.com" using keccak256:</li>
</ul>
domainHash </span>=</span> keccak256</span>(</span>bytes</span>(</span>"mail.example.com"</span>)</span>)</span></span></code></pre>
The registry MUST treat each domain and subdomain as a distinct entity. This means that:</p>

A key hash registered for "example.com" does not automatically apply to its subdomains</li>
Each subdomain can have its own independent DKIM key hash registration</li>
The full domain name (including subdomain if present) must be hashed as a single string</li>
</ol>
Key Hash</h3>
The keyHash</code> parameter MUST be a cryptographic hash of the DKIM public key. The public key should be in the standard DKIM format as specified in RFC 6376</a>.</p>
Implementations MAY choose any cryptographically secure hash function for computing the key hash. Common choices include keccak256, Poseidon (for zk-friendly applications) or other hash functions.</p>
DKIM Public Key Specification</h3>
The DKIM public key MUST follow the format specified in RFC 6376. Here are the key requirements:</p>


Key Format</strong>:</p>

The public key MUST be in the format specified in the DKIM DNS record (p=PUBLIC_KEY)</li>
The key MUST be base64 encoded</li>
The key MUST NOT include the PEM headers or any other formatting</li>
The key MUST be the raw public key data as specified in the DKIM DNS record</li>
</ul>
</li>

Key Requirements</strong>:</p>

The key MUST be a valid RSA public key</li>
The key MUST be in the format as published in the domain's DNS TXT record</li>
The key MUST be the exact value from the p= parameter in the DKIM DNS record</li>
The key MUST NOT include any whitespace or line breaks</li>
</ul>
</li>

Key Registration Process</strong>:</p>

Obtain the DKIM public key from the domain's DNS TXT record</li>
Extract the value from the p= parameter</li>
Calculate the hash of the raw public key using the implementation's chosen hash function</li>
Register the hash in the DKIM registry</li>
</ol>
</li>

Key Validation</strong>:</p>

The registry MUST verify that the provided key hash corresponds to a valid DKIM public key</li>
The key MUST be in the correct format as specified in RFC 6376</li>
The key MUST be the exact value as published in the domain's DNS record</li>
</ul>
</li>

Example with keccak256</strong>:</p>
Given the following DKIM DNS record from RFC 6376:</p>
$ORIGIN _domainkey.example.org.</span></span>
brisbane IN  TXT  ("v=DKIM1; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQ"</span></span>
                "KBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYt"</span></span>
                "IxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v"</span></span>
                "/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhi"</span></span>
                "tdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB")</span></span>
                ```</span></span></code></pre>
The process to register this key would be:</p>

Extract the public key value from the p= parameter:</li>
</ol>
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB</span></span></code></pre></li>

Calculate the keccak256 hash of the public key:</p>
bytes32</span> keyHash </span>=</span> keccak256</span>(</span>bytes</span>(</span>"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB"</span>)</span>)</span>;</span></span></code></pre>

Calculate the domain hash:</li>
</ol>
bytes32</span> domainHash </span>=</span> keccak256</span>(</span>bytes</span>(</span>"example.org"</span>)</span>)</span>;</span></span></code></pre>

Register the key hash in the registry:</li>
</ol>
registry</span>.</span>setKeyHash</span>(</span>domainHash</span>,</span> keyHash</span>)</span>;</span></span></code></pre></li>
</ol>
Events</h3>
KeyHashRegistered</h4>
This event MUST be emitted when a new DKIM public key hash is registered for a domain.</p>
event</span> KeyHashRegistered</span>(</span>bytes32</span> domainHash</span>, </span>bytes32</span> keyHash</span>)</span></span></code></pre>KeyHashRevoked</h4>
This event MUST be emitted when a DKIM public key hash is revoked for a domain.</p>
event</span> KeyHashRevoked</span>(</span>bytes32</span> domainHash</span>)</span></span></code></pre>Functions</h3>
isKeyHashValid</h4>
This function MUST return true</code> if the provided key hash is valid for the given domain hash, and false</code> otherwise.</p>
function</span> isKeyHashValid</span>(</span></span>
    bytes32</span> domainHash</span>,</span></span>
    bytes32</span> keyHash</span></span>
)</span> external</span> view</span> returns</span> (</span>bool</span>)</span></span></code></pre>Rationale</h2>
The interface is designed to be simple and focused on the core functionality of DKIM public key hash registration and validation. The use of keccak256 hashing for both domain names and public keys ensures consistent and secure handling of the data.</p>
The events allow for efficient tracking of key registrations and revocations, which is important for maintaining the integrity of the registry.</p>
Backwards Compatibility</h2>
This EIP introduces a new interface and does not affect existing contracts or standards.</p>
Reference Implementation</h2>
pragma</span> solidity</span> ^0.8.0</span>;</span></span>
import</span> "@openzeppelin/contracts/access/Ownable.sol"</span>;</span></span>
import</span> "./interfaces/IDKIMRegistry.sol"</span>;</span></span>
contract</span> DKIMRegistry</span> is</span> IDKIMRegistry</span>, </span>Ownable</span> {</span></span>
    constructor</span>(</span>address</span> _owner</span>)</span> Ownable</span>(</span>_owner) </span>{</span> }</span></span>
    //</span> Mapping from hashed domain name to DKIM public key hash to enabled</span></span>
    mapping</span>(</span>bytes32</span> =></span> mapping</span>(</span>bytes32</span> =></span> bool</span>)</span>)</span> private</span> _keyHashes</span>;</span></span>
    /**</span></span>
     * </span>@notice</span> Checks if a DKIM key hash is valid for a given domain</span></span>
     * </span>@param</span> domainHash</span> The hash of the domain name</span></span>
     * </span>@param</span> keyHash</span> The hash of the DKIM public key</span></span>
     * </span>@return</span> bool</span> True if the key hash is valid for the domain, false otherwise</span></span>
     */</span></span>
    function</span> isKeyHashValid</span>(</span></span>
        bytes32</span> domainHash</span>,</span></span>
        bytes32</span> keyHash</span></span>
    )</span> public</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span>
        return</span> _keyHashes</span>[</span>domainHash</span>]</span>[</span>keyHash</span>]</span>;</span></span>
    }</span></span>
    /**</span></span>
     * </span>@notice</span> Sets a DKIM key hash for a domain</span></span>
     * </span>@param</span> domainHash</span> The hash of the domain name</span></span>
     * </span>@param</span> keyHash</span> The hash of the DKIM public key to register</span></span>
     * </span>@dev</span> Only callable by the contract owner</span></span>
     * </span>@dev</span> Cannot set zero hash as a valid key hash</span></span>
     */</span></span>
    function</span> setKeyHash</span>(</span></span>
        bytes32</span> domainHash</span>,</span></span>
        bytes32</span> keyHash</span></span>
    )</span> public</span> onlyOwner</span> {</span></span>
        require</span>(</span>keyHash </span>!=</span> bytes32</span>(</span>0</span>)</span>,</span> "cannot set zero hash"</span>)</span>;</span></span>
        _keyHashes</span>[</span>domainHash</span>]</span>[</span>keyHash</span>]</span> =</span> true</span>;</span></span>
        emit</span> KeyHashRegistered</span>(</span>domainHash</span>,</span> keyHash</span>)</span>;</span></span>
    }</span></span>
    /**</span></span>
     * </span>@notice</span> Sets multiple DKIM key hashes for a domain in a single transaction</span></span>
     * </span>@param</span> domainHash</span> The hash of the domain name</span></span>
     * </span>@param</span> keyHashes</span> Array of DKIM public key hashes to register</span></span>
     * </span>@dev</span> Only callable by the contract owner</span></span>
     * </span>@dev</span> Array must not be empty</span></span>
     * </span>@dev</span> Each key hash must not be zero</span></span>
     */</span></span>
    function</span> setKeyHashes</span>(</span></span>
        bytes32</span> domainHash</span>,</span></span>
        bytes32</span>[</span>]</span> memory</span> keyHashes</span></span>
    )</span> public</span> onlyOwner</span> {</span></span>
        require</span>(</span>keyHashes</span>.</span>length </span>></span> 0</span>,</span> "empty array"</span>)</span>;</span></span>
        for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> keyHashes</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span>
            setKeyHash</span>(</span>domainHash</span>,</span> keyHashes</span>[</span>i</span>]</span>)</span>;</span></span>
        }</span></span>
    }</span></span>
    /**</span></span>
     * </span>@notice</span> Revokes a DKIM key hash for a domain</span></span>
     * </span>@param</span> domainHash</span> The hash of the domain name</span></span>
     * </span>@param</span> keyHash</span> The hash of the DKIM public key to revoke</span></span>
     * </span>@dev</span> Only callable by the contract owner</span></span>
     * </span>@dev</span> Sets the key hash mapping to false, effectively revoking it</span></span>
     */</span></span>
    function</span> revokeKeyHash</span>(</span>bytes32</span> domainHash</span>,</span> bytes32</span> keyHash</span>)</span> public</span> onlyOwner</span> {</span></span>
        delete</span> _keyHashes</span>[</span>domainHash</span>]</span>[</span>keyHash</span>]</span>;</span></span>
        emit</span> KeyHashRevoked</span>(</span>domainHash</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Security Considerations</h2>

Domain owners must ensure they have control over their private keys and domain names.</li>
The registry implementation should include proper access control mechanisms to prevent unauthorized registrations.</li>
The registry should implement a mechanism to handle key rotation and revocation.</li>
Implementations should consider rate limiting to prevent spam registrations.</li>
Registries should select the domainHash</code> and keyHash</code> algorithms carefully. Upgrading the hash function must be thoughtfully planned.</li>
</ol>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


uRWA - Universal Real World Asset Interface
2025-06-10T00:00:00+00:00
Abstract</h2>
This EIP proposes the Universal RWA (uRWA) standard, a set of interfaces for tokenized Real World Assets (RWAs) such as securities, real estate, commodities, or other physical/financial assets on the blockchain.</p>
Real World Assets often require regulatory compliance features not found in standard tokens, including the ability to freeze assets, perform enforcement transfers for legal compliance, and restrict transfers to authorized users. The uRWA standard extends common token standards like ERC-20</a>, ERC-721</a> or ERC-1155</a> by introducing essential compliance functions while remaining minimal and not opinionated about specific implementation details.</p>
This enables DeFi protocols and applications to interact with tokenized real-world assets in a standardized way, knowing they can check transfer permissions, whether users are allowed to interact, handle frozen assets appropriately, and integrate with compliant RWA tokens regardless of the underlying asset type or internal compliance logic. It also adopts ERC-165</a> for introspection.</p>
Motivation</h2>
Real World Assets (RWAs) represent a significant opportunity to bridge traditional finance and decentralized finance (DeFi). By tokenizing assets like real estate, corporate bonds, commodities, art, or securities, we can unlock benefits such as fractional ownership, programmable compliance, enhanced liquidity through secondary markets for traditionally illiquid assets and integration with decentralized protocols.</p>
However, tokenizing real world assets introduces regulatory requirements often absent in purely digital assets, such as allowlists for users, transfer restrictions, asset freezing, or law enforcement rules. Existing token standards like ERC-20</a>, ERC-721</a> and ERC-1155</a> lack the inherent structure to address these compliance needs directly within the standard itself.</p>
Attempts at defining universal RWA standards historically imposed unnecessary complexity and gas overhead for simpler use cases that do not require the full spectrum of features like granular role-based access control, mandatory on-chain whitelisting, specific on-chain identity solutions, or metadata handling solutions mandated by the standard.</p>
Additionally, the broad spectrum of RWA classes inherently suggests the need to move away from a one-size-fits-all solution. This means a minimalistic approach, unopinionated features list, and maximally compatible design have been kept in mind as design goals.</p>
The uRWA standard seeks a more refined balance by defining an essential interface, establishing a common ground for interaction regarding compliance and control, without dictating the underlying implementation mechanisms. This allows core token implementations to remain lean while providing standard functions for RWA-specific interactions.</p>
The final goal is to build composable DeFi around RWAs, providing the same interface when dealing with compliance and regulation.</p>
Specification</h2>
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", and "MAY" in this document are to be interpreted as described in RFC 2119 and RFC 8174.</p>
The following defines the standard interfaces for an ERC-7943</a> token contract, which MUST extend from one base token interface such as ERC-20</a>, ERC-721</a> or ERC-1155</a>:</p>
///</span> @notice</span> Interface for ERC-20 based implementations.</span></span>
interface</span> IERC7943Fungible</span> is</span> IERC165</span> {</span></span>
    ///</span> @notice</span> Emitted when tokens are taken from one address and transferred to another.</span></span>
    ///</span> @param</span> from</span> The address from which tokens were taken.</span></span>
    ///</span> @param</span> to</span> The address to which seized tokens were transferred.</span></span>
    ///</span> @param</span> amount</span> The amount seized.</span></span>
    event</span> ForcedTransfer</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> amount</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Emitted when `setFrozenTokens` is called, changing the frozen `amount` of tokens for `account`.</span></span>
    ///</span> @param</span> account</span> The address of the account whose tokens are being frozen.</span></span>
    ///</span> @param</span> amount</span> The amount of tokens frozen after the change.</span></span>
    event</span> Frozen</span>(</span>address</span> indexed</span> account</span>, </span>uint256</span> amount</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Error reverted when an account is not allowed to transact. </span></span>
    ///</span> @param</span> account</span> The address of the account which is not allowed for transfers.</span></span>
    error</span> ERC7943CannotTransact</span>(</span>address</span> account</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Error reverted when a transfer is not allowed according to internal rules. </span></span>
    ///</span> @param</span> from</span> The address from which tokens are being sent.</span></span>
    ///</span> @param</span> to</span> The address to which tokens are being sent.</span></span>
    ///</span> @param</span> amount</span> The amount sent.</span></span>
    error</span> ERC7943CannotTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> amount</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Error reverted when a transfer is attempted from `account` with an `amount` less than or equal to its balance, but greater than its unfrozen balance.</span></span>
    ///</span> @param</span> account</span> The address holding the tokens.</span></span>
    ///</span> @param</span> amount</span> The amount being transferred.</span></span>
    ///</span> @param</span> unfrozen</span> The amount of tokens that are unfrozen and available to transfer.</span></span>
    error</span> ERC7943InsufficientUnfrozenBalance</span>(</span>address</span> account</span>,</span> uint256</span> amount</span>,</span> uint256</span> unfrozen</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Takes tokens from one address and transfers them to another.</span></span>
    ///</span> @dev</span> Requires specific authorization. Used for regulatory compliance or recovery scenarios.</span></span>
    ///</span> @param</span> from</span> The address from which `amount` is taken.</span></span>
    ///</span> @param</span> to</span> The address that receives `amount`.</span></span>
    ///</span> @param</span> amount</span> The amount to force transfer.</span></span>
    ///</span> @return</span> result</span> True if the transfer executed correctly. Reverts on failure.</span></span>
    function</span> forcedTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> amount</span>)</span> external</span> returns</span>(</span>bool</span> result</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Changes the frozen status of `amount` tokens belonging to `account`.</span></span>
    ///</span> This overwrites the current value, similar to an `approve` function.</span></span>
    ///</span> @dev</span> Requires specific authorization. Frozen tokens cannot be transferred by the account.</span></span>
    ///</span> @param</span> account</span> The address of the account whose tokens are to be frozen.</span></span>
    ///</span> @param</span> amount</span> The amount of tokens to freeze. It can be greater than account balance.</span></span>
    ///</span> @return</span> result</span> True if the freezing executed correctly. Reverts on failure.</span></span>
    function</span> setFrozenTokens</span>(</span>address</span> account</span>,</span> uint256</span> amount</span>)</span> external</span> returns</span>(</span>bool</span> result</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Checks if a specific account is allowed to transact according to token rules.</span></span>
    ///</span> @dev</span> This is often used for allowlist/KYC/KYB/AML checks.</span></span>
    ///</span> @param</span> account</span> The address to check.</span></span>
    ///</span> @return</span> allowed</span> True if the account is allowed, false otherwise.</span></span>
    function</span> canTransact</span>(</span>address</span> account</span>)</span> external</span> view</span> returns</span> (</span>bool</span> allowed</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Checks the frozen status/amount.</span></span>
    ///</span> @param</span> account</span> The address of the account.</span></span>
    ///</span> @dev</span> It could return an amount higher than the account's balance.</span></span>
    ///</span> @return</span> amount</span> The amount of tokens currently frozen for `account`.</span></span>
    function</span> getFrozenTokens</span>(</span>address</span> account</span>)</span> external</span> view</span> returns</span> (</span>uint256</span> amount</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Checks if a transfer is currently possible according to token rules. It enforces validations on the frozen tokens.</span></span>
    ///</span> @dev</span> This can involve checks like allowlists, blocklists, transfer limits and other policy-defined restrictions.</span></span>
    ///</span> @param</span> from</span> The address sending tokens.</span></span>
    ///</span> @param</span> to</span> The address receiving tokens. </span></span>
    ///</span> @param</span> amount</span> The amount being transferred.</span></span>
    ///</span> @return</span> allowed</span> True if the transfer is allowed, false otherwise.</span></span>
    function</span> canTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> amount</span>)</span> external</span> view</span> returns</span> (</span>bool</span> allowed</span>)</span>;</span></span>
}</span></span>
</span>
///</span> @notice</span> Interface for ERC-721 based implementations.</span></span>
interface</span> IERC7943NonFungible</span> is</span> IERC165</span> {</span></span>
    ///</span> @notice</span> Emitted when `tokenId` is taken from one address and transferred to another.</span></span>
    ///</span> @param</span> from</span> The address from which `tokenId` is taken.</span></span>
    ///</span> @param</span> to</span> The address to which seized `tokenId` is transferred.</span></span>
    ///</span> @param</span> tokenId</span> The ID of the token being transferred.</span></span>
    event</span> ForcedTransfer</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> tokenId</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Emitted when `setFrozenTokens` is called, changing the frozen status of `tokenId` for `account`.</span></span>
    ///</span> @param</span> account</span> The address of the account whose `tokenId` is subjected to freeze/unfreeze.</span></span>
    ///</span> @param</span> tokenId</span> The ID of the token subjected to freeze/unfreeze.</span></span>
    ///</span> @param</span> frozenStatus</span> Whether `tokenId` has been frozen or unfrozen.</span></span>
    event</span> Frozen</span>(</span>address</span> indexed</span> account</span>, </span>uint256</span> indexed</span> tokenId</span>, </span>bool</span> indexed</span> frozenStatus</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Error reverted when an account is not allowed to transact. </span></span>
    ///</span> @param</span> account</span> The address of the account which is not allowed for transfers.</span></span>
    error</span> ERC7943CannotTransact</span>(</span>address</span> account</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Error reverted when a transfer is not allowed according to internal rules. </span></span>
    ///</span> @param</span> from</span> The address from which tokens are being sent.</span></span>
    ///</span> @param</span> to</span> The address to which tokens are being sent.</span></span>
    ///</span> @param</span> tokenId</span> The id of the token being sent.</span></span>
    error</span> ERC7943CannotTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> tokenId</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Error reverted when a transfer is attempted from `account` with a `tokenId` which has been previously frozen.</span></span>
    ///</span> @param</span> account</span> The address holding the token with `tokenId`.</span></span>
    ///</span> @param</span> tokenId</span> The ID of the token being frozen and unavailable to be transferred. </span></span>
    error</span> ERC7943InsufficientUnfrozenBalance</span>(</span>address</span> account</span>,</span> uint256</span> tokenId</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Takes `tokenId` from one address and transfers it to another.</span></span>
    ///</span> @dev</span> Requires specific authorization. Used for regulatory compliance or recovery scenarios.</span></span>
    ///</span> @param</span> from</span> The address from which `tokenId` is taken.</span></span>
    ///</span> @param</span> to</span> The address that receives `tokenId`.</span></span>
    ///</span> @param</span> tokenId</span> The ID of the token being transferred.</span></span>
    ///</span> @return</span> result</span> True if the transfer executed correctly. Reverts on failure.</span></span>
    function</span> forcedTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> tokenId</span>)</span> external</span> returns</span>(</span>bool</span> result</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Changes the frozen status of `tokenId` belonging to an `account`.</span></span>
    ///</span> This overwrites the current value, similar to an `approve` function.</span></span>
    ///</span> @dev</span> Requires specific authorization. Frozen tokens cannot be transferred by the account.</span></span>
    ///</span> @param</span> account</span> The address of the account whose tokens are to be frozen.</span></span>
    ///</span> @param</span> tokenId</span> The ID of the token to freeze.</span></span>
    ///</span> @param</span> frozenStatus</span> Whether `tokenId` is being frozen or not. </span></span>
    ///</span> @return</span> result</span> True if the freezing executed correctly. Reverts on failure.</span></span>
    function</span> setFrozenTokens</span>(</span>address</span> account</span>,</span> uint256</span> tokenId</span>,</span> bool</span> frozenStatus</span>)</span> external</span> returns</span>(</span>bool</span> result</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Checks if a specific account is allowed to transact according to token rules.</span></span>
    ///</span> @dev</span> This is often used for allowlist/KYC/KYB/AML checks.</span></span>
    ///</span> @param</span> account</span> The address to check.</span></span>
    ///</span> @return</span> allowed</span> True if the account is allowed, false otherwise.</span></span>
    function</span> canTransact</span>(</span>address</span> account</span>)</span> external</span> view</span> returns</span> (</span>bool</span> allowed</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Checks the frozen status of a specific `tokenId`.</span></span>
    ///</span> @dev</span> It could return true even if account does not hold the token.</span></span>
    ///</span> @param</span> account</span> The address of the account.</span></span>
    ///</span> @param</span> tokenId</span> The ID of the token.</span></span>
    ///</span> @return</span> frozenStatus</span> Whether `tokenId` is currently frozen for `account`.</span></span>
    function</span> getFrozenTokens</span>(</span>address</span> account</span>,</span> uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>bool</span> frozenStatus</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Checks if a transfer is currently possible according to token rules. It enforces validations on the frozen tokens.</span></span>
    ///</span> @dev</span> This can involve checks like allowlists, blocklists, transfer limits and other policy-defined restrictions.</span></span>
    ///</span> @param</span> from</span> The address sending tokens.</span></span>
    ///</span> @param</span> to</span> The address receiving tokens. </span></span>
    ///</span> @param</span> tokenId</span> The ID of the token being transferred.</span></span>
    ///</span> @return</span> allowed</span> True if the transfer is allowed, false otherwise.</span></span>
    function</span> canTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>bool</span> allowed</span>)</span>;</span></span>
}</span></span>
</span>
///</span> @notice</span> Interface for ERC-1155 based implementations.</span></span>
interface</span> IERC7943MultiToken</span> is</span> IERC165</span> {</span></span>
    ///</span> @notice</span> Emitted when tokens are taken from one address and transferred to another.</span></span>
    ///</span> @param</span> from</span> The address from which tokens were taken.</span></span>
    ///</span> @param</span> to</span> The address to which seized tokens were transferred.</span></span>
    ///</span> @param</span> tokenId</span> The ID of the token being transferred.</span></span>
    ///</span> @param</span> amount</span> The amount seized.</span></span>
    event</span> ForcedTransfer</span>(</span>address</span> indexed</span> from</span>, </span>address</span> indexed</span> to</span>, </span>uint256</span> indexed</span> tokenId</span>, </span>uint256</span> amount</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Emitted when `setFrozenTokens` is called, changing the frozen `amount` of `tokenId` tokens for `account`.</span></span>
    ///</span> @param</span> account</span> The address of the account whose tokens are being frozen.</span></span>
    ///</span> @param</span> tokenId</span> The ID of the token being frozen.</span></span>
    ///</span> @param</span> amount</span> The amount of tokens frozen after the change.</span></span>
    event</span> Frozen</span>(</span>address</span> indexed</span> account</span>, </span>uint256</span> indexed</span> tokenId</span>, </span>uint256</span> amount</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Error reverted when an account is not allowed to transact. </span></span>
    ///</span> @param</span> account</span> The address of the account which is not allowed for transfers.</span></span>
    error</span> ERC7943CannotTransact</span>(</span>address</span> account</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Error reverted when a transfer is not allowed according to internal rules. </span></span>
    ///</span> @param</span> from</span> The address from which tokens are being sent.</span></span>
    ///</span> @param</span> to</span> The address to which tokens are being sent.</span></span>
    ///</span> @param</span> tokenId</span> The id of the token being sent.</span></span>
    ///</span> @param</span> amount</span> The amount sent.</span></span>
    error</span> ERC7943CannotTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> tokenId</span>,</span> uint256</span> amount</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Error reverted when a transfer is attempted from `account` with an `amount` of `tokenId` less than or equal to its balance, but greater than its unfrozen balance.</span></span>
    ///</span> @param</span> account</span> The address holding the `amount` of `tokenId` tokens.</span></span>
    ///</span> @param</span> tokenId</span> The ID of the token being transferred. </span></span>
    ///</span> @param</span> amount</span> The amount of `tokenId` tokens being transferred.</span></span>
    ///</span> @param</span> unfrozen</span> The amount of tokens that are unfrozen and available to transfer.</span></span>
    error</span> ERC7943InsufficientUnfrozenBalance</span>(</span>address</span> account</span>,</span> uint256</span> tokenId</span>,</span> uint256</span> amount</span>,</span> uint256</span> unfrozen</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Takes tokens from one address and transfers them to another.</span></span>
    ///</span> @dev</span> Requires specific authorization. Used for regulatory compliance or recovery scenarios.</span></span>
    ///</span> @param</span> from</span> The address from which `amount` is taken.</span></span>
    ///</span> @param</span> to</span> The address that receives `amount`.</span></span>
    ///</span> @param</span> tokenId</span> The ID of the token being transferred.</span></span>
    ///</span> @param</span> amount</span> The amount to force transfer.</span></span>
    ///</span> @return</span> result</span> True if the transfer executed correctly. Reverts on failure.</span></span>
    function</span> forcedTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> tokenId</span>,</span> uint256</span> amount</span>)</span> external</span> returns</span>(</span>bool</span> result</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Changes the frozen status of `amount` of `tokenId` tokens belonging to an `account`.</span></span>
    ///</span> This overwrites the current value, similar to an `approve` function.</span></span>
    ///</span> @dev</span> Requires specific authorization. Frozen tokens cannot be transferred by the account.</span></span>
    ///</span> @param</span> account</span> The address of the account whose tokens are to be frozen.</span></span>
    ///</span> @param</span> tokenId</span> The ID of the token to freeze.</span></span>
    ///</span> @param</span> amount</span> The amount of tokens to freeze. It can be greater than account balance.</span></span>
    ///</span> @return</span> result</span> True if the freezing executed correctly. Reverts on failure.</span></span>
    function</span> setFrozenTokens</span>(</span>address</span> account</span>,</span> uint256</span> tokenId</span>,</span> uint256</span> amount</span>)</span> external</span> returns</span>(</span>bool</span> result</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Checks if a specific account is allowed to transact according to token rules.</span></span>
    ///</span> @dev</span> This is often used for allowlist/KYC/KYB/AML checks.</span></span>
    ///</span> @param</span> account</span> The address to check.</span></span>
    ///</span> @return</span> allowed</span> True if the account is allowed, false otherwise.</span></span>
    function</span> canTransact</span>(</span>address</span> account</span>)</span> external</span> view</span> returns</span> (</span>bool</span> allowed</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Checks the frozen status/amount of a specific `tokenId`.</span></span>
    ///</span> @dev</span> It could return an amount higher than the account's balance.</span></span>
    ///</span> @param</span> account</span> The address of the account.</span></span>
    ///</span> @param</span> tokenId</span> The ID of the token.</span></span>
    ///</span> @return</span> amount</span> The amount of `tokenId` tokens currently frozen for `account`.</span></span>
    function</span> getFrozenTokens</span>(</span>address</span> account</span>,</span> uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>uint256</span> amount</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Checks if a transfer is currently possible according to token rules. It enforces validations on the frozen tokens.</span></span>
    ///</span> @dev</span> This can involve checks like allowlists, blocklists, transfer limits and other policy-defined restrictions.</span></span>
    ///</span> @param</span> from</span> The address sending tokens.</span></span>
    ///</span> @param</span> to</span> The address receiving tokens. </span></span>
    ///</span> @param</span> tokenId</span> The ID of the token being transferred.</span></span>
    ///</span> @param</span> amount</span> The amount being transferred.</span></span>
    ///</span> @return</span> allowed</span> True if the transfer is allowed, false otherwise.</span></span>
    function</span> canTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> tokenId</span>,</span> uint256</span> amount</span>)</span> external</span> view</span> returns</span> (</span>bool</span> allowed</span>)</span>;</span></span>
}</span></span></code></pre>canTransact</code>, canTransfer</code> and getFrozenTokens</code></h3>
These provide views into the implementing contract's compliance, transfer policy logic and freezing status. These functions:</p>


MUST NOT revert.</p>
</li>

MUST NOT change the storage of the contract.</p>
</li>

MAY depend on context (e.g., current timestamp, block number or msg.sender</code>).</p>
</li>

The canTransfer</code></p>

MUST validate that the amount</code> being transferred doesn't exceed the unfrozen amount (which is the difference between the current balance and the frozen balance).</li>
MUST perform a canTransact</code> check on the from</code> and to</code> parameters. An important documentation note is that ERC-3643</a> doesn't perform a canTransact</code> check within canTransfer</code> as required.</li>
MUST return false in general, if any permissioned rule would prevent a given transfer from succeeding. A transfer refers to any operation that emits the token’s canonical transfer event. A permissioned check can be a pausing mechanism, a call to canTransact</code> or anything else that requires privileged actors.</li>
</ul>
</li>

getFrozenTokens</code> will return the absolute frozen amount, which MAY exceed the account's current balance. In ERC-721</a> tokens, it MAY return true even if the account does not hold the token.</p>
</li>
</ul>
forcedTransfer</code></h3>
This function provides a standard mechanism for forcing a transfer from a from</code> to a to</code> address. The function:</p>

MUST directly manipulate balances or ownership to transfer the asset from from</code> to to</code> either by transferring or burning from from</code> and minting to to</code>.</li>
MUST be restricted in access.</li>
MUST perform necessary validation checks (e.g., sufficient balance/ownership of a specific token).</li>
MUST emit both the standard transfer event (from the base standard) and the ForcedTransfer</code> event.</li>
In single-party permissioned contexts:

It MAY bypass the canTransfer</code> checks. If this happens, and the transfer involves tokens that are currently counted as frozen, it MUST unfreeze the assets first and emit a Frozen</code> event before the underlying base token transfer event reflecting the change. Having the unfrozen amount changed before the actual transfer is critical for tokens that might be susceptible to reentrancy attacks doing external checks on recipients as it is the case for ERC-721</a> and ERC-1155</a> tokens.</li>
It SHOULD at least perform a canTransact</code> check on the to</code> parameter to ensure compliance.</li>
</ul>
</li>
In multi-party permissioned contexts:

It SHOULD perform the canTransfer</code> checks and SHOULD NOT bypass the frozen constraints.</li>
</ul>
</li>
MUST revert in cases where validations and/or canTransact</code> checks return false or fail.</li>
</ul>
setFrozenTokens</code></h3>
It provides a way to freeze or unfreeze assets held by a specific account. This is useful for temporary lock mechanisms. This function:</p>

MUST emit the Frozen</code> event.</li>
MUST be restricted in access.</li>
MUST allow freezing more assets than those held. This allows for future balances withholding.</li>
MUST revert in cases of logical issues or validation checks failure.</li>
</ul>
Additional Specifications</h3>
The contract MUST implement the ERC-165</a> supportsInterface</code> function and MUST return true for the bytes4</code> value (representing the interfaceId</code>):</p>

0x29388973</code> for the fungible interface.</li>
0xa8fdc849</code> for the non-fungible interface.</li>
0x5627c61a</code> for the multi token interface.</li>
</ul>
Implementations of these interfaces MUST implement the necessary functions of their chosen base standard (e.g., ERC-20</a> for the fungible interface, ERC-721</a> for the non-fungible interface and ERC-1155</a> for the multi token interface) and MUST also restrict access to sensitive functions like forcedTransfer</code> and setFrozenTokens</code> using an appropriate access control mechanism (e.g., onlyOwner</code>, Role-Based Access Control). The specific mechanism is NOT mandated by this interface standard.</p>
Implementations MUST ensure their transfer methods exhibit the following behavior:</p>

Public transfers</strong> (transfer</code>, transferFrom</code>, safeTransferFrom</code>, etc.) MUST NOT succeed in cases in which canTransfer</code> or  canTransact</code> would return false</code> for either one or both from</code> and to</code> addresses.</li>
Minting</strong> in permissionless contexts (e.g., public mint</code> functions) MUST NOT succeed for accounts where canTransact</code> on the recipient would return false</code>. In permissioned contexts (e.g., authorized minting by privileged roles), minting SHOULD respect canTransact</code> checks on the recipient, though implementations MAY bypass these checks when necessary for operational or compliance reasons.</li>
Burning</strong> in permissionless contexts (e.g., public burn</code> functions) MUST respect canTransfer</code> check, MUST respect the canTransact</code> check on the token holder and MUST NOT allow burning more assets than the unfrozen amount. In permissioned contexts (e.g., authorized burning by privileged roles), burning MAY succeed for accounts where canTransact</code> on the token holder would return false</code>, and MAY burn more assets than the unfrozen amount, in which case the contract MUST update the frozen status accordingly and emit a Frozen</code> event before the underlying base token transfer event.</li>
</ul>
The ERC7943CannotTransact</code>/ERC7943CannotTransfer</code> errors MAY be used as a general revert mechanism whenever internal calls to canTransact</code>/canTransfer</code> return false. They MAY be replaced by more specific errors depending on the custom checks performed inside those calls, or simply not used.</p>
In general, the standard prioritizes error specificity, meaning that specific errors such as ERC7943InsufficientUnfrozenBalance</code> SHOULD be thrown when applicable. The ERC7943InsufficientUnfrozenBalance</code> error SHOULD be triggered when a transfer is attempted from account</code> with an amount</code> less than or equal to its balance, but greater than its unfrozen balance or with a tokenId</code> which is currently frozen. If the amount</code> is greater than the whole balance or the tokenId</code> is not owned by the account</code>, unrelated from the frozen amount, more specific errors from the base standard SHOULD be used instead.</p>
Rationale</h2>

Minimalism:</strong> Defines only the essential functions (forcedTransfer</code>, setFrozenTokens</code>, canTransact</code>, canTransfer</code>, getFrozenTokens</code>) and associated events/errors needed for common RWA compliance and control patterns, avoiding mandated complexity or opinionated features. The reason to introduce specific errors (ERC7943CannotTransact</code>, ERC7943CannotTransfer</code> and ERC7943InsufficientUnfrozenBalance</code>) is to provide completeness with the introduced functionalities (canTransact</code>, canTransfer</code> and getFrozenTokens</code>). As dictated in the specifications, error specificity is prioritized, leaving space for implementations to accommodate more explicit errors. Regarding the events Frozen</code> and ForcedTransfer</code>, the reason for their existence is to signal uncommon</em> transfers (like in forcedTransfer</code>) but also to help off-chain indexers to correctly keep track and account for asset seizures and freezing. As mentioned in the specifications, the order in which these events are emitted in relation to the base token contract events is important in practice and merits special attention.</li>
Flexible compliance:</strong> Provides standard view functions (canTransact</code>, canTransfer</code>, getFrozenTokens</code>) for compliance checks without dictating how</em> those checks are implemented internally by the token contract. This allows diverse compliance strategies.</li>
Compatibility:</strong> Designed as an interface layer compatible with existing base standards like ERC-20</a>, ERC-721</a> and ERC-1155</a>. Implementations extend from ERC-7943</a> alongside their base standard interface. Additionally, with the adopted naming conventions, automatic backward compatibility is achieved with already existing standards like ERC-3643</a> and ERC-7518</a>.</li>
Essential enforcement rules:</strong> Includes forcedTransfer</code> and setFrozenTokens</code> as standard functions, acknowledging their importance for regulatory enforcement in the RWA space, distinct from standard transfers. Mandates access control for this sensitive function. To maintain a lean EIP, a single setFrozenTokens</code> function (which overwrites the frozen asset quantity) and one Frozen</code> event were favored over distinct freeze</code>/unfreeze</code> functions and events.</li>
ERC-165</a>:</strong> Ensures implementing contracts can signal support for this interface.</li>
</ul>
As an example, an AMM pool or a lending protocol can integrate with ERC-7943</a> based ERC-20</a> tokens by calling canTransact</code> or canTransfer</code> to handle these assets in a compliant manner. Enforcement actions like forcedTransfer</code> and setFrozenTokens</code> can either be called by third party entities or be integrated by external protocols to allow for automated and programmable compliance. Users can then expand these tokens with additional features to fit the specific needs of individual asset types, either with on-chain identity systems, historical balances tracking for dividend distributions, semi-fungibility with token metadata, and other custom functionalities.</p>
Extensibility</h3>
While this ERC provides the necessary primitives for regulated assets, any additional feature can be added through extensions. Few examples:</p>

If for any administrative function like setFrozenTokens</code> it is necessary to attach a proof to the call, the contract can have a function that batches operations like:</li>
</ol>
contract</span> TokenWithLegalProofs</span> is</span> IERC7943MultiToken</span> {</span></span>
    .</span>.</span>.</span></span>
</span>
    function</span> setFrozenTokensWithProof</span>(</span>address</span> account</span>,</span> uint256</span> tokenId</span>,</span> uint256</span> amount</span>,</span> bytes</span> calldata</span> legalProof</span>)</span> external</span> onlyOwner</span> returns</span>(</span>bool</span> result</span>)</span> {</span></span>
        ///</span> do anything with `legalProof`</span></span>
        return</span> setFrozenTokens</span>(</span>account</span>,</span> tokenId</span>,</span> amount</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>

Since the setFrozenTokens</code> function overwrites the absolute frozen amount and given the fact that the standard allows for multiple privileged accounts, some race-conditions might happen. If that's the case, one can build an extension function that works with expected values of amounts frozen, like:</li>
</ol>
function</span> setFrozenTokensIf</span>(</span>address</span> account</span>,</span> uint256</span> expectedPrev</span>,</span> uint256</span> newAmount</span>)</span> external</span> onlyOwner</span> returns</span>(</span>bool</span> result</span>)</span> {</span></span>
     require</span>(</span>frozenTokens</span>[</span>account</span>]</span> ==</span> expectedPrev</span>,</span> ERC7943ExpectedValueMismatch</span>(</span>expectedPrev</span>,</span> frozenTokens</span>[</span>account</span>]</span>)</span>)</span>;</span></span>
     return</span> setFrozenTokens</span>(</span>account</span>,</span>newAmount</span>)</span>;</span></span>
}</span></span></code></pre>
Alternatively, another solution can be using delta amounts:</p>
function</span> setFrozenTokensDelta</span>(</span>address</span> account</span>,</span> int256</span> deltaAmount</span>)</span> external</span> onlyOwner</span> returns</span>(</span>bool</span> result</span>)</span> {</span></span>
     uint256</span> actualValue </span>=</span> frozenTokens</span>[</span>account</span>]</span>;</span></span>
     if</span>(</span>deltaAmount </span>></span>=</span> 0</span>)</span> actualValue </span>+</span>=</span> uint256</span>(</span>deltaAmount</span>)</span>;</span></span>
     else</span> {</span></span>
        uint256</span> sub </span>=</span> uint256</span>(</span>-</span>deltaAmount</span>)</span>;</span></span>
        require</span>(</span>sub </span><</span>=</span> actualValue</span>,</span> ERC7943ExpectedValueMismatch</span>(</span>sub</span>,</span> actualValue</span>)</span>)</span>;</span></span>
        actualValue </span>-</span>=</span> sub</span>;</span></span>
     }</span></span>
     return</span> setFrozenTokens</span>(</span>account</span>,</span> actualValue</span>)</span>;</span></span>
}</span></span></code></pre>
Note</em> These helpers reduce accidental overwrites and expand in functionalities but do not prevent same-block conflicting updates or mempool ordering races by different privileged actors.</p>

Developers can also perform several operations through the use of multicall</code> patterns similar to the one defined in ERC-6357</a> so that a mix of the given primitives with additional features can be batched in one transaction:</li>
</ol>
contract</span> ERC7943Fungible</span> is</span> IERC7943Fungible</span>, </span>Multicall</span> {</span></span>
    //</span> Now any combination of `setFrozenTokens`/`forcedTransfer` </span></span>
    //</span> coupled with other functionalities like the ones to blacklist/whitelist users</span></span>
    //</span> can be submitted in one transaction through the use of `multicall` function</span></span>
}</span></span></code></pre>

Functionalities like pausability can be added on top, either through the use of modifiers or directly within functions implementations:</li>
</ol>
    function</span> canTransfer</span>(</span>address</span> from</span>,</span> address</span> to</span>,</span> uint256</span> amount</span>)</span> external</span> view</span> returns</span> (</span>bool</span> allowed</span>)</span> {</span></span>
        if</span>(</span>paused</span>(</span>)</span>)</span> return</span> allowed</span>;</span></span>
        //</span> ... other checks</span></span>
    }</span>;</span></span>
}</span></span></code></pre>Notes on naming</h3>
The naming conventions in this ERC were carefully chosen to establish clarity and semantic consistency within the broader RWA ecosystem while maintaining neutrality and broad applicability.</p>

forcedTransfer</code></strong>: This term was selected for its neutrality. While names like confiscation</em>, revocation</em>, or recovery</em> describe specific motivations, forcedTransfer</code> purely denotes the direct action of transferring assets, irrespective of the underlying reason. forcedTransfer</code> was preferred over forceTransfer</code> to maintain backward compatibility with ERC-3643</a>.</li>
canTransfer</code></strong>: This name was preferred over isTransferAllowed</code> for consistency with established RWA standards including ERC-3643</a> and ERC-7518</a>. This alignment promotes interoperability and reduces cognitive overhead when working across different RWA tokens.</li>
setFrozenTokens</code> / getFrozenTokens</code></strong>: These names were chosen for managing transfer restrictions and align with ERC-3643</a> naming patterns. Frozen</em> was also selected for its general applicability to both fungible (amount-based) and non-fungible (status-based) assets, as terms like amount</em> or asset(s)</em> might not be universally fitting.</li>
ERC7943InsufficientUnfrozenBalance</code></strong>: Discussions around insufficient</em> being similar to unavailable</em> arose, where unavailable</em> might have better suggested a temporal condition like a freezing status. However, the term available</em>/unavailable</em> was also overlapping with frozen</em>/unfrozen</em> creating more confusion and duality. Finally, coupling insufficient</em> with the specified unfrozen balance</em> better represents the domain, prefix and subject of the error, according to ERC-6093</a> guidelines.</li>
</ul>
Backwards Compatibility</h2>
This EIP defines a new interface standard and does not alter existing ones like ERC-20</a>, ERC-721</a> and ERC-1155</a>. Standard wallets and explorers can interact with the base token functionality of implementing contracts, subject to the rules enforced by that contract's implementation of canTransact</code>, canTransfer</code> and getFrozenTokens</code> functions. Full support for the ERC-7943</a> functions requires explicit integration.</p>
Reference Implementation</h2>
Reference implementations of uRWA for ERC-20</a>, ERC-721</a> and ERC-1155</a> token implementations is provided in assets folder. They use the OpenZeppelin library and include an account whitelist and enumerable role-based access control. These examples are provided for educational purposes only and are not audited.</p>
Security Considerations</h2>

Access Control for forcedTransfer</code> and setFrozenTokens</code>:</strong> The security of the mechanism chosen by the implementer to restrict access to these functions is paramount. Unauthorized access could lead to asset theft. Secure patterns (multisig, timelocks) are highly recommended.</li>
Front-run of the setFrozenTokens</code> function:</strong> The setFrozenTokens</code> function might be susceptible to front-running, similar to the approve</code> function of the ERC-20</a>. If the suggestion of allowing freezing more than what an account owns is not followed, a front-run might be an incentive to an account to avoid any attempt of freezing its balance. Additional features to gradually increment or decrement the frozen status MAY be considered for implementation.</li>
Implementation Logic:</strong> The correctness of the implementation</em> behind all interface functions is critical. Flaws in this logic could bypass intended transfer restrictions or incorrectly block valid transfers.</li>
Standard Contract Security:</strong> Implementations MUST adhere to general smart contract security best practices (reentrancy guards where applicable, checks-effects-interactions, etc.). Specifically in the checks-effects-interactions consideration, implementations need to be aware of tokens having hooks, especially on recipients like in ERC-721</a> or ERC-1155</a>. In such circumstances it might be convenient to adopt reentrancy guards to prevent unwanted executions.</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Proof-based Broadcast in ERC-7786 Gateways
2025-06-06T00:00:00+00:00
Abstract</h2>
This document defines standardized broadcasting semantics and attributes for ERC-7786</a> cross-chain messaging that enable trustless message verification through cryptographic proofs. Messages are committed on source chains in verifiable ways, then verified on destination chains using cryptographic proofs of the source chain's state or transaction history. This approach provides cross-chain communication without relying on external validators or bridge operators.</p>
Motivation</h2>
Cross-chain messaging protocols typically rely on external validators, multisigs, or optimistic mechanisms that introduce trust assumptions and potential points of failure. Cryptographic proofs offer an alternative approach where messages can be verified using the consensus mechanisms and cryptographic commitments of the chains themselves (e.g. storage proofs for EVM chains).</p>
However, cryptographic proof verification requires chain-specific routing information, proof data, and verification parameters that are not addressed by the base ERC-7786</a> interface. Additionally, while ERC-7786</a> defines basic broadcasting through "omitted or zeroed" recipient addresses, it does not specify granular broadcasting patterns that enable targeting specific chains or chain types. Enhanced broadcasting semantics enable messages to be sent with varying levels of specificity, from all addresses on a specific chain to all supported infrastructure.</p>
This document standardizes these requirements as ERC-7786</a> attributes, enabling cryptographic proof-based messaging within the established cross-chain messaging framework. The specification supports multi-hop verification paths, allowing messages to traverse through multiple intermediary chains when direct verification is not possible.</p>
The key benefits of this approach include:</p>

Trustless verification</strong>: No external validators or multisigs required. Chains trust their own consensus mechanisms.</li>
Universal compatibility</strong>: Works between chains with verifiable state relationships through shared settlement infrastructure or compatible proof systems.</li>
Flexible messaging patterns</strong>: Supports both targeted and granular broadcast messaging through standardized semantics, enabling new classes of applications like oracles and intent settlement systems.</li>
Composability</strong>: Full integration with existing ERC-7786</a> infrastructure and tooling</li>
</ul>
Specification</h2>
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.</p>
Broadcasting Semantics</h3>
ERC-7786</a> defines broadcasting as using "omitted or zeroed" recipient addresses (containing an ERC-7930</a> interoperable address with all fields set to zero). This specification extends that concept to enable granular broadcasting patterns through ERC-7930</a>'s flexible address structure:</p>
Broadcasting semantics in this specification extend ERC-7786</a> by allowing:</p>

Interoperable addresses with AddressLength</code> set to 0 and specified ChainType</code> and/or ChainReference</code> to broadcast messages to all addresses on a given chain</li>
Interoperable addresses with ChainReferenceLength</code> set to 0 and a specified ChainType</code> to broadcast to all chains of a given type</li>
Interoperable addresses with all fields set to zero to indicate universal broadcasting to all supported chains and addresses</li>
</ul>
Receivers of broadcast messages SHOULD validate the source and authenticity of messages according to their own security requirements.</p>
Cryptographic Proof Attributes</h3>
This specification defines the following ERC-7786</a> attributes for cryptographic proof messaging. Gateways MUST return true if supportsAttribute</code> is called with the selector for supported attributes.</p>
route((bytes,bytes,uint256)[])</code></h4>
Specifies the verification path from destination to source chain with corresponding proofs and version requirements. Each tuple contains a bytes-encoded address that SHOULD be called for verification of the next chain's state or transaction history, the cryptographic proof required for that verification step, and the expected version of the verification logic (0 means any version is acceptable). The route address MAY invoke other gateways to resend the message to the next hop.</p>
When a non-zero version is specified, gateways MUST reject messages if the route address does not support the exact required version (unless 0</code>). Route addresses SHOULD implement version querying mechanisms to enable compatibility checking.</p>
The route MUST form a valid path where each step represents a direct relationship between chains that enables state or transaction verification. For multi-hop scenarios, the route creates a chain of trust where each step verifies the next, ultimately establishing the authenticity of the source chain's state. Gateways MUST reject messages with invalid or incomplete proof data.</p>
abi</span>.</span>encodeWithSignature</span>(</span>"route((bytes,bytes,uint256)[])"</span>,</span> hops</span>)</span>;</span></span></code></pre>inclusionProof(bytes)</code></h4>
The cryptographic proof demonstrating that a specific message exists in the source chain's committed state at a finalized block or transaction. For EVM chains, this would typically be an event inclusion proof or storage proof.</p>
ERC-7786</a> receivers MUST validate the cryptographic proof according to the source chain's proof system.</p>
abi</span>.</span>encodeWithSignature</span>(</span>"inclusionProof(bytes)"</span>,</span> proofData</span>)</span>;</span></span></code></pre>targetBlock(uint256)</code></h4>
Specifies the block number or height on the source chain where the message was committed. For chains that don't use sequential block numbers, this represents the equivalent commitment identifier.</p>
ERC-7786</a> receivers MAY validate the target block for freshness or finality requirements according to their security policies. Receivers MAY ignore this attribute if not needed for their use case.</p>
When provided, this attribute SHOULD correspond to the block or commitment whose state is proven by the cryptographic proof.</p>
abi</span>.</span>encodeWithSignature</span>(</span>"targetBlock(uint256)"</span>,</span> blockNumber</span>)</span>;</span></span></code></pre>Relationship to Existing Proof Protocols</h3>
This ERC provides standard attributes that enable protocols like ERC-7888</a> (for EVM storage proofs) and other proof systems to implement ERC-7786</a> gateways without rebuilding their core verification logic. For example, an ERC-7888</a> Broadcaster MAY expose an ERC-7786</a> interface using these attributes while maintaining its existing storage proof architecture. Similarly, other proof systems can implement these same attributes using their native proof mechanisms.</p>
Caching</h3>
Gateways implementing this specification MAY implement caching mechanisms to optimize repeated proof verifications.</p>
Mutability of Message Commitments</h3>
Gateways MAY choose to commit messages in ways that cannot be deleted or modified after being set, providing immutability guarantees. While not required by this standard, implementers can use ERC-7201</a> to calculate namespaces for immutable storage locations on EVM chains, or equivalent immutability mechanisms on other chain architectures.</p>
Verification Process</h3>
In ERC-7786</a>, the payload</code> contains the actual message data to be delivered, while the attributes</code> contain proof metadata that establishes the payload's authenticity. The destination gateway validates the attributes through cryptographic verification, and it MAY cache results for future use.</p>
For multihop scenarios, each route step verifies the next chain's state commitment, creating a chain of trust from destination to source. This enables message verification across multiple intermediate chains, similar to systems like ERC-7888</a>'s BlockHashProver chains.</p>
Message verification follows these steps:</p>

Parse the route</code> and inclusionProof</code> attributes from the message, and optionally targetBlock</code> if provided</li>
Validate all required attributes are present and well-formed</li>
For each route step, verify block hash transition or equivalent state commitment using the paired proof and validate version requirements if specified (non-zero)</li>
Use the inclusionProof</code> to verify that message data exists in the source chain's committed state at the target block obtained from the route verification. The source chain SHOULD correspond to the final validated step in the route verification process</li>
Optionally validate the targetBlock</code> for freshness or finality requirements if the attribute is provided and the receiver chooses to validate it</li>
Execute the message if all verifications pass</li>
</ol>
Rationale</h2>
This standard extends ERC-7786</a>'s attribute system to add cryptographic proof capabilities without creating new interfaces. This approach maintains compatibility with existing infrastructure while enabling trustless cross-chain verification, allowing implementations to focus on proof verification logic rather than rebuilding messaging infrastructure.</p>
Broadcasting and Cryptographic Proofs</h3>
ERC-7786</a> natively supports broadcasting through "omitted or zeroed" ERC-7930</a> interoperable addresses. This specification extends that foundation to enable granular broadcasting patterns through ERC-7930</a>'s flexible address structure. Empty address components (AddressLength</code> = 0) allow broadcasting to all addresses on a specific chain, while empty chain references (ChainReferenceLength</code> = 0) enable broadcasting to all chains of a specific type (e.g., all EVM chains via eip155</code> namespace). Universal broadcasting uses fully zeroed addresses as defined in ERC-7786</a>.</p>
This multi-level broadcasting approach leverages ERC-7930</a>'s inherent address structure and ERC-7786</a>'s existing broadcast semantics rather than introducing new patterns, ensuring consistency with the cross-chain messaging ecosystem. The granularity enables efficient message distribution patterns: oracle feeds can target specific chains, governance messages can address entire chain families, and emergency notifications can reach all supported infrastructure.</p>
Cryptographic proofs provide trustless verification relying only on chain consensus mechanisms. This approach offers universal accessibility, cryptographic guarantees, cost efficiency (gas only on source/destination chains), and enables implicit batching through shared state commitments. Multi-hop routing extends this capability to chains without direct verification relationships.</p>
Attribute Design</h3>
The two required attributes provide the essential functionality for cryptographic proof verification, while the optional targetBlock</code> attribute enables additional freshness and finality validation when needed. Combining route information into a single tuple maintains type safety while separating proof verification from chain state transitions allows independent optimization. The optional nature of targetBlock</code> provides implementation flexibility without adding unnecessary complexity to basic use cases.</p>
Caching</h3>
Caching can improve performance by storing verification results for reuse. Since proofs are deterministic, they can be safely cached. This is especially useful for broadcast messages that need multiple verifications. Implementations should cache both block hash transitions and proof verification results, while invalidating the cache when proof infrastructure changes.</p>
Mutability of Message Commitments</h3>
Proving a commitment that could be deleted or modified may introduce additional security risks. For example, if a message is committed in a way that allows deletion after the message is sent, the proof will still be valid. This is why the specification does not require immutability, but allows gateways to choose to commit messages in immutable ways if they so desire.</p>
Backwards Compatibility</h2>
This ERC extends ERC-7786</a> through its attribute system and introduces no breaking changes to existing implementations. Gateways that do not support cryptographic proof attributes will simply reject messages containing them, which is the expected behavior for unsupported features.</p>
Existing ERC-7786</a> tooling and infrastructure can immediately leverage cryptographic proof messaging without modification, as the base interface remains unchanged.</p>
Reference Implementation</h2>
Basic Gateway Usage</h3>
struct</span> Hop</span> {</span></span>
    bytes</span> gateway</span>;</span> //</span> bytes-encoded address of the gateway</span></span>
    bytes</span> proof</span>;</span></span>
    uint256</span> version</span>;</span> //</span> 0 = any version</span></span>
}</span></span>
</span>
//</span> Prepare route with proofs and version requirements</span></span>
Hop</span>[</span>]</span> memory</span> hops </span>=</span> new</span> Hop</span>[</span>]</span>(</span>2</span>)</span>;</span></span>
hops</span>[</span>0</span>]</span> =</span> Hop</span>(</span>gateway1</span>,</span> proof1</span>,</span> 1</span>)</span>;</span> //</span> Require version 1</span></span>
hops</span>[</span>1</span>]</span> =</span> Hop</span>(</span>gateway2</span>,</span> proof2</span>,</span> 0</span>)</span>;</span> //</span> Any version acceptable</span></span>
</span>
//</span> Example 1: Address Broadcasting - broadcast to all addresses on Arbitrum One (42161)</span></span>
bytes</span> memory</span> addressBroadcast </span>=</span> abi</span>.</span>encodePacked</span>(</span></span>
    uint16</span>(</span>1</span>)</span>,</span>        //</span> Version</span></span>
    uint16</span>(</span>0x0000</span>)</span>,</span>   //</span> ChainType: eip155</span></span>
    uint8</span>(</span>2</span>)</span>,</span>         //</span> ChainReferenceLength: 2 bytes for chain ID</span></span>
    uint16</span>(</span>42161</span>)</span>,</span>    //</span> ChainReference: Arbitrum One (42161)</span></span>
    uint8</span>(</span>0</span>)</span>          //</span> AddressLength: 0 (empty address = broadcast to all addresses)</span></span>
)</span>;</span></span>
</span>
//</span> Example 2: Chain Type Broadcasting - broadcast to all EIP-155 chains</span></span>
bytes</span> memory</span> chainTypeBroadcast </span>=</span> abi</span>.</span>encodePacked</span>(</span></span>
    uint16</span>(</span>1</span>)</span>,</span>        //</span> Version</span></span>
    uint16</span>(</span>0x0000</span>)</span>,</span>   //</span> ChainType: eip155</span></span>
    uint8</span>(</span>0</span>)</span>,</span>         //</span> ChainReferenceLength: 0 (broadcast to all chains of this type)</span></span>
    uint8</span>(</span>0</span>)</span>          //</span> AddressLength: 0 (empty address)</span></span>
)</span>;</span></span>
</span>
//</span> Example 3: Universal Broadcasting - broadcast to all supported chains and addresses</span></span>
bytes</span> memory</span> universalBroadcast </span>=</span> abi</span>.</span>encodePacked</span>(</span></span>
    uint16</span>(</span>1</span>)</span>,</span>        //</span> Version</span></span>
    uint16</span>(</span>0x0000</span>)</span>,</span>   //</span> ChainType: 0 (all chain types)</span></span>
    uint8</span>(</span>0</span>)</span>,</span>         //</span> ChainReferenceLength: 0 (all chains)</span></span>
    uint8</span>(</span>0</span>)</span>          //</span> AddressLength: 0 (all addresses)</span></span>
)</span>;</span></span>
</span>
bytes</span>[</span>]</span> memory</span> attributes </span>=</span> new</span> bytes</span>[](</span>3</span>)</span>;</span></span>
attributes</span>[</span>0</span>]</span> =</span> abi</span>.</span>encodeWithSignature</span>(</span>"route((bytes,bytes,uint256)[])"</span>,</span> hops</span>)</span>;</span></span>
attributes</span>[</span>1</span>]</span> =</span> abi</span>.</span>encodeWithSignature</span>(</span>"inclusionProof(bytes)"</span>,</span> proofData</span>)</span>;</span></span>
attributes</span>[</span>2</span>]</span> =</span> abi</span>.</span>encodeWithSignature</span>(</span>"targetBlock(uint256)"</span>,</span> blockNumber</span>)</span>;</span> //</span> Optional</span></span>
</span>
//</span> Send message with address broadcasting</span></span>
gateway</span>.</span>sendMessage</span>(</span></span>
    addressBroadcast</span>,</span> //</span> broadcast to all addresses on Arbitrum One</span></span>
    abi</span>.</span>encode</span>(</span>"priceUpdate"</span>,</span> asset</span>,</span> price</span>)</span>,</span></span>
    attributes</span></span>
)</span>;</span></span>
</span>
//</span> Send message with chain type broadcasting  </span></span>
gateway</span>.</span>sendMessage</span>(</span></span>
    chainTypeBroadcast</span>,</span> //</span> broadcast to all EIP-155 chains</span></span>
    abi</span>.</span>encode</span>(</span>"governanceProposal"</span>,</span> proposalId</span>,</span> votingPeriod</span>)</span>,</span></span>
    attributes</span></span>
)</span>;</span></span>
</span>
//</span> Send message with universal broadcasting</span></span>
gateway</span>.</span>sendMessage</span>(</span></span>
    universalBroadcast</span>,</span> //</span> broadcast to all supported chains and addresses</span></span>
    abi</span>.</span>encode</span>(</span>"pause"</span>,</span> reason</span>)</span>,</span></span>
    attributes</span></span>
)</span>;</span></span></code></pre>Security Considerations</h2>
Validation Requirements</h3>
Gateways must rigorously validate all proof data to prevent message forgery, including proof format, completeness, and cryptographic validity. Route addresses must correspond to legitimate proof infrastructure forming a valid, connected path between chains. Only finalized blocks or equivalent commitment points should be used for proof generation to prevent reorganization attacks.</p>
Consumers of cryptographic proof messages should implement appropriate freshness checks, as proofs can verify messages at any historical block or commitment, potentially including very old messages. This is not required for gateways offering immutable message commitments.</p>
Route Security</h3>
The security of a multi-hop route is only as strong as the weakest proof in the verification path. When multiple route steps are used, the overall security level is determined by the step with the lowest cryptographic guarantees or the least secure consensus mechanism. Implementers should carefully evaluate each hop in their routes and consider the cumulative security implications when designing cross-chain verification paths.</p>
Broadcast Message Security</h3>
Since broadcast messages can be executed by any party, receivers should implement robust validation of message sources and contents. This includes verifying the sender's authority and the message's semantic validity.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Crosschain EIP-712 Signatures
2025-06-05T00:00:00+00:00
Abstract</h2>
This ERC defines a standard approach for creating and verifying crosschain signatures using EIP-712</a>. By omitting the chainId</code> field from the EIP-712 domain, a signature can be valid across multiple chains. Chain-specific operations are encoded as an array of structured messages, where each chain receives the array of message hashes and only the full message data relevant to that chain. This enables efficient crosschain signature validation using standard EIP-712 encoding without requiring special wallet support.</p>
Motivation</h2>
Current account abstraction solutions require separate signatures for each blockchain network. This creates poor user experience for crosschain operations such as:</p>

Crosschain intents</strong>: Users wanting to trade assets across multiple chains atomically</li>
Multi-chain DAO governance</strong>: Voting on proposals that affect protocol instances across different networks</li>
Unified account management</strong>: Managing the same account deployed on multiple chains</li>
Crosschain social recovery</strong>: Recovery processes that span multiple networks</li>
</ul>
Existing proposals either require complex Merkle tree constructions (which need wallet-specific UI to verify all leaves) or non-standard encoding schemes that lack wallet adoption. This ERC provides a simpler approach using only standard EIP-712 encoding with array types, enabling crosschain signatures with minimal on-chain overhead while maintaining full transparency in standard wallet signing interfaces.</p>
Specification</h2>
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.</p>
Crosschain Domain Semantics</h3>
A crosschain EIP-712</a> signature MUST omit the chainId</code> field from the EIP712Domain</code> type and domain object. Since chainId</code> is optional per EIP-712</a>, omitting it signals that the signature is intended for crosschain validity.</p>
Contract addresses and chainIds MUST be validated per-chain, so typically, only name</code> and version</code> are included in the main domain. The verifyingContract</code> field MAY be used to bind the signature to a specific application deployed deterministically on the same address across all chains the signature is intended to be valid on, allowing to omit the contract address from the chain-specific structs.</p>
Message Array Encoding</h3>
Crosschain operations MUST be encoded as an array of message structs with chain-specific fields. Each struct in the array SHOULD include the target chainId</code> field. When contracts are deployed at different addresses across chains, the struct SHOULD also include the verifyingContract</code> (or equivalent) field to bind each operation to its specific contract address unless the main domain includes the verifyingContract</code> field.</p>
Implementers MAY use the canonical EIP712Domain</code> struct but named to avoid collisions with EIP712Domain</code> (e.g., EIP712ChainDomain</code>) so it can be nested inside the chain-specific structs, allowing to include the chainId</code> and verifyingContract</code> fields.</p>
Per EIP-712</a>, arrays are encoded as keccak256(encodeData(element[0]) ‖ encodeData(element[1]) ‖ ... ‖ encodeData(element[n]))</code>, where each element is a struct that is recursively encoded as hashStruct(element[i])</code>, and nested structs are also recursively hashed.</p>
In practice, this means the array of chain-specific operations is represented as an array of pre-computed bytes32</code> struct hashes (one for each chain). The hash of this array is computed as keccak256(abi.encodePacked(structsArray))</code>, which concatenates all 32-byte hashes and produces the array hash that matches the standard EIP-712</a> array encoding for reference types.</p>
Struct Hash</h4>
Per EIP-712</a>, the signature is computed over a complete message struct (e.g., CrossChainIntent</code>, MultiChainVote</code>), not just the array of operations. Applications implementing verification MUST define a type hash for the complete message struct that includes the array of operations.</p>
Wrapping the array of operations in a main struct also allows to include other message fields (e.g., nonce</code>, deadline</code>) in the struct hash. For example, for a CrossChainIntent</code> struct would be encoded as:</p>
   bytes32</span> constant</span> CROSSCHAIN_INTENT_TYPEHASH </span>=</span> keccak256</span>(</span></span>
       "CrossChainIntent(ChainOperation[] operations,uint256 nonce,uint256 deadline)ChainOperation(EIP712ChainDomain domain,address target,uint256 value,bytes data)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span></span>
   )</span>;</span></span>
</span>
   fullStructHash </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span>
       CROSSCHAIN_INTENT_TYPEHASH</span>,</span></span>
       keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>chainOperationsArray</span>)</span>)</span>,</span></span>
       nonce</span>,</span></span>
       deadline</span></span>
   )</span>)</span>;</span></span></code></pre>
Applications implementing verification MUST use the same typehash across all chains where the application is deployed.</p>
On-Chain Verification</h3>
To enable applications to detect and verify crosschain signatures through standard ECDSA validation or ERC-1271</a> isValidSignature</code> calls, crosschain signatures SHOULD be encoded with metadata in the signature parameter. The signature validation flow requires the contract application to detect the encoding of this ERC, parse the signature components, and then verify the signature agains the reconstructed crosschain message hash.</p>
The signature encoding format uses ABI encoding for dynamic types (arrays and bytes) with the following structure:</p>
[0x00:0x09] magic (9 bytes)</span></span>
[0x09:0x0a] fields (1 byte)</span></span>
[0x0a:0x0c] structIndex (2 bytes, big-endian uint16)</span></span>
[0x0c:0x20] application (20 bytes)</span></span>
[0x20:0x40] structsArrayOffset (32 bytes, big-endian uint256, offset to structsArray location)</span></span>
[structsArrayOffset:structsArrayOffset + 32] structsArrayLength (32 bytes, big-endian uint256)</span></span>
[structsArrayOffset + 32:structsArrayOffset + 32 + structsArrayLength * 32] structsArray (structsArrayLength * 32 bytes)</span></span>
[crossChainSignatureOffset:crossChainSignatureOffset + 32] crossChainSignatureLength (32 bytes, big-endian uint256)</span></span>
[crossChainSignatureOffset + 32:crossChainSignatureOffset + 32 + crossChainSignatureLength] crossChainSignature (crossChainSignatureLength bytes)</span></span></code></pre>
Equivalent to the following ABI encoding:</p>
bytes32</span> header </span>=</span> bytes32</span>(</span>abi</span>.</span>encodePacked</span>(</span>CrossChainSignatureChecker</span>.</span>ERC7964_MAGIC</span>,</span> fields</span>,</span> structIndex</span>,</span> address</span>(</span>application</span>)</span>)</span>)</span>;</span></span>
abi</span>.</span>encode</span>(</span>header</span>,</span> structsArray</span>,</span> crossChainSignature</span>)</span>;</span> //</span> (bytes32, bytes, bytes32[])</span></span></code></pre>
Where:</p>

magic</code></strong>: A fixed 9-byte value 0x796479647964796479</code> used to detect encoded crosschain signatures</li>
fields</code></strong>: A single byte encoding which EIP-712</a> domain fields are present (per ERC-5267</a>)</li>
structIndex</code></strong>: The index in the structsArray</code> corresponding to the current chain's operation</li>
application</code></strong>: The address of a contract implementing ERC-5267</a> that provides the EIP-712</a> domain information</li>
structsArrayOffset</code></strong>: The offset (in bytes) from the start of the signature to where the structsArray</code> begins.</li>
structsArrayLength</code></strong>: The number of elements in the structs array</li>
structsArray</code></strong>: Array of bytes32</code> hashes, one per chain operation</li>
crossChainSignatureOffset</code></strong>: The offset (in bytes) from the start of the signature to where the crossChainSignature</code> begins.</li>
crossChainSignatureLength</code></strong>: The length of the crosschain signature in bytes</li>
crossChainSignature</code></strong>: The actual signature bytes that sign the crosschain message</li>
</ul>
This encoding allows applications to identify when a signature is a crosschain signature, rebuild the EIP-712 domain information needed to reconstruct the expected typed hash, and verify the signature against the reconstructed crosschain message hash.</p>
Applications can detect crosschain signatures by checking if the first 9 bytes of the signature equal the magic value 0x796479647964796479</code>. If detected, applications MUST:</p>

Parse the encoded metadata from the signature</li>
Verify that structsArray[structIndex]</code> matches the struct hash of the current chain's message</li>
Query the ERC-5267</a> contract at application</code> to obtain the EIP-712 domain</li>
Reconstruct the full EIP-712</a> hash using the domain, the main struct hash and the array of chain-specific struct hashes</li>
Verify the crossChainSignature</code> against the reconstructed typed hash</li>
</ol>
Wallet Display</h3>
Standard EIP-712</a> wallets will automatically display the array of chain-specific messages in a readable format. Wallets MAY enhance the display by grouping operations by chain and showing chain names instead of chain IDs for better user experience.</p>
Rationale</h2>
Standard EIP-712 Compatibility</h3>
This ERC uses only standard EIP-712</a> encoding without any extensions or special constructs. All fields in the EIP712Domain</code> are optional per the standard, so omitting chainId</code> is perfectly valid. This means any wallet that supports EIP-712 can sign these messages and any application that supports EIP-712 can verify them.</p>
The main benefit of this approach is that users can achieve a full transparent view of the crosschain message in any wallet provider that supports EIP-712</a>.</p>
Main Struct Hash</h3>
For wallet providers to show the crosschain message properly, they need a primaryType</code> to display the message. This specification does not mandate a specific primaryType</code> to allow for flexibility in the implementation, but defines the requirements for the array of operations and the main struct to ensure a secure EIP-712 message.</p>
The specification requires that each of the operations include the chainId</code> field to avoid replaying the same operation on other chains. The verifyingContract</code> field (or equivalent) is used to bind the operation to its specific contract address and is optional if the main EIP712Domain</code> includes the verifyingContract</code> field since the domain hash would include the application's address.</p>
Array Encoding vs Merkle Trees</h3>
Alternative approaches use Merkle trees to commit to crosschain operations. While Merkle trees can reduce on-chain overhead for many chains, they have a critical drawback:</p>
Wallet Verification Complexity</strong>: Standard EIP-712 wallets cannot display Merkle tree leaves. Users signing a Merkle root have no way to verify all operations in their wallet UI. Wallets would need to implement custom logic to:</p>

Request all leaves from the application</li>
Verify the Merkle tree construction</li>
Display all operations across all chains</li>
Ensure no malicious operations are hidden</li>
</ol>
This breaks the principle of trustless signing, users must trust the application to correctly provide all leaves, and wallet developers must implement and maintain custom verification logic.</p>
The array-based approach provides full transparency</strong> using standard EIP-712. Users see all chain-specific operations in any compliant wallet without custom support. No hidden operations are possible since all array elements are displayed as part of the standard EIP-712 message structure.</p>
On-chain overhead comparison</strong>: For reasonable crosschain operations, the overhead difference is minimal.</p>
With the array approach, each chain receives all N operation hashes (N × 32 bytes</code>). With Merkle trees (assuming a binary tree), each chain receives a Merkle proof of size ceil(log₂(N)) × 32 bytes</code>. Both approaches reconstruct the root/array hash on-chain from the provided data and verify it against the signature, no additional calldata for the root is needed. While Merkle proofs grow logarithmically vs. the array's linear growth, the practical savings are small for reasonable use cases:</p>
Chains</th> Array (N × 32)</th> Merkle (⌈log₂(N)⌉ × 32)</th> Savings</th></tr></thead>

2</td> 64 bytes (2 × 32)</td> 32 bytes (1 × 32)</td> 32 bytes (1 hash)</td></tr>
3</td> 96 bytes (3 × 32)</td> 64 bytes (2 × 32)</td> 32 bytes (1 hash)</td></tr>
4</td> 128 bytes (4 × 32)</td> 64 bytes (2 × 32)</td> 64 bytes (2 hashes)</td></tr>
5</td> 160 bytes (5 × 32)</td> 96 bytes (3 × 32)</td> 64 bytes (2 hashes)</td></tr>
8</td> 256 bytes (8 × 32)</td> 96 bytes (3 × 32)</td> 160 bytes (5 hashes)</td></tr>
</tbody></table>
For 2-5 chains (the reasonable case for crosschain operations), Merkle trees save only 32-64 bytes (1-2 hashes) per transaction. This minimal savings doesn't justify the complexity and loss of transparency. Merkle trees only become significantly more efficient at 8+ chains, which is an uncommon use case and may indicate the operation should be split into multiple signatures for better user comprehension and failure isolation.</p>
Omitting chainId vs using 0</code></h3>
Omitting chainId</code> entirely is cleaner than using a special value like 0</code> because it explicitly signals that the signature is intended for crosschain validity.</p>
Signature Encoding Format</h3>
The custom binary encoding format for crosschain signatures was selected to minimize calldata and memory overhead. The format packs metadata values that can be read to the stack and uses ABI encoding for structsArray</code> and crossChainSignature</code> for easy calldata and memory casting.</p>
The magic value is used to detect crosschain signatures and is designed to be easy to parse and verify. It's a fixed 9-byte value that is easy to identify and verify. The length was selected to pack it along with bytes1(fields)</code>, uint16(structIndex)</code> and address(application)</code> into a single 32-byte word. While 9 bytes is shorter than a full 32-byte hash, the collision probability remains negligible in practice—an attacker would need to produce a valid ECDSA or ERC-1271</a> signature that randomly begins with these exact 9 bytes, which has probability 2^-72 (approximately 1 in 4.7 × 10^21) assuming a uniform distribution.</p>
The fields</code> byte encodes which EIP-712 domain fields are present in the main domain (per ERC-5267</a>), enabling dynamic field selection. Only name</code> and version</code> are normally set in the main domain, since chainId</code> is omitted for crosschain validity since each chain-specific struct includes its own chainId</code> and optionally verifyingContract</code> (or equivalent), allowing each chain to validate its own contract address as part of the struct hash verification.</p>
The application</code> address refers to any contract that implements ERC-5267</a>'s eip712Domain()</code> function. This contract provides the domain separator information needed to reconstruct the crosschain message hash. The application contract does not need to be the contract that executes the operation: it serves solely as a source of EIP-712 domain metadata. Applications could either deploy dedicated immutable domain separator contracts to ensure consistent domain information across all chains, or use the executing contract itself if it implements ERC-5267</a>.</p>
Backwards Compatibility</h2>
This ERC uses standard EIP-712</a> without modifications. Existing wallets and applications that support EIP-712 can immediately work with crosschain signatures without any changes, though they may not recognize the crosschain semantics.</p>
Applications that verify signatures with a domain that includes a specific chainId</code> will reject crosschain signatures (where chainId</code> is omitted), providing safe failure by default. Applications that wish to support crosschain signatures must explicitly implement the verification pattern described in this ERC.</p>
Reference Implementation</h2>
To validate a crosschain signature, the application can use the following library:</p>
import</span> {</span>SignatureChecker</span>}</span> from</span> "@openzeppelin/contracts/utils/cryptography/SignatureChecker.sol"</span>;</span></span>
import</span> {</span>MessageHashUtils</span>}</span> from</span> "@openzeppelin/contracts/utils/cryptography/MessageHashUtils.sol"</span>;</span></span>
import</span> {</span>IERC5267</span>}</span> from</span> "@openzeppelin/contracts/interfaces/IERC5267.sol"</span>;</span></span>
import</span> {</span>Calldata</span>}</span> from</span> "@openzeppelin/contracts/utils/Calldata.sol"</span>;</span></span>
</span>
library</span> CrossChainSignatureChecker</span> {</span></span>
    bytes9</span> internal</span> constant</span> ERC7964_MAGIC </span>=</span> 0x796479647964796479</span>;</span></span>
</span>
    function</span> isValidCrossChainSignatureNow</span>(</span></span>
        address</span> signer</span>,</span></span>
        bytes32</span> hash</span>,</span></span>
        bytes</span> calldata</span> erc7964Signature</span>,</span></span>
        function</span>(</span>bytes32</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> structHash</span></span>
    )</span> internal</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span>
        (</span></span>
            bool</span> success</span>,</span></span>
            bytes1</span> fields</span>,</span></span>
            uint16</span> structIndex</span>,</span></span>
            address</span> application</span>,</span></span>
            bytes32</span>[</span>]</span> calldata</span> structsArray</span>,</span></span>
            bytes</span> calldata</span> crossChainSignature</span></span>
        )</span> =</span> parseCrossChainSignature</span>(</span>erc7964Signature</span>)</span>;</span></span>
        if</span> (</span>!</span>success </span>||</span> structsArray</span>[</span>structIndex</span>]</span> !=</span> hash</span>)</span> return</span> false</span>;</span></span>
</span>
        string</span> memory</span> name</span>;</span></span>
        string</span> memory</span> version</span>;</span></span>
        uint256</span> chainId</span>;</span></span>
        address</span> verifyingContract</span>;</span></span>
        bytes32</span> domainSalt</span>;</span></span>
        (</span>,</span> name</span>,</span> version</span>,</span> chainId</span>,</span> verifyingContract</span>,</span> domainSalt</span>,</span> )</span> =</span> IERC5267</span>(</span>application</span>)</span>.</span>eip712Domain</span>(</span>)</span>;</span></span>
</span>
        bytes32</span> typedHash </span>=</span> MessageHashUtils</span>.</span>toTypedDataHash</span>(</span></span>
            MessageHashUtils</span>.</span>toDomainSeparator</span>(</span>fields</span>,</span> name</span>,</span> version</span>,</span> chainId</span>,</span> verifyingContract</span>,</span> domainSalt</span>)</span>,</span></span>
            structHash</span>(</span>keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>structsArray</span>)</span>)</span>)</span></span>
        )</span>;</span></span>
        return</span> SignatureChecker</span>.</span>isValidSignatureNowCalldata</span>(</span>signer</span>,</span> typedHash</span>,</span> crossChainSignature</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> parseCrossChainSignature</span>(</span></span>
        bytes</span> calldata</span> erc7964Signature</span></span>
    )</span></span>
        internal</span></span>
        pure</span></span>
        returns</span> (</span></span>
            bool</span> success</span>,</span></span>
            bytes1</span> fields</span>,</span></span>
            uint16</span> structIndex</span>,</span></span>
            address</span> application</span>,</span></span>
            bytes32</span>[</span>]</span> calldata</span> structsArray</span>,</span></span>
            bytes</span> calldata</span> crossChainSignature</span></span>
        )</span></span>
    {</span></span>
        //</span> magic (9 bytes) + fields (1 byte) + structIndex (2 bytes) + application (20 bytes) + structsArrayOffset (32 bytes) +</span></span>
        //</span> structsArrayLength (32 bytes) + crossChainSignatureOffset (32 bytes) + crossChainSignatureLength (32 bytes)</span></span>
        if</span> (</span>erc7964Signature</span>.</span>length </span><</span> 0x9f</span> ||</span> bytes9</span>(</span>erc7964Signature</span>[</span>0</span>:</span>9</span>]</span>)</span> !=</span> ERC7964_MAGIC</span>)</span> {</span></span>
            return</span> (</span>false</span>,</span> 0</span>,</span> 0</span>,</span> address</span>(</span>0</span>)</span>,</span> _empty32BytesArrayCalldata</span>(</span>)</span>,</span> Calldata</span>.</span>emptyBytes</span>(</span>)</span>)</span>;</span></span>
        }</span></span>
        fields </span>=</span> erc7964Signature</span>[</span>9</span>]</span>;</span></span>
        structIndex </span>=</span> uint16</span>(</span>bytes2</span>(</span>erc7964Signature</span>[</span>10</span>:</span>]</span>)</span>)</span>;</span></span>
        application </span>=</span> address</span>(</span>bytes20</span>(</span>erc7964Signature</span>[</span>12</span>:</span>]</span>)</span>)</span>;</span></span>
</span>
        uint256</span> structsArrayOffset </span>=</span> uint256</span>(</span>bytes32</span>(</span>erc7964Signature</span>[</span>0x20</span>:</span>]</span>)</span>)</span>;</span></span>
        uint256</span> structsArrayDataOffset </span>=</span> structsArrayOffset </span>+</span> 32</span>;</span></span>
        if</span> (</span>structsArrayOffset </span><</span> 0x60</span> ||</span> structsArrayDataOffset </span>></span> erc7964Signature</span>.</span>length</span>)</span> {</span></span>
            return</span> (</span>false</span>,</span> 0</span>,</span> 0</span>,</span> address</span>(</span>0</span>)</span>,</span> _empty32BytesArrayCalldata</span>(</span>)</span>,</span> Calldata</span>.</span>emptyBytes</span>(</span>)</span>)</span>;</span></span>
        }</span></span>
        uint256</span> structsArrayLength </span>=</span> uint256</span>(</span>bytes32</span>(</span>erc7964Signature</span>[</span>structsArrayOffset</span>:</span>]</span>)</span>)</span>;</span></span>
        if</span> (</span>structsArrayDataOffset </span>+</span> structsArrayLength </span>*</span> 32</span> ></span> erc7964Signature</span>.</span>length</span>)</span> {</span></span>
            return</span> (</span>false</span>,</span> 0</span>,</span> 0</span>,</span> address</span>(</span>0</span>)</span>,</span> _empty32BytesArrayCalldata</span>(</span>)</span>,</span> Calldata</span>.</span>emptyBytes</span>(</span>)</span>)</span>;</span></span>
        }</span></span>
</span>
        uint256</span> crossChainSignatureOffset </span>=</span> structsArrayDataOffset </span>+</span> structsArrayLength </span>*</span> 32</span>;</span></span>
        uint256</span> crossChainSignatureDataOffset </span>=</span> crossChainSignatureOffset </span>+</span> 32</span>;</span></span>
        if</span> (</span>crossChainSignatureOffset </span><</span> 0x60</span> ||</span> crossChainSignatureDataOffset </span>></span> erc7964Signature</span>.</span>length</span>)</span> {</span></span>
            return</span> (</span>false</span>,</span> 0</span>,</span> 0</span>,</span> address</span>(</span>0</span>)</span>,</span> _empty32BytesArrayCalldata</span>(</span>)</span>,</span> Calldata</span>.</span>emptyBytes</span>(</span>)</span>)</span>;</span></span>
        }</span></span>
        uint256</span> crossChainSignatureLength </span>=</span> uint256</span>(</span>bytes32</span>(</span>erc7964Signature</span>[</span>crossChainSignatureOffset</span>:</span>]</span>)</span>)</span>;</span></span>
        if</span> (</span>crossChainSignatureDataOffset </span>+</span> crossChainSignatureLength </span>></span> erc7964Signature</span>.</span>length</span>)</span> {</span></span>
            return</span> (</span>false</span>,</span> 0</span>,</span> 0</span>,</span> address</span>(</span>0</span>)</span>,</span> _empty32BytesArrayCalldata</span>(</span>)</span>,</span> Calldata</span>.</span>emptyBytes</span>(</span>)</span>)</span>;</span></span>
        }</span></span>
</span>
        assembly</span> (</span>"memory-safe"</span>)</span> {</span></span>
            structsArray</span>.</span>offset </span>:=</span> add</span>(</span>erc7964Signature</span>.</span>offset</span>,</span> structsArrayDataOffset</span>)</span></span>
            structsArray</span>.</span>length </span>:=</span> structsArrayLength</span></span>
        }</span></span>
        crossChainSignature </span>=</span> erc7964Signature</span>[</span></span>
            crossChainSignatureDataOffset</span>:</span>crossChainSignatureDataOffset </span>+</span> crossChainSignatureLength</span></span>
        ]</span>;</span></span>
        return</span> (</span>true</span>,</span> fields</span>,</span> structIndex</span>,</span> application</span>,</span> structsArray</span>,</span> crossChainSignature</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> _empty32BytesArrayCalldata</span>(</span>)</span> private</span> pure</span> returns</span> (</span>bytes32</span>[</span>]</span> calldata</span> result</span>)</span> {</span></span>
        assembly</span> (</span>"memory-safe"</span>)</span> {</span></span>
            result</span>.</span>offset </span>:=</span> 0</span></span>
            result</span>.</span>length </span>:=</span> 0</span></span>
        }</span></span>
    }</span></span>
}</span></span></code></pre>
A collection of examples of how to use this ERC to fulfill the Motivation</em> use cases.</p>
Crosschain Intent Example</h3>
A user wants to execute a crosschain trade: sell USDC on Ethereum, receive ETH on Arbitrum:</p>
{</span></span>
  types</span>:</span> {</span></span>
    EIP712Domain</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>name</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>version</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span></span>
      //</span> Note: chainId is omitted for crosschain validity</span></span>
    ]</span>,</span></span>
    CrossChainIntent</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>operations</span>"</span>,</span> type</span>:</span> "</span>ChainOperation[]</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>nonce</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>deadline</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span></span>
    ]</span>,</span></span>
    ChainOperation</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>domain</span>"</span>,</span> type</span>:</span> "</span>EIP712ChainDomain</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>target</span>"</span>,</span> type</span>:</span> "</span>address</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>value</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>data</span>"</span>,</span> type</span>:</span> "</span>bytes</span>"</span> }</span></span>
    ]</span>,</span></span>
    EIP712ChainDomain</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>chainId</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>verifyingContract</span>"</span>,</span> type</span>:</span> "</span>address</span>"</span> }</span></span>
    ]</span></span>
  }</span>,</span></span>
  primaryType</span>:</span> "</span>CrossChainIntent</span>"</span>,</span></span>
  domain</span>:</span> {</span></span>
    name</span>:</span> "</span>CrossChainDEX</span>"</span>,</span></span>
    version</span>:</span> "</span>1</span>"</span></span>
  }</span>,</span></span>
  message</span>:</span> {</span></span>
    operations</span>:</span> [</span></span>
      {</span></span>
        domain</span>:</span> {</span></span>
          chainId</span>:</span> 1</span>,</span></span>
          verifyingContract</span>:</span> "</span>0x123321...</span>"</span> //</span> User's account on Ethereum</span></span>
        }</span>,</span></span>
        target</span>:</span> "</span>0xA0b86a33E6776885F5Db...</span>"</span>,</span> //</span> USDC contract</span></span>
        value</span>:</span> 0</span>,</span></span>
        data</span>:</span> "</span>0xa9059cbb...</span>"</span> //</span> transfer(settler, 1000 USDC)</span></span>
      }</span>,</span></span>
      {</span></span>
        domain</span>:</span> {</span></span>
          chainId</span>:</span> 42161</span>,</span></span>
          verifyingContract</span>:</span> "</span>0x123321...</span>"</span> //</span> User's account on Arbitrum</span></span>
        }</span>,</span></span>
        target</span>:</span> "</span>0xArbitrumSettler...</span>"</span>,</span></span>
        value</span>:</span> 0</span>,</span></span>
        data</span>:</span> "</span>0x3ccfd60b...</span>"</span> //</span> claim(0.5 ETH min)</span></span>
      }</span></span>
    ]</span>,</span></span>
    nonce</span>:</span> 42</span>,</span></span>
    deadline</span>:</span> 1704067200</span></span>
  }</span></span>
}</span></span></code></pre>
On-chain verification on Ethereum:</strong></p>
Applications can verify crosschain signatures using the encoded format. The signature contains all necessary metadata to reconstruct and verify the crosschain message:</p>
import</span> {</span>EIP712</span>}</span> from</span> "@openzeppelin/contracts/utils/cryptography/EIP712.sol"</span>;</span></span>
import</span> {</span>Nonces</span>}</span> from</span> "@openzeppelin/contracts/utils/Nonces.sol"</span>;</span></span>
import</span> {</span>CrossChainSignatureChecker</span>}</span> from</span> "./CrossChainSignatureChecker.sol"</span>;</span></span>
</span>
contract</span> CrossChainDEX</span> is</span> EIP712</span>, </span>Nonces</span> {</span></span>
    using</span> CrossChainSignatureChecker</span> for</span> address</span>;</span></span>
</span>
    bytes32</span> public</span> constant</span> EIP712_CHAIN_DOMAIN_TYPEHASH </span>=</span></span>
        keccak256</span>(</span>"EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span>
    bytes32</span> public</span> constant</span> CHAIN_OPERATION_TYPEHASH </span>=</span></span>
        keccak256</span>(</span>"ChainOperation(EIP712ChainDomain domain,address target,uint256 value,bytes data)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span>
    bytes32</span> public</span> constant</span> CROSSCHAIN_INTENT_TYPEHASH </span>=</span></span>
        keccak256</span>(</span>"CrossChainIntent(ChainOperation[] operations,uint256 nonce,uint256 deadline)ChainOperation(EIP712ChainDomain domain,address target,uint256 value,bytes data)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span>
</span>
    mapping</span>(</span>bytes32</span> operationHash </span>=></span> uint256</span>)</span> private</span> _deadlines</span>;</span></span>
</span>
    constructor</span>(</span>)</span> EIP712</span>(</span>"CrossChainDEX", "1") </span>{</span>}</span></span>
</span>
    function</span> executeIntent</span>(</span></span>
        address</span> account</span>,</span></span>
        ChainOperation</span> calldata</span> currentOp</span>,</span></span>
        uint256</span> nonce</span>,</span></span>
        uint256</span> deadline</span>,</span></span>
        bytes</span> calldata</span> signature</span></span>
    )</span> external</span> {</span></span>
        bytes32</span> currentOpHash </span>=</span> _structHash</span>(</span>currentOp</span>)</span>;</span></span>
</span>
        _useCheckedNonce</span>(</span>account</span>,</span> nonce</span>)</span>;</span></span>
        _deadlines</span>[</span>currentOpHash</span>]</span> =</span> deadline</span>;</span></span>
</span>
        require</span>(</span></span>
            account</span>.</span>isValidCrossChainSignatureNowCalldata</span>(</span></span>
                currentOpHash</span>,</span></span>
                signature</span>,</span></span>
                _crossChainStructHash</span></span>
            )</span>,</span></span>
            "Invalid signature"</span></span>
        )</span>;</span></span>
</span>
        (</span>bool</span> success</span>,</span> )</span> =</span> currentOp</span>.</span>target</span>.</span>call</span>{</span>value</span>:</span> currentOp</span>.</span>value</span>}</span>(</span>currentOp</span>.</span>data</span>)</span>;</span></span>
        require</span>(</span>success</span>,</span> "Execution failed"</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> _crossChainStructHash</span>(</span>bytes32</span> operationsHash</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
        return</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>CROSSCHAIN_INTENT_TYPEHASH</span>,</span> operationsHash</span>,</span> nonces</span>(</span>account</span>)</span>,</span> _deadlines</span>[</span>operationsHash</span>]</span>)</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> _structHash</span>(</span>ChainOperation</span> calldata</span> op</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
        return</span> keccak256</span>(</span></span>
            abi</span>.</span>encode</span>(</span></span>
                CHAIN_OPERATION_TYPEHASH</span>,</span></span>
                keccak256</span>(</span>abi</span>.</span>encode</span>(</span>EIP712_CHAIN_DOMAIN_TYPEHASH</span>,</span> block</span>.</span>chainid</span>,</span> address</span>(</span>this</span>)</span>)</span>)</span>,</span></span>
                op</span>.</span>target</span>,</span></span>
                op</span>.</span>value</span>,</span></span>
                keccak256</span>(</span>op</span>.</span>data</span>)</span></span>
            )</span></span>
        )</span>;</span></span>
    }</span></span>
}</span></span></code></pre>
The Arbitrum settler would use the same signature with currentIndex: 1</code> and the full data for op[1]</code>. Each chain only receives the full calldata for its own operation, while other operations are represented as 32-byte hashes.</p>
Multi-Chain Governance Example</h3>
A DAO member votes on a proposal affecting all chain deployments:</p>
{</span></span>
  types</span>:</span> {</span></span>
    EIP712Domain</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>name</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>version</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span></span>
    ]</span>,</span></span>
    MultiChainVote</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>votes</span>"</span>,</span> type</span>:</span> "</span>ChainVote[]</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>nonce</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span></span>
    ]</span>,</span></span>
    ChainVote</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>domain</span>"</span>,</span> type</span>:</span> "</span>EIP712ChainDomain</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>proposalId</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>support</span>"</span>,</span> type</span>:</span> "</span>uint8</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>reason</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span></span>
    ]</span>,</span></span>
    EIP712ChainDomain</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>chainId</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>verifyingContract</span>"</span>,</span> type</span>:</span> "</span>address</span>"</span> }</span></span>
    ]</span></span>
  }</span>,</span></span>
  primaryType</span>:</span> "</span>MultiChainVote</span>"</span>,</span></span>
  domain</span>:</span> {</span></span>
    name</span>:</span> "</span>MultiChainDAO</span>"</span>,</span></span>
    version</span>:</span> "</span>1</span>"</span></span>
  }</span>,</span></span>
  message</span>:</span> {</span></span>
    votes</span>:</span> [</span></span>
      {</span></span>
        domain</span>:</span> {</span></span>
          chainId</span>:</span> 1</span>,</span></span>
          verifyingContract</span>:</span> "</span>0x123321...</span>"</span> //</span> DAO contract on Ethereum</span></span>
        }</span>,</span></span>
        proposalId</span>:</span> 42</span>,</span></span>
        support</span>:</span> 1</span>,</span> //</span> For</span></span>
        reason</span>:</span> "</span>This upgrade improves security</span>"</span></span>
      }</span>,</span></span>
      {</span></span>
        domain</span>:</span> {</span></span>
          chainId</span>:</span> 137</span>,</span></span>
          verifyingContract</span>:</span> "</span>0x321321...</span>"</span> //</span> DAO contract on Polygon</span></span>
        }</span>,</span></span>
        proposalId</span>:</span> 42</span>,</span></span>
        support</span>:</span> 1</span>,</span> //</span> For</span></span>
        reason</span>:</span> "</span>This upgrade improves security</span>"</span></span>
      }</span></span>
    ]</span>,</span></span>
    nonce</span>:</span> 7</span></span>
  }</span></span>
}</span></span></code></pre>
On-chain verification on each DAO:</strong></p>
import</span> {</span>EIP712</span>}</span> from</span> "@openzeppelin/contracts/utils/cryptography/EIP712.sol"</span>;</span></span>
import</span> {</span>Nonces</span>}</span> from</span> "@openzeppelin/contracts/utils/Nonces.sol"</span>;</span></span>
import</span> {</span>CrossChainSignatureChecker</span>}</span> from</span> "./CrossChainSignatureChecker.sol"</span>;</span></span>
</span>
contract</span> MultiChainDAO</span> is</span> EIP712</span>, </span>Nonces</span> {</span></span>
    using</span> CrossChainSignatureChecker</span> for</span> address</span>;</span></span>
</span>
    bytes32</span> public</span> constant</span> EIP712_CHAIN_DOMAIN_TYPEHASH </span>=</span></span>
        keccak256</span>(</span>"EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span>
    bytes32</span> public</span> constant</span> CHAIN_VOTE_TYPEHASH </span>=</span></span>
        keccak256</span>(</span>"ChainVote(EIP712ChainDomain domain,uint256 proposalId,uint8 support,string reason)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span>
    bytes32</span> public</span> constant</span> MULTICHAIN_VOTE_TYPEHASH </span>=</span></span>
        keccak256</span>(</span>"MultiChainVote(ChainVote[] votes,uint256 nonce)ChainVote(EIP712ChainDomain domain,uint256 proposalId,uint8 support,string reason)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span>
</span>
    constructor</span>(</span>)</span> EIP712</span>(</span>"MultiChainDAO", "1") </span>{</span>}</span></span>
</span>
    function</span> castVoteWithSignature</span>(</span></span>
        ChainVote</span> calldata</span> currentVote</span>,</span></span>
        uint256</span> nonce</span>,</span></span>
        address</span> voter</span>,</span></span>
        bytes</span> calldata</span> erc7964Signature</span></span>
    )</span> external</span> {</span></span>
        bytes32</span> currentVoteHash </span>=</span> _structHash</span>(</span>currentVote</span>)</span>;</span></span>
</span>
        _useCheckedNonce</span>(</span>voter</span>,</span> nonce</span>)</span>;</span></span>
</span>
        require</span>(</span></span>
            voter</span>.</span>isValidCrossChainSignatureNowCalldata</span>(</span></span>
                currentVoteHash</span>,</span></span>
                erc7964Signature</span>,</span></span>
                _crossChainStructHash</span></span>
            )</span>,</span></span>
            "Invalid signature"</span></span>
        )</span>;</span></span>
</span>
        _castVote</span>(</span>currentVote</span>.</span>proposalId</span>,</span> voter</span>,</span> currentVote</span>.</span>support</span>,</span> currentVote</span>.</span>reason</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> _crossChainStructHash</span>(</span>bytes32</span> votesHash</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
        return</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>MULTICHAIN_VOTE_TYPEHASH</span>,</span> votesHash</span>,</span> nonces</span>(</span>voter</span>)</span>)</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> _structHash</span>(</span>ChainVote</span> calldata</span> vote</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
        return</span> keccak256</span>(</span></span>
            abi</span>.</span>encode</span>(</span></span>
                CHAIN_VOTE_TYPEHASH</span>,</span></span>
                keccak256</span>(</span>abi</span>.</span>encode</span>(</span>EIP712_CHAIN_DOMAIN_TYPEHASH</span>,</span> block</span>.</span>chainid</span>,</span> address</span>(</span>this</span>)</span>)</span>)</span>,</span></span>
                vote</span>.</span>proposalId</span>,</span></span>
                vote</span>.</span>support</span>,</span></span>
                keccak256</span>(</span>bytes</span>(</span>vote</span>.</span>reason</span>)</span>)</span></span>
            )</span></span>
        )</span>;</span></span>
    }</span></span>
}</span></span></code></pre>
This vote signature can be submitted to DAO contracts on both Ethereum and Polygon, enabling coordinated multi-chain governance decisions.</p>
Unified Account Management Example</h3>
A user wants to add a new signer to their multisig account deployed across multiple chains:</p>
{</span></span>
  types</span>:</span> {</span></span>
    EIP712Domain</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>name</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>version</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span></span>
    ]</span>,</span></span>
    MultiChainAccountUpdate</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>updates</span>"</span>,</span> type</span>:</span> "</span>AccountUpdate[]</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>nonce</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span></span>
    ]</span>,</span></span>
    AccountUpdate</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>domain</span>"</span>,</span> type</span>:</span> "</span>EIP712ChainDomain</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>operation</span>"</span>,</span> type</span>:</span> "</span>uint8</span>"</span> }</span>,</span> //</span> 0=addSigner, 1=removeSigner, 2=changeThreshold</span></span>
      {</span> name</span>:</span> "</span>signerData</span>"</span>,</span> type</span>:</span> "</span>bytes</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>threshold</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span></span>
    ]</span>,</span></span>
    EIP712ChainDomain</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>chainId</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>verifyingContract</span>"</span>,</span> type</span>:</span> "</span>address</span>"</span> }</span></span>
    ]</span></span>
  }</span>,</span></span>
  primaryType</span>:</span> "</span>MultiChainAccountUpdate</span>"</span>,</span></span>
  domain</span>:</span> {</span></span>
    name</span>:</span> "</span>MultiChainMultisig</span>"</span>,</span></span>
    version</span>:</span> "</span>1</span>"</span></span>
  }</span>,</span></span>
  message</span>:</span> {</span></span>
    updates</span>:</span> [</span></span>
      {</span></span>
        domain</span>:</span> {</span></span>
          chainId</span>:</span> 1</span>,</span></span>
          verifyingContract</span>:</span> "</span>0x123321...</span>"</span> //</span> Account on Ethereum</span></span>
        }</span>,</span></span>
        operation</span>:</span> 0</span>,</span> //</span> addSigner</span></span>
        signerData</span>:</span> "</span>0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20</span>"</span>,</span></span>
        threshold</span>:</span> 3</span></span>
      }</span>,</span></span>
      {</span></span>
        domain</span>:</span> {</span></span>
          chainId</span>:</span> 137</span>,</span></span>
          verifyingContract</span>:</span> "</span>0x123321...</span>"</span> //</span> Account on Polygon</span></span>
        }</span>,</span></span>
        operation</span>:</span> 0</span>,</span> //</span> addSigner</span></span>
        signerData</span>:</span> "</span>0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20</span>"</span>,</span></span>
        threshold</span>:</span> 3</span></span>
      }</span>,</span></span>
      {</span></span>
        domain</span>:</span> {</span></span>
          chainId</span>:</span> 42161</span>,</span></span>
          verifyingContract</span>:</span> "</span>0x123321...</span>"</span> //</span> Account on Arbitrum</span></span>
        }</span>,</span></span>
        operation</span>:</span> 0</span>,</span> //</span> addSigner</span></span>
        signerData</span>:</span> "</span>0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20</span>"</span>,</span></span>
        threshold</span>:</span> 3</span></span>
      }</span></span>
    ]</span>,</span></span>
    nonce</span>:</span> 42</span></span>
  }</span></span>
}</span></span></code></pre>
On-chain execution:</strong></p>
import</span> {</span>EIP712</span>}</span> from</span> "@openzeppelin/contracts/utils/cryptography/EIP712.sol"</span>;</span></span>
import</span> {</span>Nonces</span>}</span> from</span> "@openzeppelin/contracts/utils/Nonces.sol"</span>;</span></span>
import</span> {</span>CrossChainSignatureChecker</span>}</span> from</span> "./CrossChainSignatureChecker.sol"</span>;</span></span>
</span>
contract</span> MultiChainMultisig</span> is</span> EIP712</span>, </span>Nonces</span> {</span></span>
    using</span> CrossChainSignatureChecker</span> for</span> address</span>;</span></span>
</span>
    bytes32</span> public</span> constant</span> EIP712_CHAIN_DOMAIN_TYPEHASH </span>=</span></span>
        keccak256</span>(</span>"EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span>
    bytes32</span> public</span> constant</span> ACCOUNT_UPDATE_TYPEHASH </span>=</span></span>
        keccak256</span>(</span>"AccountUpdate(EIP712ChainDomain domain,uint8 operation,bytes signerData,uint256 threshold)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span>
    bytes32</span> public</span> constant</span> MULTICHAIN_ACCOUNT_UPDATE_TYPEHASH </span>=</span></span>
        keccak256</span>(</span>"MultiChainAccountUpdate(AccountUpdate[] updates,uint256 nonce)AccountUpdate(EIP712ChainDomain domain,uint8 operation,bytes signerData,uint256 threshold)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span>)</span>;</span></span>
</span>
    constructor</span>(</span>)</span> EIP712</span>(</span>"MultiChainMultisig", "1") </span>{</span>}</span></span>
</span>
    function</span> updateAccountWithSignature</span>(</span></span>
        AccountUpdate</span> calldata</span> currentUpdate</span>,</span></span>
        uint256</span> nonce</span>,</span></span>
        bytes</span> calldata</span> erc7964Signature</span></span>
    )</span> external</span> {</span></span>
        bytes32</span> currentUpdateHash </span>=</span> _structHash</span>(</span>currentUpdate</span>)</span>;</span></span>
</span>
        _useCheckedNonce</span>(</span>address</span>(</span>this</span>)</span>,</span> nonce</span>)</span>;</span></span>
</span>
        require</span>(</span></span>
            address</span>(</span>this</span>)</span>.</span>isValidCrossChainSignatureNowCalldata</span>(</span></span>
                currentUpdateHash</span>,</span></span>
                erc7964Signature</span>,</span></span>
                _crossChainStructHash</span></span>
            )</span>,</span></span>
            "Invalid signature"</span></span>
        )</span>;</span></span>
</span>
        if</span> (</span>currentUpdate</span>.</span>operation </span>==</span> 0</span>)</span> {</span></span>
            _addSigner</span>(</span>currentUpdate</span>.</span>signerData</span>,</span> currentUpdate</span>.</span>threshold</span>)</span>;</span></span>
        }</span> //</span> ... other operations</span></span>
    }</span></span>
</span>
    function</span> _crossChainStructHash</span>(</span>bytes32</span> updatesHash</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
        return</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>MULTICHAIN_ACCOUNT_UPDATE_TYPEHASH</span>,</span> updatesHash</span>,</span> nonces</span>(</span>address</span>(</span>this</span>)</span>)</span>)</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> _structHash</span>(</span>AccountUpdate</span> calldata</span> update</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
        return</span> keccak256</span>(</span></span>
            abi</span>.</span>encode</span>(</span></span>
                ACCOUNT_UPDATE_TYPEHASH</span>,</span></span>
                keccak256</span>(</span>abi</span>.</span>encode</span>(</span>EIP712_CHAIN_DOMAIN_TYPEHASH</span>,</span> block</span>.</span>chainid</span>,</span> address</span>(</span>this</span>)</span>)</span>)</span>,</span></span>
                update</span>.</span>operation</span>,</span></span>
                keccak256</span>(</span>update</span>.</span>signerData</span>)</span>,</span></span>
                update</span>.</span>threshold</span></span>
            )</span></span>
        )</span>;</span></span>
    }</span></span>
</span>
    function</span> _addSigner</span>(</span>bytes</span> calldata</span> signerData</span>,</span> uint256</span> threshold</span>)</span> internal</span> {</span></span>
        //</span> Implementation for adding signer</span></span>
    }</span></span>
}</span></span></code></pre>
This signature enables the multisig owners to add a new signer and update the threshold across all chain deployments simultaneously. The same account address exists on Ethereum, Polygon, and Arbitrum, and this single signature authorizes the updates on all three networks.</p>
CrossChain Social Recovery Example</h3>
A user has lost access to their account and guardians need to initiate recovery across multiple networks:</p>
{</span></span>
  types</span>:</span> {</span></span>
    EIP712Domain</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>name</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>version</span>"</span>,</span> type</span>:</span> "</span>string</span>"</span> }</span></span>
      //</span> Note: verifyingContract is omitted since the recovery module is deployed on different addresses across chains for this example</span></span>
    ]</span>,</span></span>
    MultiChainRecovery</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>recoveries</span>"</span>,</span> type</span>:</span> "</span>ChainRecovery[]</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>nonce</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span></span>
    ]</span>,</span></span>
    ChainRecovery</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>domain</span>"</span>,</span> type</span>:</span> "</span>EIP712ChainDomain</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>newOwner</span>"</span>,</span> type</span>:</span> "</span>address</span>"</span> }</span></span>
    ]</span>,</span></span>
    EIP712ChainDomain</span>:</span> [</span></span>
      {</span> name</span>:</span> "</span>chainId</span>"</span>,</span> type</span>:</span> "</span>uint256</span>"</span> }</span>,</span></span>
      {</span> name</span>:</span> "</span>verifyingContract</span>"</span>,</span> type</span>:</span> "</span>address</span>"</span> }</span></span>
    ]</span></span>
  }</span>,</span></span>
  primaryType</span>:</span> "</span>MultiChainRecovery</span>"</span>,</span></span>
  domain</span>:</span> {</span></span>
    name</span>:</span> "</span>CrossChainSocialRecovery</span>"</span>,</span></span>
    version</span>:</span> "</span>1</span>"</span></span>
  }</span>,</span></span>
  message</span>:</span> {</span></span>
    recoveries</span>:</span> [</span></span>
      {</span></span>
        domain</span>:</span> {</span></span>
          chainId</span>:</span> 1</span>,</span></span>
          verifyingContract</span>:</span> "</span>0x123321...</span>"</span> //</span> Recovery module on Ethereum</span></span>
        }</span>,</span></span>
        newOwner</span>:</span> "</span>0x9999999999999999999999999999999999999999</span>"</span></span>
      }</span>,</span></span>
      {</span></span>
        domain</span>:</span> {</span></span>
          chainId</span>:</span> 137</span>,</span></span>
          verifyingContract</span>:</span> "</span>0x321321...</span>"</span> //</span> Recovery module on Polygon</span></span>
        }</span>,</span></span>
        newOwner</span>:</span> "</span>0x9999999999999999999999999999999999999999</span>"</span></span>
      }</span>,</span></span>
      {</span></span>
        domain</span>:</span> {</span></span>
          chainId</span>:</span> 42161</span>,</span></span>
          verifyingContract</span>:</span> "</span>0x432432...</span>"</span> //</span> Recovery module on Arbitrum</span></span>
        }</span>,</span></span>
        newOwner</span>:</span> "</span>0x9999999999999999999999999999999999999999</span>"</span></span>
      }</span></span>
    ]</span>,</span></span>
    nonce</span>:</span> 1</span></span>
  }</span></span>
}</span></span></code></pre>
On-chain execution with guardian multisig:</strong></p>
import</span> { </span>CrossChainSignatureChecker</span> }</span> from</span> "./CrossChainSignatureChecker.sol"</span>;</span></span>
</span>
bytes32</span> constant</span> EIP712_CHAIN_DOMAIN_TYPEHASH </span>=</span> keccak256</span>(</span></span>
    "EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span></span>
)</span>;</span></span>
bytes32</span> constant</span> CHAIN_RECOVERY_TYPEHASH </span>=</span> keccak256</span>(</span></span>
    "ChainRecovery(EIP712ChainDomain domain,address newOwner)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span></span>
)</span>;</span></span>
bytes32</span> constant</span> MULTICHAIN_RECOVERY_TYPEHASH </span>=</span> keccak256</span>(</span></span>
    "MultiChainRecovery(ChainRecovery[] recoveries,uint256 nonce)ChainRecovery(EIP712ChainDomain domain,address newOwner)EIP712ChainDomain(uint256 chainId,address verifyingContract)"</span></span>
)</span>;</span></span>
</span>
uint256</span> private</span> _tempNonce</span>;</span></span>
</span>
function</span> initiateRecoveryWithSignature</span>(</span></span>
    ChainRecovery</span> calldata</span> currentRecovery</span>,</span></span>
    uint256</span> nonce</span>,</span></span>
    address</span>[</span>]</span> calldata</span> guardians</span>,</span></span>
    bytes</span>[</span>]</span> calldata</span> guardianErc7964Signatures</span></span>
)</span> external</span> {</span></span>
    require</span>(</span>guardians</span>.</span>length </span>==</span> guardianErc7964Signatures</span>.</span>length</span>,</span> "Mismatched arrays"</span>)</span>;</span></span>
    //</span> Note</span>: chainId and verifyingContract validation is implicit in the struct hash verification</span></span>
</span>
    //</span> Verify the current recovery hash matches all guardian signatures</span></span>
    bytes32</span> currentRecoveryHash </span>=</span> _structHash</span>(</span>currentRecovery</span>)</span>;</span></span>
</span>
    _tempNonce </span>=</span> nonce</span>;</span></span>
</span>
    //</span> Verify all guardian signatures are valid and count valid guardian signatures</span></span>
    uint256</span> validSignatures </span>=</span> 0</span>;</span></span>
    for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> guardians</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span>
        if</span> (</span></span>
            CrossChainSignatureChecker</span>.</span>isValidCrossChainSignatureNow</span>(</span></span>
                guardians</span>[</span>i</span>]</span>,</span></span>
                currentRecoveryHash</span>,</span></span>
                guardianErc7964Signatures</span>[</span>i</span>]</span>,</span></span>
                _computeRecoveryStructHash</span></span>
            )</span> &&</span> isGuardian</span>(</span>guardians</span>[</span>i</span>]</span>)</span></span>
        )</span> {</span></span>
            validSignatures</span>+</span>+</span>;</span></span>
        }</span></span>
    }</span></span>
    require</span>(</span>validSignatures </span>></span>=</span> 3</span>,</span> "Insufficient guardian signatures"</span>)</span>;</span></span>
</span>
    //</span> Schedule recovery with delay</span></span>
    _scheduleRecovery</span>(</span>currentRecovery</span>.</span>newOwner</span>,</span> block</span>.</span>timestamp </span>+</span> RECOVERY_DELAY</span>)</span>;</span></span>
}</span></span>
</span>
function</span> _computeRecoveryStructHash</span>(</span></span>
    bytes32</span> recoveriesHash</span></span>
)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
    return</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span>
        MULTICHAIN_RECOVERY_TYPEHASH</span>,</span></span>
        recoveriesHash</span>,</span></span>
        _tempNonce</span></span>
    )</span>)</span>;</span></span>
}</span></span>
</span>
function</span> _structHash</span>(</span>ChainRecovery</span> calldata</span> recovery</span>)</span> internal</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
    return</span> keccak256</span>(</span></span>
        abi</span>.</span>encode</span>(</span></span>
            CHAIN_RECOVERY_TYPEHASH</span>,</span></span>
            keccak256</span>(</span>abi</span>.</span>encode</span>(</span>EIP712_CHAIN_DOMAIN_TYPEHASH</span>,</span> block</span>.</span>chainid</span>,</span> address</span>(</span>this</span>)</span>)</span>)</span>,</span></span>
            recovery</span>.</span>newOwner</span></span>
        )</span></span>
    )</span>;</span></span>
}</span></span></code></pre>
This signature enables guardians to schedule a recovery operation across all chains. The process includes:</p>

Guardian Signatures</strong>: Multiple guardians sign the same crosschain recovery message (3-of-5 threshold)</li>
Schedule Phase</strong>: Once sufficient guardians sign, the recovery is scheduled on all networks with a delay</li>
Security Window</strong>: Delay period where malicious recovery attempts can be detected and canceled</li>
Execution Phase</strong>: After the delay, the recovery replaces the account's owner</li>
CrossChain Consistency</strong>: The same recovery operation is scheduled simultaneously on Ethereum, Polygon, and Arbitrum</li>
</ol>
Security Considerations</h2>
Crosschain Replay</h3>
This ERC intentionally enables replay across chains, the same signature is designed to be used on multiple chains. The verifyingContract</code> field (set to the user's account address) binds the signature to a specific account, preventing unauthorized use. However, applications must implement their own replay protection mechanisms such as including nonces and deadlines in the message.</p>
Account Validation</h3>
Applications verifying signatures should check that the signing account exists on the current chain. An account that exists on Ethereum but not Polygon should not have signatures accepted on Polygon. For counterfactual accounts that have not been deployed yet, applications should follow ERC-6492</a> to validate signatures.</p>
Code and State Differences</h3>
Contract code and state may differ across chains at the same address. Signatures that pass isValidSignature()</code> on one chain may fail on another due to state divergence or chain-specific logic. For example, a crosschain message that has uses a nonce</code> field may find that the nonce is already used on one of the chains. Applications should handle signature validation failures gracefully and should not assume uniform behavior across chains.</p>
Partial Execution Risk</h3>
Crosschain signatures do not guarantee atomic execution. A signature may be successfully validated on some chains but not others. This can result in partial fulfillment of the intent. Applications should implement refund mechanisms to allow users to recover from failed partial executions.</p>
Additionally, operations may execute in different orders across chains due to varying network conditions, block times, and congestion levels. An operation intended to execute first may complete last on a congested chain, leading to unexpected state changes. For example, in a crosschain trade, a user might sell an asset on one chain before successfully acquiring its replacement on another chain, creating temporary exposure. Applications should design operations to be order-independent where possible, or implement coordination mechanisms to ensure proper sequencing.</p>
Signature Expiration</h3>
Signatures without explicit expiration remain valid indefinitely. If an operation is not executed on some chains, it can be executed later, potentially with unexpected consequences. Applications may include deadline</code> or validUntil</code> fields in messages to prevent stale signature execution.</p>
Wallet Display Considerations</h3>
Since this ERC relies on standard EIP-712 wallet display, users depend on their wallet to correctly show all crosschain operations. Users should:</p>

Review All Operations</strong>: Check every element in the message array</li>
Verify Chain IDs</strong>: Ensure operations target the expected chains</li>
Check Amounts</strong>: Verify asset amounts and addresses on each chain</li>
Understand Atomicity</strong>: Know that operations may execute independently</li>
</ol>
Wallet developers should enhance displays to highlight crosschain nature and show warnings about partial execution risks.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Encode chain id with transaction hash
2025-05-22T00:00:00+00:00
Abstract</h2>
This standard proposes a way to encode the combination of a chain ID and a transaction hash into one string.</p>
Motivation</h2>
Looking up a transaction by its hash always requires the context of the chain - a transaction hash alone is not enough to identify the used chain. If the chain information is included in the string itself, finding the right chain for the transaction is easy.</p>
Such strings can then be used, for example, in a forwarder service that forwards to the correct blockchain explorer.</p>
The chain id is included in some object formats, such as the transaction object inside the blockchain itself, but that object has a lot of unneeded data for our purposes.</p>
Specification</h2>
The encoded string has three components:</p>

A chain ID, denoted as chainId</code>. The used chain id MUST be based on EIP-155</a> and the chain ID repository stated in that EIP.</li>
A transaction hash, denoted as txHash</code>. The hash MUST include the 0x</code> prefix.</li>
A static string tx</code>, acting as a type identifier.</li>
</ul>
The syntax is: chainId:txHash:tx</code>.</p>
An example for a transaction with hash 0xc55e2b90168af6972193c1f86fa4d7d7b31a29c156665d15b9cd48618b5177ef</code> that was issued on chain ID 1</code> is: 1:0xc55e2b90168af6972193c1f86fa4d7d7b31a29c156665d15b9cd48618b5177ef:tx</code>.</p>
All of the characters are case-insensitive.</p>
Rationale</h2>
The chain ID is the most important detail when routing queries based on this standard and is therefore the first element in the string. The transaction hash is the second most important element.</p>
The suffix tx</code> is used to differentiate from, for example, addresses. Without the tx</code> it would remain unclear whether an encoded string refers to an address, a transaction hash or something else.</p>
Security Considerations</h2>
This EIP does not introduce direct security risks. It is up to the external service providers (such as wallet developers and blockchain explorers) to decide how and if they want to incorporate this EIP.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Key Hash Based Tokens
2025-05-16T00:00:00+00:00
Abstract</h2>
This EIP proposes two token interfaces: ERC-KeyHash721</strong> for non-fungible tokens (NFTs) and ERC-KeyHash20</strong> for fungible tokens (similar to ERC-20</a>). Both of them utilize cryptographic key hashes (“keyHash”, or keccak256(key)</code>) instead of Ethereum addresses to manage ownership. This enhances privacy by authorizing by the public key’s ECDSA signature (address derived from keccak256(key[1:])</code>) and matching keyHash = keccak256(key)</code>, without storing addresses on‑chain. Consequently, it empowers users to conduct transactions using any address they choose. By separating ownership from transaction initiation, these standards allow gas fees to be paid by third parties without relinquishing token control, making them suitable for batch transactions and gas sponsorship. Security is ensured by implementing robust ECDSA signature verification on key functions (transfer</code>) to prevent message tampering.</p>
Motivation</h2>
Traditional ERC-721</a> and ERC-20</a> tokens bind ownership to Ethereum addresses, which are publicly visible and may be linked to identities, compromising privacy. The key hash-based ownership model allows owners to prove control without exposing addresses, ideal for anonymous collectibles, private transactions, or decentralized identity use cases. Additionally, separating ownership from gas fee payment enables third-party gas sponsorship, improving user experience in high-gas or batch transaction scenarios. This proposal aligns with the privacy principles of ERC-5564</a> (Stealth Addresses) and extends them to token ownership.</p>
Specification</h2>
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.</p>
Overview</h3>
This proposal defines two token interfaces:</p>

IERCKeyHash721</code>: For non-fungible tokens (NFTs), each identified by a unique tokenId</code>, with ownership managed via keyHash</code> (keccak256(key)</code>).</li>
IERCKeyHash20</code>: For fungible tokens, with balances associated with keyHash</code>.</li>
</ul>
Token operations (transfer</code>) require the owner's key(an uncompressed secp256k1 public key) and an ECDSA signature produced by the private key corresponding to the key (i.e., the address derived from keccak256(key[1:])</code> excluding the 0x04 prefix) to prove ownership, ensuring only legitimate owners can execute actions. Signatures follow EIP-712</a> structured data hashing to prevent message tampering, with per-keyHash nonces and deadlines to prevent replay attacks.</p>
Implementers MAY optionally add administrative functions such as mint</code> (create new tokens) and destroy</code> (remove tokens) based on application requirements. These functions are not part of the core interface of this ERC; if provided, they SHOULD enforce strict access control, correct supply accounting, and preserve the key‑hash privacy model without exposing addresses.</p>
Notably, the approve function is intentionally omitted. The key is designed for one-time use and is revealed only during token transfer transactions. Once revealed, holdings are typically migrated to fresh keyHashes; implementations MAY disallow reuse of previously revealed keyHash. Since transactions can be submitted by any address, the signature must be generated by the address derived from the key. This binds authorization to the key while allowing any relayer address to submit and pay gas.</p>
ERC-KeyHash721: Non-Fungible Token Interface</h3>
Interface</h4>
interface</span> IERCKeyHash721</span> {</span></span>
    //</span> Events</span></span>
    event</span> KeyHashTransfer721</span>(</span>uint256</span> indexed</span> tokenId</span>, </span>bytes32</span> indexed</span> fromKeyHash</span>, </span>bytes32</span> indexed</span> toKeyHash</span>)</span>;</span></span>
    event</span> KeyHashBurn721</span>(</span>uint256</span> indexed</span> tokenId</span>, </span>bytes32</span> indexed</span> ownerKeyHash</span>)</span>;</span></span>
</span>
    //</span> View functions (aligned with ERC-721)</span></span>
    function</span> name</span>(</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span>;</span></span>
    function</span> symbol</span>(</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span>;</span></span>
    function</span> tokenURI</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span>;</span></span>
    function</span> totalSupply</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
    function</span> ownerOf</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span>
</span>
    //</span> State-changing functions</span></span>
    function</span> mint</span>(</span>uint256</span> tokenId</span>,</span> bytes32</span> keyHash</span>)</span> external</span>;</span></span>
    function</span> transfer</span>(</span>uint256</span> tokenId</span>,</span> bytes32</span> toKeyHash</span>,</span> bytes</span> memory</span> key</span>,</span> bytes</span> memory</span> signature</span>,</span> uint256</span> deadline</span>)</span> external</span>;</span></span>
    function</span> destroy</span>(</span>uint256</span> tokenId</span>,</span> bytes</span> memory</span> key</span>,</span> bytes</span> memory</span> signature</span>,</span> uint256</span> deadline</span>)</span> external</span>;</span></span>
}</span></span></code></pre>Function Descriptions</h4>
transfer</code></h5>
    transfer</span>(</span>uint256</span> tokenId</span>,</span> bytes32</span> toKeyHash</span>,</span> bytes</span> memory</span> key</span>,</span> bytes</span> memory</span> signature</span>,</span> uint256</span> deadline</span>)</span> external</span>;</span></span></code></pre>
Description</strong>: Transfers the specified token from the current owner's keyHash</code> to toKeyHash</code>. The caller provides the owner's key to prove ownership. The signature is verified using EIP-712</a> structured data.

Parameters</strong>:</p>

tokenId</code>: uint256</code> - The token ID to transfer.</li>
toKeyHash</code>: bytes32</code> - The new owner's key hash.</li>
key</code>: bytes</code> - MUST be a 65-byte uncompressed secp256k1 public key with prefix 0x04.</li>
signature</code>: bytes</code> -  ECDSA signature produced by the private key corresponding to the key, verifying ownership and preventing malicious relay attacks.</li>
deadline</code>: uint256</code> - Signature expiration timestamp (Unix seconds).

Signature Message</strong>: EIP-712</a> structured data:

solidity     struct Transfer {         uint256 tokenId;         bytes32 toKeyHash;         uint256 nonce;         uint256 deadline;     }     </code>

Events</strong>: Emits KeyHashTransfer721(tokenId, fromKeyHash, toKeyHash)</code>.

Requirements</strong>:</li>
Token MUST exist (non-zero fromKeyHash</code>).</li>
keccak256(key)</code> MUST equal the current fromKeyHash</code>.</li>
Signature MUST be valid.</li>
block.timestamp</code> MUST be <= deadline</code>.</li>
toKeyHash</code> MUST NOT be zero.</li>
Updates ownership to toKeyHash</code>.</li>
</ul>

Other Functions</strong>: name</code>, symbol</code>, tokenURI</code>, and totalSupply</code> align with ERC-721</a> . ownerOf</code> returns bytes32</code> (keyHash) instead of an address.tokenURI</code> is part of the core interface and MAY return an empty string if metadata is not provided.</li>
</ul>
Key Concepts</h4>

Key (key</code>)</strong>: An uncompressed secp256k1 public key (65 bytes, starting with 0x04), used to prove ownership. Implementations MUST validate the key format:</li>
</ul>
require</span>(</span>key</span>.</span>length </span>==</span> 65</span> &&</span> key</span>[</span>0</span>]</span> ==</span> 0x04</span>,</span> "BAD_KEY_FMT"</span>)</span>;</span></span></code></pre>

Key Hash (keyHash</code>)</strong>: A bytes32</code> value representing keccak256(key)</code>, identifying ownership without exposing addresses.</li>
Token Existence</strong>: A token exists if its keyHash</code> is non-zero.</li>
Nonce</strong>: Nonces are tracked per keyHash and per contract. Each ERC-KeyHash contract maintains its ownmapping(bytes32 =>uint256)keyNonces. Cross-contract replay is already prevented by the EIP-712 domain (verifyingContract, chainId). Signers MUST serialize operations for the same keyHashwithin the same contract.</li>
</ul>
ERC-KeyHash20: Fungible Token Interface</h3>
Interface</h4>
interface</span> IERCKeyHash20</span> {</span></span>
    //</span> Events</span></span>
    event</span> KeyHashTransfer20</span>(</span>bytes32</span> indexed</span> fromKeyHash</span>, </span>bytes32</span> indexed</span> toKeyHash</span>, </span>uint256</span> amount</span>)</span>;</span></span>
</span>
    //</span> View functions (aligned with ERC-20)</span></span>
    function</span> name</span>(</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span>;</span></span>
    function</span> symbol</span>(</span>)</span> external</span> view</span> returns</span> (</span>string</span> memory</span>)</span>;</span></span>
    function</span> decimals</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint8</span>)</span>;</span></span>
    function</span> totalSupply</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
    function</span> balanceOf</span>(</span>bytes32</span> keyHash</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
</span>
    //</span> State-changing functions</span></span>
    function</span> mint</span>(</span>bytes32</span> keyHash</span>,</span> uint256</span> amount</span>)</span> external</span>;</span></span>
    function</span> transfer</span>(</span>bytes32</span> fromKeyHash</span>,</span> bytes32</span> toKeyHash</span>,</span> uint256</span> amount</span>,</span> bytes</span> memory</span> key</span>,</span> bytes</span> memory</span> signature</span>,</span> uint256</span> deadline</span>,</span> bytes32</span> leftKeyHash</span>)</span> external</span>;</span></span>
}</span></span></code></pre>Function Descriptions</h4>
transfer</code></h5>
    transfer</span>(</span>bytes32</span> fromKeyHash</span>,</span> bytes32</span> toKeyHash</span>,</span> uint256</span> amount</span>,</span> bytes</span> memory</span> key</span>,</span> bytes</span> memory</span> signature</span>,</span> uint256</span> deadline</span>,</span> bytes32</span> leftKeyHash</span>)</span></span></code></pre>
Description</strong>: Transfers amount</code> tokens from fromKeyHash</code> to toKeyHash</code>, with remaining balance assigned to leftKeyHash</code> (controlled by the sender). The caller provides the owner's key to prove ownership. The signature is verified using EIP-712</a> structured data. Mimics Bitcoin's UTXO model for partial transfers.

Parameters</strong>:</p>

fromKeyHash</code>: bytes32</code> - Token owner's key hash.</li>
toKeyHash</code>: bytes32</code> - Recipient's key hash.</li>
amount</code>: uint256</code> - Amount to transfer.</li>
key</code>: bytes</code> - MUST be a 65-byte uncompressed secp256k1 public key with prefix 0x04.</li>
signature</code>: bytes</code> - ECDSA signature.</li>
deadline</code>: uint256</code> - Signature expiration timestamp.</li>
leftKeyHash</code>: bytes32</code> - Key hash for remaining balance (balance - amount</code>). MUST NOT equal toKeyHash</code> or fromKeyHash</code> (strict mode to enforce key rotation and unlinkability).

Signature Message</strong>: EIP-712</a> structured data:

solidity     struct Transfer {         bytes32 fromKeyHash;         bytes32 toKeyHash;         uint256 amount;         uint256 nonce;         uint256 deadline;         bytes32 leftKeyHash;     }     </code>

Events</strong>: Emits KeyHashTransfer20(fromKeyHash, toKeyHash, amount)</code>.

Requirements</strong>:</li>
fromKeyHash</code> MUST have sufficient balance (balanceOf[fromKeyHash] >= amount</code>).</li>
keccak256(key)</code> MUST equal fromKeyHash</code>.</li>
Signature MUST be valid.</li>
block.timestamp</code> MUST be <= deadline</code>.</li>
toKeyHash</code> and leftKeyHash</code> MUST NOT be zero.</li>
Updates balances: balanceOf[fromKeyHash] = 0</code>, balanceOf[toKeyHash] += amount</code>, balanceOf[leftKeyHash] += (original balance - amount)</code>.</li>
</ul>

Other Functions</strong>: name</code>, symbol</code>, decimals</code>, and totalSupply</code> align with ERC-20</a>. balanceOf</code> uses bytes32</code> parameter.</li>
</ul>
Signature Verification</h3>
For transfer</code>:</p>


Verify keccak256(key) == current keyHash</code>.</p>
</li>

Compute EIP-712</a> message hash:</p>
bytes32</span> digest </span>=</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span></span>
    "\x19\x01"</span>,</span></span>
    DOMAIN_SEPARATOR</span>,</span></span>
    keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span>
        TYPE_HASH</span>,</span> //</span> Struct-specific type hash</span></span>
        params </span>//</span> Struct fields (e.g., tokenId, toKeyHash, nonce, deadline)</span></span>
    )</span>)</span></span>
)</span>)</span>;</span></span></code></pre></li>

Recover signer address using ecrecover(digest, signature)</code>.</p>
</li>

REQUIRE signer == address(uint160(uint256(keccak256(key[1:])))), where key is a 65‑byte uncompressed secp256k1 public key (0x04 || X || Y) and key[1:] denotes the 64‑byte XY payload (prefix removed)</p>
</li>

On successful verification, increment _keyNonces[currentOwnerKeyHash] (i.e., _keyNonces[ownerKeyHash] for ERC‑KeyHash721 and _keyNonces[fromKeyHash] for ERC‑KeyHash20) to prevent replay.</p>
</li>

Verify block.timestamp <= deadline</code>.</p>
</li>
</ol>
Requirements</h3>

Contracts MUST maintain mappings:

ERC-KeyHash721: tokenId</code> to keyHash</code>.</li>
ERC-KeyHash20: keyHash</code> to balance.</li>
</ul>
</li>
MUST use per-keyHash nonces (mapping(bytes32 => uint256) _keyNonces</code>) for replay protection.</li>
MUST implement EIP-712</a> for signature hashing.</li>
MUST enforce deadline</code> to limit signature validity.</li>
MUST verify signatures and hash keys in transfer</code>.</li>
For ERC-KeyHash20, MUST enforce strict mode for leftKeyHash</code> by requiring it to be different from both toKeyHash</code> and fromKeyHash</code>. This prevents change consolidation with the recipient or original account, promoting key rotation and unlinkability.</li>
</ul>
Rationale</h2>
Advantages of Key Hash</h3>

Privacy</strong>: ownerOf</code> and balanceOf</code> return keyHash</code>, not addresses. Users can use unique key pairs per token or balance, reducing linkability.</li>
Gas Fee Separation</strong>: Anyone can call transfer</code> with a valid signature, paying gas fees, enabling batch transactions or gas sponsorship.</li>
Flexibility</strong>: Aligns with ERC-5564</a> stealth addresses, extending privacy to tokens.</li>
</ul>
Transfer Design</h3>

Open to any caller with valid signatures, ensuring only owners operate while allowing gas sponsorship.</li>
EIP-712</a> signatures prevent message tampering by including all critical parameters.</li>
Per-keyHash nonces and deadlines prevent replay attacks.</li>
</ul>
Backwards Compatibility</h2>
This proposal is not compatible with ERC-721</a>  or ERC-20</a> due to bytes32</code> key hashes instead of addresses. Adapters can bridge to existing systems for privacy-focused use cases.</p>
Reference Implementation</h2>
ERC-KeyHash721 Implementation</h3>
pragma</span> solidity</span> ^0.8.0</span>;</span></span>
import</span> "@openzeppelin/contracts/utils/cryptography/ECDSA.sol"</span>;</span></span>
import</span> "@openzeppelin/contracts/utils/cryptography/EIP712.sol"</span>;</span></span>
</span>
contract</span> KeyHashERC721</span> is</span> EIP712</span> {</span></span>
    using</span> ECDSA</span> for</span> bytes32</span>;</span></span>
</span>
    string</span> public</span> name</span>;</span></span>
    string</span> public</span> symbol</span>;</span></span>
    mapping</span>(</span>uint256</span> =></span> bytes32</span>)</span> private</span> _tokenKeyHashes</span>;</span></span>
    mapping</span>(</span>uint256</span> =></span> bool</span>)</span> private</span> _destroyedTokens</span>;</span></span>
    uint256</span> public</span> totalSupply</span>;</span></span>
    mapping</span>(</span>bytes32</span> =></span> uint256</span>)</span> private</span> _keyNonces</span>;</span></span>
</span>
    event</span> KeyHashTransfer721</span>(</span>uint256</span> indexed</span> tokenId</span>, </span>bytes32</span> indexed</span> fromKeyHash</span>, </span>bytes32</span> indexed</span> toKeyHash</span>)</span>;</span></span>
    event</span> KeyHashBurn721</span>(</span>uint256</span> indexed</span> tokenId</span>, </span>bytes32</span> indexed</span> ownerKeyHash</span>)</span>;</span></span>
</span>
    bytes32</span> private</span> constant</span> TRANSFER_TYPEHASH </span>=</span> keccak256</span>(</span></span>
        "Transfer(uint256 tokenId,bytes32 toKeyHash,uint256 nonce,uint256 deadline)"</span></span>
    )</span>;</span></span>
    bytes32</span> private</span> constant</span> DESTROY_TYPEHASH </span>=</span> keccak256</span>(</span></span>
        "Destroy(uint256 tokenId,uint256 nonce,uint256 deadline)"</span></span>
    )</span>;</span></span>
</span>
    constructor</span>(</span>string</span> memory</span> _name</span>,</span> string</span> memory</span> _symbol</span>)</span></span>
        EIP712</span>(</span>"KeyHashERC721", "1")</span></span>
    {</span></span>
        name </span>=</span> _name</span>;</span></span>
        symbol </span>=</span> _symbol</span>;</span></span>
    }</span></span>
</span>
    function</span> ownerOf</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span> {</span></span>
        require</span>(</span>_tokenKeyHashes</span>[</span>tokenId</span>]</span> !=</span> 0</span> &&</span> !</span>_destroyedTokens</span>[</span>tokenId</span>]</span>,</span> "Token does not exist"</span>)</span>;</span></span>
        return</span> _tokenKeyHashes</span>[</span>tokenId</span>]</span>;</span></span>
    }</span></span>
</span>
    function</span> tokenURI</span>(</span>uint256</span>)</span> external</span> pure</span> returns</span> (</span>string</span> memory</span>)</span> {</span> return</span> ""</span>;</span> }</span></span>
</span>
    function</span> transfer</span>(</span></span>
        uint256</span> tokenId</span>,</span></span>
        bytes32</span> toKeyHash</span>,</span></span>
        bytes</span> memory</span> key</span>,</span></span>
        bytes</span> memory</span> signature</span>,</span></span>
        uint256</span> deadline</span></span>
    )</span> external</span> {</span></span>
        require</span>(</span>toKeyHash </span>!=</span> bytes32</span>(</span>0</span>)</span>,</span> "Invalid recipient hash"</span>)</span>;</span></span>
        require</span>(</span>_tokenKeyHashes</span>[</span>tokenId</span>]</span> !=</span> 0</span> &&</span> !</span>_destroyedTokens</span>[</span>tokenId</span>]</span>,</span> "Token does not exist"</span>)</span>;</span></span>
        require</span>(</span>block</span>.</span>timestamp </span><</span>=</span> deadline</span>,</span> "Signature expired"</span>)</span>;</span></span>
        require</span>(</span>key</span>.</span>length </span>==</span> 65</span> &&</span> key</span>[</span>0</span>]</span> ==</span> 0x04</span>,</span> "BAD_KEY_FMT"</span>)</span>;</span></span>
        bytes32</span> currentKeyHash </span>=</span> _tokenKeyHashes</span>[</span>tokenId</span>]</span>;</span></span>
        require</span>(</span>keccak256</span>(</span>key</span>)</span> ==</span> currentKeyHash</span>,</span> "BAD_KEYHASH"</span>)</span>;</span></span>
        </span></span>
        uint256</span> nonce </span>=</span> _keyNonces</span>[</span>currentKeyHash</span>]</span>;</span></span>
        bytes32</span> structHash </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span>
            TRANSFER_TYPEHASH</span>,</span></span>
            tokenId</span>,</span></span>
            toKeyHash</span>,</span></span>
            nonce</span>,</span></span>
            deadline</span></span>
        )</span>)</span>;</span></span>
        bytes32</span> digest </span>=</span> _hashTypedDataV4</span>(</span>structHash</span>)</span>;</span></span>
        address</span> signer </span>=</span> digest</span>.</span>recover</span>(</span>signature</span>)</span>;</span></span>
        address</span> expectedAddress </span>=</span> _addressFromUncompressedKey</span>(</span>key</span>)</span>;</span></span>
        require</span>(</span>signer </span>==</span> expectedAddress</span>,</span> "Invalid signature"</span>)</span>;</span></span>
        _keyNonces</span>[</span>currentKeyHash</span>]</span> =</span> nonce </span>+</span> 1</span>;</span> //</span> 验签通过后再自增</span></span>
</span>
        _tokenKeyHashes</span>[</span>tokenId</span>]</span> =</span> toKeyHash</span>;</span></span>
        emit</span> KeyHashTransfer721</span>(</span>tokenId</span>,</span> currentKeyHash</span>,</span> toKeyHash</span>)</span>;</span></span>
    }</span></span>
</span>
</span>
    function</span> getNonce</span>(</span>bytes32</span> keyHash</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span> {</span></span>
        return</span> _keyNonces</span>[</span>keyHash</span>]</span>;</span></span>
    }</span></span>
    </span></span>
    function</span> _addressFromUncompressedKey</span>(</span>bytes</span> memory</span> key</span>)</span> internal</span> pure</span> returns</span> (</span>address</span>)</span> {</span></span>
        //</span> key: 65 bytes, [0] = 0x04, [1..32] = X, [33..64] = Y </span></span>
        require</span>(</span>key</span>.</span>length </span>==</span> 65</span> &&</span> key</span>[</span>0</span>]</span> ==</span> 0x04</span>,</span> "BAD_KEY_FMT"</span>)</span>;</span></span>
        bytes32</span> x</span>;</span></span>
        bytes32</span> y</span>;</span></span>
        assembly</span> {</span></span>
            x </span>:=</span> mload</span>(</span>add</span>(</span>key</span>,</span> 0x21</span>)</span>)</span> //</span> key[1..32] </span></span>
            y </span>:=</span> mload</span>(</span>add</span>(</span>key</span>,</span> 0x41</span>)</span>)</span> //</span> key[33..64] </span></span>
        }</span></span>
        bytes32</span> h </span>=</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>x</span>,</span> y</span>)</span>)</span>;</span> //</span> 64-byte XY </span></span>
        return</span> address</span>(</span>uint160</span>(</span>uint256</span>(</span>h</span>)</span>)</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>ERC-KeyHash20 Implementation</h3>
pragma</span> solidity</span> ^0.8.0</span>;</span></span>
import</span> "@openzeppelin/contracts/utils/cryptography/ECDSA.sol"</span>;</span></span>
import</span> "@openzeppelin/contracts/utils/cryptography/EIP712.sol"</span>;</span></span>
</span>
contract</span> KeyHashERC20</span> is</span> EIP712</span> {</span></span>
    using</span> ECDSA</span> for</span> bytes32</span>;</span></span>
</span>
    string</span> public</span> name</span>;</span></span>
    string</span> public</span> symbol</span>;</span></span>
    uint8</span> public</span> decimals</span>;</span></span>
    mapping</span>(</span>bytes32</span> =></span> uint256</span>)</span> public</span> balanceOf</span>;</span></span>
    uint256</span> public</span> totalSupply</span>;</span></span>
    mapping</span>(</span>bytes32</span> =></span> uint256</span>)</span> private</span> _keyNonces</span>;</span></span>
</span>
    event</span> KeyHashTransfer20</span>(</span>bytes32</span> indexed</span> fromKeyHash</span>, </span>bytes32</span> indexed</span> toKeyHash</span>, </span>uint256</span> amount</span>)</span>;</span></span>
</span>
    bytes32</span> private</span> constant</span> TRANSFER_TYPEHASH </span>=</span> keccak256</span>(</span></span>
        "Transfer(bytes32 fromKeyHash,bytes32 toKeyHash,uint256 amount,uint256 nonce,uint256 deadline,bytes32 leftKeyHash)"</span></span>
    )</span>;</span></span>
</span>
    constructor</span>(</span>string</span> memory</span> _name</span>,</span> string</span> memory</span> _symbol</span>)</span></span>
        EIP712</span>(</span>"KeyHashERC20", "1")</span></span>
    {</span></span>
        name </span>=</span> _name</span>;</span></span>
        symbol </span>=</span> _symbol</span>;</span></span>
        decimals </span>=</span> 18</span>;</span></span>
    }</span></span>
</span>
</span>
    function</span> transfer</span>(</span></span>
        bytes32</span> fromKeyHash</span>,</span></span>
        bytes32</span> toKeyHash</span>,</span></span>
        uint256</span> amount</span>,</span></span>
        bytes</span> memory</span> key</span>,</span></span>
        bytes</span> memory</span> signature</span>,</span></span>
        uint256</span> deadline</span>,</span></span>
        bytes32</span> leftKeyHash</span></span>
    )</span> external</span> {</span></span>
        require</span>(</span>balanceOf</span>[</span>fromKeyHash</span>]</span> ></span>=</span> amount</span>,</span> "Insufficient balance"</span>)</span>;</span></span>
        require</span>(</span>toKeyHash </span>!=</span> bytes32</span>(</span>0</span>)</span>,</span> "Invalid recipient hash"</span>)</span>;</span></span>
        require</span>(</span>leftKeyHash </span>!=</span> bytes32</span>(</span>0</span>)</span>,</span> "Invalid leftKeyHash"</span>)</span>;</span></span>
        require</span>(</span>leftKeyHash </span>!=</span> toKeyHash</span>,</span> "LEFT_EQ_TO"</span>)</span>;</span></span>
        require</span>(</span>leftKeyHash </span>!=</span> fromKeyHash</span>,</span> "LEFT_EQ_FROM"</span>)</span>;</span></span>
        require</span>(</span>block</span>.</span>timestamp </span><</span>=</span> deadline</span>,</span> "Signature expired"</span>)</span>;</span></span>
        require</span>(</span>key</span>.</span>length </span>==</span> 65</span> &&</span> key</span>[</span>0</span>]</span> ==</span> 0x04</span>,</span> "BAD_KEY_FMT"</span>)</span>;</span></span>
        require</span>(</span>keccak256</span>(</span>key</span>)</span> ==</span> fromKeyHash</span>,</span> "BAD_KEYHASH"</span>)</span>;</span></span>
</span>
        uint256</span> nonce </span>=</span> _keyNonces</span>[</span>fromKeyHash</span>]</span>;</span></span>
        bytes32</span> structHash </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span></span>
            TRANSFER_TYPEHASH</span>,</span></span>
            fromKeyHash</span>,</span></span>
            toKeyHash</span>,</span></span>
            amount</span>,</span></span>
            nonce</span>,</span></span>
            deadline</span>,</span></span>
            leftKeyHash</span></span>
        )</span>)</span>;</span></span>
        bytes32</span> digest </span>=</span> _hashTypedDataV4</span>(</span>structHash</span>)</span>;</span></span>
        address</span> signer </span>=</span> digest</span>.</span>recover</span>(</span>signature</span>)</span>;</span></span>
        address</span> expectedAddress </span>=</span> _addressFromUncompressedKey</span>(</span>key</span>)</span>;</span></span>
        require</span>(</span>signer </span>==</span> expectedAddress</span>,</span> "Invalid signature"</span>)</span>;</span></span>
        _keyNonces</span>[</span>fromKeyHash</span>]</span> =</span> nonce </span>+</span> 1</span>;</span> //</span> 验签通过后再自增</span></span>
</span>
        uint256</span> remaining </span>=</span> balanceOf</span>[</span>fromKeyHash</span>]</span> -</span> amount</span>;</span></span>
        balanceOf</span>[</span>fromKeyHash</span>]</span> =</span> 0</span>;</span></span>
        balanceOf</span>[</span>toKeyHash</span>]</span> +</span>=</span> amount</span>;</span></span>
        balanceOf</span>[</span>leftKeyHash</span>]</span> +</span>=</span> remaining</span>;</span></span>
        emit</span> KeyHashTransfer20</span>(</span>fromKeyHash</span>,</span> toKeyHash</span>,</span> amount</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> getNonce</span>(</span>bytes32</span> keyHash</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span> {</span></span>
        return</span> _keyNonces</span>[</span>keyHash</span>]</span>;</span></span>
    }</span></span>
</span>
    function</span> _addressFromUncompressedKey</span>(</span>bytes</span> memory</span> key</span>)</span> internal</span> pure</span> returns</span> (</span>address</span>)</span> {</span></span>
        //</span> key: 65 bytes, [0] = 0x04, [1..32] = X, [33..64] = Y </span></span>
        require</span>(</span>key</span>.</span>length </span>==</span> 65</span> &&</span> key</span>[</span>0</span>]</span> ==</span> 0x04</span>,</span> "BAD_KEY_FMT"</span>)</span>;</span></span>
        bytes32</span> x</span>;</span></span>
        bytes32</span> y</span>;</span></span>
        assembly</span> {</span></span>
            x </span>:=</span> mload</span>(</span>add</span>(</span>key</span>,</span> 0x21</span>)</span>)</span> //</span> key[1..32] </span></span>
            y </span>:=</span> mload</span>(</span>add</span>(</span>key</span>,</span> 0x41</span>)</span>)</span> //</span> key[33..64] </span></span>
        }</span></span>
        bytes32</span> h </span>=</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>x</span>,</span> y</span>)</span>)</span>;</span> //</span> 64-byte XY </span></span>
        return</span> address</span>(</span>uint160</span>(</span>uint256</span>(</span>h</span>)</span>)</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Security Considerations</h2>

Replay Attacks</strong>:

Mitigation</strong>: Per-keyHash nonces (_keyNonces[keyHash]</code>) increment after each operation, invalidating old signatures.</li>
Design</strong>: Similar to EIP-2612</a> permit mechanism, ensuring owner-controlled nonce sequences.</li>
</ul>
</li>
Message Tampering</strong>:

Mitigation</strong>: EIP-712</a> structured signatures include all critical parameters (tokenId</code>, toKeyHash</code>, amount</code>, leftKeyHash</code>, etc.), preventing relayer tampering. Signatures are function-specific (TRANSFER_TYPEHASH</code>, DESTROY_TYPEHASH</code>).</li>
Audit</strong>: Contracts MUST be audited to ensure no parameter omissions or hash collisions.</li>
</ul>
</li>
Signature Expiration</strong>:

Mitigation</strong>: deadline</code> parameter ensures signatures expire, reducing risks of leaked signatures.</li>
</ul>
</li>
Privacy Limitations</strong>:

Issue</strong>: Public keys (key) are revealed in calldata; the corresponding Ethereum addresses can be derived off‑chain from keccak256(key[1:]). Use fresh keys (toKeyHash / leftKeyHash) to reduce linkability.</li>
Recommendation</strong>: Use new key pairs per token or balance to minimize linkability. Store hashKey</code> securely, as it is sensitive.</li>
</ul>
</li>
Key Management</strong>:

Risk</strong>: Loss or compromise of the private key corresponding to key</code> results in loss of control. Store private keys securely.</li>
Recommendation</strong>: Use safe systems to save key</code>.</li>
</ul>
</li>
Gas Costs</strong>:

Issue</strong>: Signature verification and EIP-712</a> hashing increase gas costs.</li>
Recommendation</strong>: Optimize implementations and consider gas sponsorship to offset costs.</li>
</ul>
</li>
Signature Malleability</strong>: Implementations MUST reject malleable signatures (low‑S, v ∈ {27, 28}). OpenZeppelin’s ECDSA helpers enforce these checks by default.</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Permissionless CREATE2 Factory
2025-05-15T00:00:00+00:00
Abstract</h2>
This ERC defines a permissionless and deterministic deployment mechanism across all EVM-compatible chains. It uses the EIP-7702</a> Set Code for EOAs (0x4)</code> transaction type to deploy a universal CREATE2 factory contract to a fixed address (0xC0DEb853af168215879d284cc8B4d0A645fA9b0E</code>) with known bytecode. The factory can then create any new contract to a deterministic address using the EIP-1014</a> CREATE2 (0xf5)</code> opcode. It does not require preinstalls, secret keys, or chain-specific infrastructure.</p>
Motivation</h2>
Ensuring that contracts share the same address and code on multiple chains is a hard problem. It is typically done by having a known CREATE2 factory contract at a specific address that can further deterministically deploy new contracts using the CREATE2 (0xf5)</code> opcode.</p>
However, there is a bootstrapping problem: how do you get a CREATE2 factory contract with a specific address and code?</p>
Existing Solutions</h3>
There are currently three main approaches to this problem:</p>
1. Nick's Method</h4>
Use Nick's method to randomly generate a signature for a transaction without</strong> EIP-155</a> replay protection that deploys the CREATE2 factory. Nick's method ensures that there is no known private key for the account that deploys the CREATE2 factory, meaning that the resulting contract will have a deterministic address and code on all chains. This strategy is used by the Deterministic Deployment Proxy</em> (deployed to 0x4e59b44847b379578588920ca78fbf26c0b4956c</code>, including on Ethereum Mainnet), one of the most widely used CREATE2 factory contracts.</p>
Downsides</strong>:</p>

It does not work on chains that only accept EIP-155 replay-protected transactions.</li>
It is sensitive to changes in gas parameters on the target chain since the gas price and limit in the deployment transaction is sealed, and a new one cannot be signed without a private key.</li>
Reverts, such as those caused by alternative gas schedules, make the CREATE2 factory no longer deployable.</li>
</ul>
2. Secret Private Key</h4>
Keep a carefully guarded secret key and use it to sign transactions to deploy CREATE2 factory contracts. The resulting contract will have a deterministic address and code on all chains where the transaction at a given nonce of the deployer account is a CREATE2 factory deployment, which can be verified post-deployment to ensure trustlessness. Additionally, this method does not have the same gas sensitivity downsides as Nick's method, as the private key can sign a creation transaction with appropriate gas parameters at the time of execution. This is the strategy used by the Safe Singleton Factory</em> and CreateX</em> (deployed to 0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7</code> and 0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed</code> respectively, including on Ethereum Mainnet).</p>
Downsides</strong>:</p>

It is permissioned: the party that holds the secret key has the ultimate say on which chains will get the CREATE2 factory deployments.</li>
This requires carefully guarding a secret key; if it is exposed or lost, deployments are no longer guaranteed on new chains.</li>
If the transaction at the given nonce is not a successful CREATE2 factory deployment, then it is no longer possible to have a CREATE2 factory at the canonical address; this can happen by human error, for example.</li>
</ul>
3. Preinstalls</h4>
Have popular CREATE2 deployment factories deployed on new chains by default. This is, for example, what OP Stack and ZKsync do as part of their preinstalls, including the CREATE2 factory contracts mentioned above. This ensures that the CREATE2 factory contracts have known addresses and codes.</p>
Downsides</strong>:</p>

It is not standardized nor adopted by all chains.</li>
It is permissioned as a chain can choose not to include a specific CREATE2 factory contract preinstalled.</li>
Attempts to standardize this with RIP-7740 have not been successful.</li>
</ul>
Proposal: Using EIP-7702 Type 0x4</code> Transactions</h3>
This ERC proposes a permissionless alternative fourth mechanism to the existing ones described above with none of their downsides. Additionally, it standardizes a set of deployment parameters for a universal</strong> CREATE2 factory deployment. This ensures a common CREATE2 factory for the community instead of multiple competing copies with slightly different codes at different addresses. This single CREATE2 factory copy can bootstrap additional deterministic deployment infrastructure (such as the comprehensive CreateX universal contract deployer).</p>
Benefits</strong></p>

Universally applicable: It can be executed on any chain by any user and guarantees a reliable determination of smart contract deployments on any chain.</li>
Fault resistant: The method is secure against "out of gas" and other errors.</li>
Permissionless: The universal CREATE2 factory contract can be deployed by anyone.</li>
</ul>
Specification</h2>
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.</p>
Parameters</h3>
Parameter</th> Value</th></tr></thead>

DEPLOYER_PRIVATE_KEY</code></td> 0x942ba639ec667bdded6d727ad2e483648a34b584f916e6b826fdb7b512633731</code></td></tr>
CREATE2_FACTORY_INIT_CODE</code></td> 0x7c60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f33d52601d6003f3</code></td></tr>
CREATE2_FACTORY_SALT</code></td> 0x000000000000000000000000000000000000000000000000000000000001bec5</code></td></tr>
</tbody></table>
Derived Parameters</h3>
Derived Parameter</th> Value</th></tr></thead>

DEPLOYER_ADDRESS</code></td> 0x962560A0333190D57009A0aAAB7Bfa088f58461C</code></td></tr>
CREATE2_FACTORY_ADDRESS</code></td> 0xC0DEb853af168215879d284cc8B4d0A645fA9b0E</code></td></tr>
CREATE2_FACTORY_RUNTIME_CODE</code></td> 0x60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f3</code></td></tr>
CREATE2_FACTORY_CODE_HASH</code></td> 0x2ad75e1e9642e6fce7d293d52fa5a8f62a79a2079abb7402256add02d6e8bc30</code></td></tr>
</tbody></table>
Definitions</h3>

Deployer</strong>: The account corresponding to DEPLOYER_PRIVATE_KEY</code> with address DEPLOYER_ADDRESS</code>.</li>
CREATE2 factory contract</strong>: A contract that deploys other contracts with CREATE2 (0xf5)</code> opcode, allowing smart contracts to be deployed to deterministic addresses.</li>
Bootstrap contract</strong>: The contract that the deployer</em> delegates to in order to deploy the CREATE2 factory contract</em>.</li>
Bootstrapping code</strong>: The critical code in the bootstrap contract</em> that performs the CREATE2 (0xf5)</code> deployment of the CREATE2 factory contract</em>.</li>
</ul>
Bootstrap Contract</h3>
The bootstrap contract</em> MUST execute the following or equivalent bootstrapping code</em> as an EIP-7702 delegation target for the deployer</em> account:</p>
bytes</span> memory</span> initCode </span>=</span> CREATE2_FACTORY_INIT_CODE</span>;</span></span>
bytes32</span> salt </span>=</span> CREATE2_FACTORY_SALT</span>;</span></span>
assembly</span> (</span>"memory-safe"</span>)</span> {</span></span>
    create2</span>(</span>0</span>,</span> add</span>(</span>initCode</span>,</span> 32</span>)</span>,</span> mload</span>(</span>initCode</span>)</span>,</span> salt</span>)</span></span>
}</span></span></code></pre>
The bootstrap contract</em> MAY implement additional features such as:</p>

Abort early if either CREATE2 factory contract</em> is already deployed or the deployer</em> is not correctly delegated to.

This can help mitigate gas griefing from the front-running issue described below.</li>
</ul>
</li>
Additional verification that the deployment succeeded as expected.</li>
Emit events to facilitate tracking of either the bootstrap contract</em> or CREATE2 factory contract</em> deployments.</li>
</ul>
Deployment Process</h3>

Deploy a bootstrap contract</em> described in the previous section.</li>
Sign an EIP-7702 authorization using the DEPLOYER_PRIVATE_KEY</code> delegating to the bootstrap contract</em>.</li>
Execute an EIP-7702 type 0x4</code> transaction with the authorization from step 2; the transaction MUST call DEPLOYER_ADDRESS</code> (either</strong> directly or indirectly) which delegates to the bootstrap contract</em> and MUST perform the CREATE2 (0xf5)</code> of the CREATE2_FACTORY_INIT_CODE</code> with CREATE2_FACTORY_SALT</code> in the bootstrapping code</em>.</li>
</ol>
Assuming successful execution of the bootstrapping code</em> without reverting in the context of the deployer</em>, the CREATE2 factory contract</em> will be deployed to CREATE2_FACTORY_ADDRESS</code> with code CREATE2_FACTORY_RUNTIME_CODE</code> and code hash CREATE2_FACTORY_CODE_HASH</code>.</p>
Rationale</h2>
Deployment Mechanism</h3>
The deployment mechanism was chosen such that it is uniquely parameterized by the DEPLOYER_ADDRESS</code> (which itself is derived from the DEPLOYER_PRIVATE_KEY</code> and is therefore deterministic), the CREATE2_FACTORY_INIT_CODE</code> and the CREATE2_FACTORY_SALT</code> which are both fixed and deterministic. Additionally, since the DEPLOYER_ADDRESS</code> will deploy the CREATE2 factory contract with the CREATE2 (0xf5)</code> opcode, this guarantees that the address and code of the contract are deterministic.</p>
The use of a publicly known private key enables this mechanism, as anyone can permissionlessly generate a delegation signature to any</strong> bootstrap contract that would cause the DEPLOYER_ADDRESS</code> to execute the specified CREATE2 (0xf5)</code> operation and deploy the factory contract to a completely deterministic address. Because of the use of CREATE2 (0xf5)</code>, the CREATE2 factory will be deployed to CREATE2_FACTORY_ADDRESS</code> if and only if it is deployed with CREATE2_FACTORY_INIT_CODE</code>, thus guaranteeing a deployed code hash of CREATE2_FACTORY_CODE_HASH</code>. Additionally, the semantics of CREATE2 (0xf5)</code> make it so no transaction executed by DEPLOYER_ADDRESS</code> can permanently block the deployment of the CREATE2 factory contract to CREATE2_FACTORY_ADDRESS</code>.</p>
One issue with this method is that because the DEPLOYER_PRIVATE_KEY</code> is public, anyone can sign alternative delegations or transactions and front-run a legitimate CREATE2 factory deployment. The front-running would increase the nonce of the DEPLOYER_ADDRESS</code> account and render the EIP-7702 authorization in the legitimate CREATE2 factory deployment transaction invalid, causing the deployment to potentially fail. This is not considered to be a serious issue, however, as:</p>

Doing so does not prevent future deployments - meaning that an attacker can only delay the deployment of the CREATE2 factory with a sustained attack at a gas cost to the attacker, but not permanently prevent it from happening.</li>
The damage is limited to gas griefing for accounts that are legitimately trying to deploy the CREATE2 factory contract. Furthermore, the reference implementation was coded to minimize the gas griefing damage.</li>
In the case of a very persistent malicious actor, their attack can be circumvented by either making use of private transactions or working directly with block builders.</li>
</ol>
Another known issue with this method is that a future network upgrade may introduce new mechanisms (such as a new opcode or transaction type) to permanently set an account's code. If this were to happen, and since the DEPLOYER_PRIVATE_KEY</code> is publicly known, the DEPLOYER_ADDRESS</code> account's code could be mistakenly or maliciously set to something that does not execute the necessary bootstrapping code, permanently preventing any future deployment of the CREATE2 factory contract. If this ERC were to gain sufficient adoption, this is not believed to be an issue as:</p>

The deployment on Ethereum Mainnet would already exist, and the DEPLOYER_PRIVATE_KEY</code> would no longer have any value on Ethereum Mainnet.</li>
An RIP can be adopted to ensure that CREATE2_FACTORY_ADDRESS</code> has code CREATE2_FACTORY_RUNTIME_CODE</code>.</li>
</ol>
Publicly Known Private Key Instead of Nick's Method</h3>
Instead of using a publicly known DEPLOYER_PRIVATE_KEY</code>, Nick's method can be used to generate a random EIP-7702 authorization signature. This would prevent the front-running and forward compatibility issues described above.</p>
However, in order for Nick's method to work, the EIP-7702 authorization message that is signed, defined as keccak(MAGIC || rlp([chain_id, address, nonce]))</code>, must be constant. MAGIC</code> is already a constant; chain_id</code> can be trivially fixed to 0</code> to specify a chain-agnostic EIP-7702 authorization; nonce</code> can also be trivially fixed to 0</code> because Nick's method ensures the authority has no known private key, meaning it cannot sign another message that would increment the nonce. However, fixing address</code> is problematic. Doing so would require a contract with specific code to be deployed to the same address on all chains, which is the original bootstrapping problem the proposed permissionless CREATE2 factory aims to solve. Therefore, this creates a "chicken and egg problem", making it not a viable way to generate an EIP-7702 authorization signature.</p>
Use of CREATE2 Factory Contract</h3>
This mechanism allows the DEPLOYER_ADDRESS</code> to do any CREATE2 (0xf5)</code> deployment, so it would be possible to forgo the intermediary CREATE2 factory contract and use the deployer technique for all deployments. There are multiple downsides to this, however:</p>

All contract deployments are subject to the front-running issue described above, which could become an annoyance</li>
Concurrent deployments from the deployer are subject to race conditions since EIP-7702 authorizations increase the account nonce. This means that if two deployments are submitted to the mempool without knowing about each other, only the first one will actually succeed, because the EIP-7702 authorization in the second transaction is for an outdated nonce. This is not an issue when deployers are trying to deploy the same contract as proposed in this ERC since even if the second delegation and transaction fails, the contract would have been deployed as desired.</li>
</ul>
Multiple Transaction Procedure</h3>
Unfortunately, EIP-7702 type 0x4</code> transactions are restricted to to</code> values that are not null</code>, meaning that you cannot simultaneously deploy the bootstrap contract</em> and delegate to it in a single transaction.</p>
Choice of Deployer Private Key</h3>
The DEPLOYER_PRIVATE_KEY</code> was chosen as the private key at derivation path m/44'/60'/0'/0/0</code> for the mnemonic make code code code code code code code code code code coconut</code>.</p>
Choice of Salt</h3>
The CREATE2_FACTORY_SALT</code> was chosen as the first</strong> salt value starting from 0</code> such that the CREATE2 factory's ERC-55</a> checksum address starts with the case sensitive 0xC0DE...</code> prefix. A verifiable method for mining a vanity address for the CREATE2 factory contract was chosen in order to ensure that the ERC authors did not find a CREATE2 hash collision on the CREATE2_FACTORY_ADDRESS</code> that they can exploit at some point in the future.</p>
CREATE2 Factory Bytecode</h3>
The CREATE2 factory has a similar interface to existing implementations. Namely, it accepts salt || init_code</code> as input, which is a 32-byte salt</code> value concatenated with the init_code</code> of the contract to deploy. It will execute a CREATE2</code> with the specified salt</code> and init_code</code>, deploying a contract with init_code</code> to keccak256(0xff || CREATE2_FACTORY_ADDRESS || salt || keccak256(init_code))[12:]</code>. This contract returns the address of the created contract padded to 32 bytes. This differs from some existing implementations, but was done to maintain consistency with the 32-byte word size on the EVM (same encoding as ecrecover</code> precompile for example). A product of this is that the return data from CREATE2 factory is compatible with the Solidity ABI. In the case where the execution of init_code</code> were to fail, any revert data is propagated to the caller.</p>
Throughout both the CREATE2 factory contract initialization and runtime code, RETURNDATASIZE (0x3d)</code> is used to push 0</code> onto the stack instead of the dedicated PUSH0 (0x5f)</code> opcode. This is done to increase compatibility with chains that support EIP-7702 but not EIP-3855</a>, while remaining a 1-byte and 2-gas opcode.</p>
The CREATE2_FACTORY_INIT_CODE</code> corresponds to the following assembly:</p>
# SPDX-License-Identifier: CC0-1.0</span></span>
</span>
### Constructor Code ###</span></span>
</span>
0x0000: PUSH29 0x60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f3</span></span>
                        # Stack: [runcode]                      | Push the CREATE2 factory runtime code, left padded</span></span>
                                                                # with three 0 bytes</span></span>
0x001e: RETURNDATASIZE  # Stack: [0; runcode]                   | Push the offset in memory to store the code</span></span>
0x001f: MSTORE          # Stack: []                             | The runtime code is now in `memory[3:32]`, because of</span></span>
                                                                # the 3 bytes of 0-padding</span></span>
0x0020: PUSH1 29        # Stack: [29]                           | Push the code length</span></span>
0x0022: PUSH1 3         # Stack: [3; 29]                        | Push the memory offset of the start of code</span></span>
0x0024: RETURN          # Stack: []                             | Return the runtime code</span></span></code></pre>
The CREATE2_FACTORY_RUNTIME_CODE</code> corresponds to the following assembly:</p>
# SPDX-License-Identifier: CC0-1.0</span></span>
</span>
### Runtime Code ###</span></span>
</span>
# Prepare the stack, push 32, a value that will used a lot and can summon with</span></span>
# `DUP*` to save on one byte of code (over `PUSH1 32`), and a 0 which will be</span></span>
# used by either the `RETURN` or `REVERT` branches at the end.</span></span>
0x0000: PUSH1 32        # Stack: [32]</span></span>
0x0002: RETURNDATASIZE  # Stack: [0; 32]</span></span>
</span>
# First, load the salt value and compute the actual code size for the CREATE2</span></span>
# call, this is the calldata length minus 32 for the salt prefix.</span></span>
                        # Stack: [0; 32]</span></span>
0x0003: RETURNDATASIZE  # Stack: [0; 0; 32]                     | Push the calldata offset 0 of the `salt` parameter</span></span>
0x0004: CALLDATALOAD    # Stack: [salt; 0; 32]                  | Load the `salt` from calldata</span></span>
0x0005: DUP3            # Stack: [32; salt; 0; 32]              | Push 32 to the stack</span></span>
0x0006: CALLDATASIZE    # Stack: [msg.data.len; 32; salt; ...]  | Followed by the calldata length</span></span>
0x0007: SUB             # Stack: [code.len; salt; 0; 32]        | Compute `msg.data.length - 32`, which is the length of</span></span>
                                                                # the init `code`</span></span>
</span>
# Copy the init code to memory offset 0. Note that if the call to the contract</span></span>
# incorrectly encoded, this will revert with "out of gas", as it will attempt</span></span>
# to copy ~2**256 bytes of calldata to memory.</span></span>
                        # Stack: [code.len; salt; 0; 32]</span></span>
0x0008: DUP1            # Stack: [code.len; .; salt; 0; 32]     | Duplicate the length of the init code</span></span>
0x0009: DUP5            # Stack: [32; code.len; ...]            | Push the offset in calldata of the code, which is 32</span></span>
                                                                # as it comes immediately after the 32-byte `salt`; use</span></span>
                                                                # the 32 value at the bottom of the stack</span></span>
0x000a: RETURNDATASIZE  # Stack: [0; 32; code.len; ...]         | Push the offset (0) in memory to copy the code to</span></span>
0x000b: CALLDATACOPY    # Stack: [code.len; salt; 0; 32]        | Copy the init code, `memory[0:code.len]` contains the</span></span>
                                                                # init `code`</span></span>
</span>
# Deploy the contract.</span></span>
                        # Stack: [code.len; salt; 0; 32]</span></span>
0x000c: RETURNDATASIZE  # Stack: [0; code.len; salt; 0; 32]     | Push the offset in memory starting of the start of</span></span>
                                                                # init `code`, which is 0</span></span>
0x000d: CALLVALUE       # Stack: [v; 0; code.len; salt; 0; 32]  | Forward the call value to the contract constructor</span></span>
0x000e: CREATE2         # Stack: [address; 0; 32]               | Do `create2(v, code, salt)`, which leaves the address</span></span>
                                                                # of the contract on the stack, or 0 if the contract</span></span>
                                                                # creation reverted</span></span>
</span>
# Verify the deployment was successful and return the address.</span></span>
                        # Stack: [address; 0; 32]</span></span>
0x000f: DUP1            # Stack: [address; .; 0; 32]            | Duplicate the address value</span></span>
0x0010: PUSH1 0x19      # Stack: [0x0019; address; .; 0; 32]    | Push the jump destination offset for the code which</span></span>
                                                                # handles successful deployments</span></span>
0x0012: JUMPI           # Stack: [address; 0; 32]               | Jump if `address != 0`, i.e. `CREATE2` succeeded</span></span>
</span>
# CREATE2 reverted, propagate the revert data.</span></span>
                        # Stack: [address = 0; 0; 32]</span></span>
0x0013: RETURNDATASIZE  # Stack: [r.len; 0; 0; 32]              | Push the revert data length onto the stack</span></span>
0x0014: DUP2            # Stack: [0; r.len; 0; 0; 32]           | Push 0 on to the stack by duplicating; note that</span></span>
                                                                # `PUSH0` is intentionally do not used for increased</span></span>
                                                                # compatibility with chains that do not implement that</span></span>
                                                                # specific opcode</span></span>
0x0015: RETURNDATASIZE  # Stack: [r.len; 0; r.len; 0; 0; 32]    | Push the revert data length onto the stack again</span></span>
0x0016: SWAP4           # Stack: [0; 0; r.len; 0; r.len; 32]    | Reorder the stack so that both `RETURNDATACOPY` and</span></span>
                                                                # `REVERT` can be called; this is done by swapping the</span></span>
                                                                # revert data length on the top of the stack with the</span></span>
                                                                # bottom-most 0</span></span>
0x0017: RETURNDATACOPY  # Stack: [0; r.len; 32]                 | Copy the revert data to `memory[0:r.len]`</span></span>
0x0018: REVERT          # Stack: [32]                           | Revert with `memory[0:r.len]`</span></span>
</span>
# CREATE2 succeeded.</span></span>
0x0019: JUMPDEST        # Stack: [address; 0; 32]</span></span>
0x001a: RETURNDATASIZE  # Stack: [0; address; 0; 32]            | Push the memory offset (0) to store return data at,</span></span>
                                                                # `RETURNDATASIZE` is used as contract creation was</span></span>
                                                                # successful, and therefore the return data has size 0</span></span>
0x001b: MSTORE          # Stack: [0; 32]                        | Store the address in memory, `memory[0:32]` contains</span></span>
                                                                # the `address` left padded to 32-bytes</span></span>
0x001c: RETURN          # Stack: []                             | Return `memory[0:32]`, i.e. the address</span></span></code></pre>Backwards Compatibility</h2>
There are a few backwards compatibility considerations with the new proposal:</p>

It requires an EVM chain with EIP-7702 enabled. This means not all chains can use this deployment method.</li>
It would deploy yet another CREATE2 factory contract that would need to be adopted by tooling.</li>
The proposed CREATE2 factory implementation returns the newly created contract address padded to 32 bytes. This is different to some existing contracts that return unpadded 20-byte address value.</li>
The proposed CREATE2 factory implementation propagates revert data. This is different to some existing contracts that just revert with empty data in case executing the CREATE2 initialization code fails.</li>
</ol>
Reference Implementation</h2>
This proposal includes a reference implementation of a bootstrap contract to which the deployer account can delegate. The reference implementation expects a call to Bootstrap</code> to the function deploy()</code> in an EIP-7702 type 0x4</code> transaction including the EIP-7702 authorization delegating DEPLOYER_ADDRESS</code> to Bootstrap</code> (NOTE: the Bootstrap</code> is called as an entry point, instead of calling DEPLOYER_ADDRESS</code> directly which allows the contract to do some up-front checks to minimize gas griefing risk):</p>
//</span> SPDX-License-Identifier: CC0-1.0</span></span>
pragma</span> solidity</span> ^0.8.29</span>;</span></span>
</span>
contract</span> Bootstrap</span> {</span></span>
    address</span> private</span> constant</span> _DEPLOYER_ADDRESS </span>=</span> 0x962560A0333190D57009A0aAAB7Bfa088f58461C</span>;</span></span>
    address</span> private</span> constant</span> _CREATE2_FACTORY_ADDRESS </span>=</span> 0xC0DEb853af168215879d284cc8B4d0A645fA9b0E</span>;</span></span>
    bytes32</span> private</span> constant</span> _CREATE2_FACTORY_CODE_HASH </span>=</span> hex</span>"2ad75e1e9642e6fce7d293d52fa5a8f62a79a2079abb7402256add02d6e8bc30"</span>;</span></span>
    bytes</span> private</span> constant</span> _CREATE2_FACTORY_INIT_CODE </span>=</span> hex</span>"7c60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f33d52601d6003f3"</span>;</span></span>
    bytes32</span> private</span> constant</span> _CREATE2_FACTORY_SALT </span>=</span> hex</span>"000000000000000000000000000000000000000000000000000000000001bec5"</span>;</span></span>
</span>
    error</span> InvalidDelegation</span>(</span>)</span>;</span></span>
    error</span> CreationFailed</span>(</span>)</span>;</span></span>
</span>
    function</span> deploy</span>(</span>)</span> external</span> {</span></span>
        if</span> (</span>_CREATE2_FACTORY_ADDRESS</span>.</span>codehash </span>==</span> _CREATE2_FACTORY_CODE_HASH</span>)</span> {</span></span>
            return</span>;</span></span>
        }</span></span>
</span>
        bytes32</span> delegation </span>=</span> keccak256</span>(</span>abi</span>.</span>encodePacked</span>(</span>hex</span>"ef0100"</span>,</span> this</span>)</span>)</span>;</span></span>
        require</span>(</span>_DEPLOYER_ADDRESS</span>.</span>codehash </span>==</span> delegation</span>,</span> InvalidDelegation</span>(</span>)</span>)</span>;</span></span>
</span>
        Bootstrap</span>(</span>_DEPLOYER_ADDRESS</span>)</span>.</span>bootstrap</span>(</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> bootstrap</span>(</span>)</span> external</span> {</span></span>
        bytes</span> memory</span> initCode </span>=</span> _CREATE2_FACTORY_INIT_CODE</span>;</span></span>
        bytes32</span> salt </span>=</span> _CREATE2_FACTORY_SALT</span>;</span></span>
</span>
        address</span> factory</span>;</span></span>
        assembly</span> (</span>"memory-safe"</span>)</span> {</span></span>
            factory </span>:=</span> create2</span>(</span>0</span>,</span> add</span>(</span>initCode</span>,</span> 32</span>)</span>,</span> mload</span>(</span>initCode</span>)</span>,</span> salt</span>)</span></span>
        }</span></span>
</span>
        require</span>(</span>factory </span>==</span> _CREATE2_FACTORY_ADDRESS</span>,</span> CreationFailed</span>(</span>)</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>
A minimal bootstrap contract implementation is also possible (although this has a higher potential for gas griefing). The minimal bootstrap contract expects a call directly to the DEPLOYER_ADDRESS</code> in an EIP-7702 type 0x4</code> transaction including the EIP-7702 authorization delegating DEPLOYER_ADDRESS</code> to MiniBootstrap</code>:</p>
//</span> SPDX-License-Identifier: CC0-1.0</span></span>
pragma</span> solidity</span> ^0.8.29</span>;</span></span>
</span>
contract</span> MiniBootstrap</span> {</span></span>
    bytes</span> private</span> constant</span> _CREATE2_FACTORY_INIT_CODE </span>=</span> hex</span>"7c60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f33d52601d6003f3"</span>;</span></span>
    bytes32</span> private</span> constant</span> _CREATE2_FACTORY_SALT </span>=</span> hex</span>"000000000000000000000000000000000000000000000000000000000001bec5"</span>;</span></span>
</span>
    fallback</span>(</span>)</span> external</span> {</span></span>
        bytes</span> memory</span> initCode </span>=</span> _CREATE2_FACTORY_INIT_CODE</span>;</span></span>
        assembly</span> (</span>"memory-safe"</span>)</span> {</span></span>
            pop</span>(</span>create2</span>(</span>0</span>,</span> add</span>(</span>initCode</span>,</span> 32</span>)</span>,</span> mload</span>(</span>initCode</span>)</span>,</span> _CREATE2_FACTORY_SALT</span>)</span>)</span></span>
        }</span></span>
    }</span></span>
}</span></span></code></pre>Security Considerations</h2>
It is possible to front-run transactions that invalidate the deployer's EIP-7702 delegation and cause the deployment to fail. This, however, comes at a gas cost to the attacker, with limited benefit beyond delaying the deployment of the CREATE2 factory. Additionally, persistent attackers can be circumvented by either using private transaction queues or working with block builders directly to ensure that the EIP-7702 bootstrapping transaction is not front-run.</p>
Future Network Upgrades</h3>
If new EVM opcodes or transaction types are introduced in future network upgrades that allow an account to permanently set its code, then this method is no longer guaranteed to work. The deployer account can permanently change its code to a contract that does not have the required bootstrapping code. This can trivially be done by a malicious actor using the publicly known DEPLOYER_PRIVATE_KEY</code> and would prevent any future deployments of CREATE2 factory.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Unidirectional Wallet Uplink aka UWULink
2025-05-10T00:00:00+00:00
Abstract</h2>
Universal Wallet Uplink (UWULink) is a protocol that allows applications (dApps) to request a wallet to
make a batch of contract calls in a single atomic transaction without establishing a two-way
connection or revealing the user's address to the requester. The protocol defines a compact binary message format using
Protocol Buffers suitable for low-bandwidth channels such as QR codes or NFC tags. Two modes of operation are
supported: Static Mode</strong>, where the request payload directly contains the list of calls, and Programmable Mode</strong>,
where the payload references a contract that generates the list of calls.</p>
Motivation</h2>
dApps often require users to perform multistep interactions, such as approving a token and then executing a
swap. Traditionally, accomplishing this has required multiple user confirmations or complex wallet connectivity.
Recent standards like EIP-5792</a> and EIP-7702</a> introduced ways to batch multiple calls into one atomic operation
via JSON-RPC (e.g. wallet_sendCalls</code>). However, current implementations of those solutions assume an active connection
between dApp and wallet (e.g. injected provider or WalletConnect session), which creates an additional layer of UX friction.
There is a growing need for a privacy-preserving, frictionless workflow</strong> where a dApp or product can trigger complex
transactions without “connecting” their wallet or needing to disclosing their address to the application.</p>
Several trends highlight this need:</p>


Atomic Multi-Call Transactions:</strong> With the advent of account abstraction features like EIP-7702</a>, externally
owned accounts (EOAs) can execute batch transactions</strong> a la smart contract wallets. Users expect to
combine multiple actions (e.g. token approvals, swaps, transfers) into one confirmed transaction for better UX and
guaranteed all-or-nothing execution. Developers likewise want to avoid partial failures or multiple prompts.</p>
</li>

Privacy Concerns:</strong> Current wallet connection flows (EIP-1193</a> / EIP-1102</a>) require dApps to request access to
user accounts, linking the user's address with the dApp even before a transaction is made. By decoupling transaction
construction from user identification, we improve privacy. The wallet should not need to announce “who” it is to the
dApp just to receive a transaction request. A one-way communication means the dApp never learns the user's address or
other account info, mitigating tracking and profiling risks.</p>
</li>

One-Way Offline Interaction:</strong> In many use cases (desktop-to-mobile workflows, point-of-sale terminals, printed
media), it’s desirable to communicate a transaction request via a QR code, NFC tag, or URL without establishing a
session. Protocols like WalletConnect provide a session-based two-way link, but are heavyweight when a simple
one-off action is needed, and they reveal the user's account to the dApp. A unidirectional link allows, for
example, a user to scan a QR code on a webpage or poster and complete an on-chain action entirely within their
wallet app. This also enables fully offline dApps to hand off transactions securely to user devices.</p>
</li>

Compactness for QR/NFC:</strong> Encoding transaction data for use in QR codes or NFC imposes strict size limits. Prior
standards (e.g. EIP-681</a> Ethereum URIs) used human-readable formats that become lengthy when including contract
data (hex-encoded addresses and calldata inflate the size). WalletConnect addressed some issues by introducing a
more efficient URI scheme (ERC-1328</a>) instead of embedding JSON in QR codes. UWULink builds on this principle by
using a concise binary serialization (Protocol Buffers), allowing more data to be communicated in a QR code or NFC
tap.</p>
</li>

Programmability and Offloading Logic:</strong> There are scenarios where the exact list of calls depends on on-chain state
or user-specific data (for example, an airdrop claim that needs to gather all tokens claimable by that user, or a
DeFi interaction where allowances may already exist). In such cases, encoding all call data statically could be
unwieldy or inefficient if the dApp lacks knowledge of the user's address. UWULink’s Programmable Mode</strong> allows a
dApp to redirect to a deterministic on-chain generator (a smart contract with a standard interface) that can produce
the list of calls that the wallet should invoke. This allows the app to invoke arbitrary logic in generating the
list of calls based on the state of the blockchain, still without exposing the user's address.</p>
</li>
</ul>
By addressing these points, UWULink aims to enhance user experience with one-shot multi-call transactions and improve
security and privacy by eliminating unnecessary data sharing.</p>
Specification</h2>
Overview</h3>
UWULink</strong> defines a protobuf message format and interpretation for transaction requests sent from a dApp to a wallet.
The only operation in scope is a request for the wallet to execute an atomic batch of contract calls</strong> on an
EVM-compatible blockchain. The wallet, upon receiving a UWULink request (for example, via a QR code scan, deep link, or
NFC), will decode it, present the details to the user for confirmation, and if approved, execute the calls as a single
transaction on the specified chain.</p>
Key characteristics of the protocol:</p>


Unidirectional Communication:</strong> Communication is only dApp → wallet</strong>. The dApp encodes a request and the wallet
handles it. There is no handshake or return channel in the protocol itself. The wallet is not required (or able) to
send any data back to the dApp. This one-way design ensures the dApp does not learn any information
about the user or wallet (such as the address or which wallet app is used) at request time. It also simplifies
implementation – the dApp’s job is simply to generate a batch of calls and display it, and the wallet’s job is to
execute or reject the batch.</p>
</li>

Atomic Batch Calls:</strong> All calls listed in the request MUST</strong> be executed atomically, i.e. all succeed or all fail
together. If any specific call would revert, the wallet should revert the entire batch.</p>
</li>

No Identity / Auth Required:</strong> Because the request is self-contained, the wallet does not need to pre-authorize the
dApp or reveal the selected account. In traditional injected scenarios, a dApp would call eth_requestAccounts</code> (as
per EIP-1102</a>) to get the user's address. With UWULink, the first and only interaction is the user willingly
importing the transaction request (e.g. scanning the QR). The wallet should treat it similarly to how it would treat
a transaction payload from a connected dApp, except no connection context exists. If the request is malformed
or not supported, the wallet can simply alert the user and refuse.</p>
</li>

Binary Encoding:</strong> UWULink messages are encoded as a binary blob based on a Protocol Buffers schema. This blob is
then further encoded into a URI for transport via QR code or NFC tag. The string encoding of a request is the
uwulink:</code>
scheme followed by the base 64 encoded message:</p>
uwulink:<base64_of_UWULink_message></span></span></code></pre></li>

Chain Identification:</strong> The message includes a chain ID to indicate which chain the calls are intended for. The
wallet must verify or use this chain ID when executing the transaction.
If the wallet is not currently on the target chain, it SHOULD prompt the user to switch to that chain or automatically
switch if permissible (similar to handling of chainId</code> in EIP-681</a> URIs). If the wallet cannot operate on the
requested chain, it must reject the request. This ensures that the dApp’s intent (which chain’s contracts to interact
with) is preserved and avoids confusion if the user is on a different network.</p>
</li>

Static vs Programmable Mode:</strong> There are two mutually exclusive ways to specify the batch of calls:</p>

Static Mode:</strong> The request directly contains the list of calls (each with target address, calldata, and
optionally ETH value) that the wallet should execute in order. This mode is straightforward and similar to
existing multi-call APIs (e.g. the JSON-RPC wallet_sendCalls</code> payload from EIP-5792</a>), but encoded in a
compact binary form. This is ideal when the dApp knows exactly what actions need to be performed.</li>
Programmable Mode:</strong> The request contains a reference to an on-chain “resolver” contract</strong> and an input data
blob. The wallet will call a predefined view function on that contract (off-chain, via eth_call</code>) to retrieve
the actual list of calls</strong> to execute. The resolver contract must implement a standardized interface (detailed
below) that takes the provided input (and possibly the caller’s address or other context) and returns a set of
calls. This mode allows dynamic computation of call lists at execution time. It improves flexibility (the dApp
can offload complex logic or personalization to the blockchain) and keeps the QR/NFC payload small since it only
carries a contract address and input, rather than every call’s details. For example, a dApp could include just a
reference like “resolver contract X with input Y” and that contract’s resolver function will output perhaps
dozens of calls based on the latest on-chain state, the user's address, etc.</li>
</ol>
</li>
</ul>
The UWULink message includes a oneof/union to indicate which mode is used. Wallets SHOULD</strong> support both modes.</p>
Protobuf Schema</h3>
Below is the proposed Protocol Buffers v3 schema defining the UWULink message format:</p>
syntax = "proto3";</span></span>
</span>
package org.ethereum.uwulink;</span></span>
</span>
// The top-level UWULink transaction request message.</span></span>
message UWULinkRequest {</span></span>
  uint64 chain_id = 1;  // EIP-155 chain ID for the target chain</span></span>
</span>
  oneof request_type {</span></span>
    Batch batch = 2;</span></span>
    ResolverReference resolver = 3;</span></span>
  }</span></span>
}</span></span>
</span>
// Static batch of calls</span></span>
message Batch {</span></span>
  repeated Call calls = 1;</span></span>
}</span></span>
</span>
// Single contract call</span></span>
message Call {</span></span>
  bytes to = 1;                // 20-byte address of target contract</span></span>
  optional bytes value = 2;    // (optional) up to 32-byte big-endian ETH value</span></span>
  optional bytes data = 3;     // (optional) calldata for the call</span></span>
}</span></span>
</span>
// Reference to a resolver contract for dynamic call generation</span></span>
message ResolverReference {</span></span>
  bytes resolver_address = 1;  // 20-byte address of resolver contract</span></span>
  bytes resolver_data = 2;     // opaque data to pass to resolver</span></span>
}</span></span></code></pre>
Notes on the schema:</strong></p>


We use bytes</code> for addresses and other binary data. A conforming wallet implementation MUST enforce that Call.to</code> and
ResolverReference.resolver_address</code> are exactly 20 bytes. The protobuf itself won't enforce length, but using a
different length should cause the wallet to reject the message (to avoid ambiguity or mis-interpretation). The value</code>
field in Call</code> can be 0 bytes (interpreted as 0 ETH) up to 32 bytes. Leading zeros in value</code> SHOULD be stripped in
the encoding for consistency (e.g., 1 wei would be encoded as 0x01</code> not 32 bytes padded; conversely the decoder
should treat a missing value</code> or empty value</code> as 0).</p>
</li>

All fields are numbered for efficient encoding. The oneof request_type</code> ensures only one of Batch or
ResolverReference is in use. If an unknown field is present (e.g., a future extension), the wallet should ignore those
unknown fields per protobuf default behavior, but core fields must be present for validity (chain_id and one of
batch/resolver).</p>
</li>

If using a text encoding (like Base64) to embed in a URI, the entire UWULinkRequest</code> message is serialized to a
binary string, then that binary is base64-encoded. For URI safety, base64 output may need to be URL-encoded (i.e.,
+</code>, /</code> characters percent-encoded or using the URL-safe base64 variant). This is an implementation detail, but
wallet developers should be aware when parsing input. In all cases, the underlying data after decoding is expected to
match the protobuf schema above.</p>
</li>

The schema is chosen for broad compatibility. Proto3's varint encoding will handle the chain_id</code> (which is usually
small like 1, 137, etc.) in 1-2 bytes. The calls</code> repeated field will simply concatenate call entries. Each call
entry will have a 1-byte field tag for to</code> followed by 20 bytes address, etc. This results in a very compact
representation.</p>
</li>

Example of an encoded message (for illustration): A static request for chain 1 with two calls might look like:</p>

Call 1: to = 0x111111...1111</code>, value = none (0), data = 0xabcdef</code></li>
Call 2: to = 0x222222...2222</code>, value = 100 wei, data = (empty)</li>
After encoding in protobuf and base64, the URI could be:
ethereum:uwulink?request=EiABAggDEhARERERERERERERERERERERERERERIAGKDCr+8=</code> (this is a fake example string for
concept; actual encoding would differ).</li>
The wallet would decode that back to the structured fields.</li>
</ul>
</li>
</ul>
Wallet and dApp developers can import this .proto</code> to ensure they are constructing and parsing UWULink messages
consistently.</p>
Resolver Contract Interface (Programmable Mode)</h3>
This standard introduces an interface that resolver contracts must implement so that wallets can query them for call
batches. All resolver contracts MUST</strong> implement the following ABI (interface identifier UWUResolver</code>):</p>
///</span> @title</span> UWULink Resolver Interface</span></span>
interface</span> UWUResolver</span> {</span></span>
    struct</span> Call</span> {</span></span>
        address</span> target</span>;</span></span>
        uint256</span> value</span>;</span></span>
        bytes</span> data</span>;</span></span>
    }</span></span>
</span>
    //</span> Thrown when calls could not be generated, with an error code specific to this resolver.</span></span>
    error</span> CallGenerationFailure</span>(</span>uint256</span> errorCode</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Compute a batch of calls for a given request.</span></span>
     * </span>@param</span> requester</span> The address of the wallet (EOA or contract) that is requesting the calls.</span></span>
     * </span>@param</span> data</span> Arbitrary request data (opaque to the wallet, provided by dApp via UWULink).</span></span>
     * </span>@return</span> calls</span> The list of calls that correspond to the requester and request</span></span>
     */</span></span>
    function</span> getCalls</span>(</span>address</span> requester</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> returns</span> (</span>Call</span>[</span>]</span> memory</span> calls</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Returns the details for the given error code. Meant to be called by developers to better understand the error code for a resolver.</span></span>
     *  Due to localization needs, it is expected that developers may call this function, but the wallet should not show this information to users.</span></span>
     */</span></span>
    function</span> getErrorCodeDetails</span>(</span>uint256</span> errorCode</span>)</span> external</span> returns</span> (</span>string</span> memory</span> information</span>)</span>;</span></span>
}</span></span></code></pre>

The function MAY</strong> modify state. Wallets SHOULD</strong> call it off-chain, and avoid combining the call with others e.g.
via Multicall.</li>
The requester</code> is included to allow the contract to tailor results to the specific user. For example, a resolver
could check requester</code>’s token holdings or permissions and then return different call sets. The wallet should supply
its own sending address as requester</code>. This means that the user’s address is revealed only to the RPC server</em> used
by the wallet via this call, not to the dApp server or UI. In the future with the propagation of light clients, it's
possible for the wallet to avoid revealing this information.</li>
The data</code> parameter is the exact bytes provided in the UWULink request’s resolver_data</code>. Its contents and encoding
are defined by the dApp’s usage and the contract’s logic. For instance, it might contain an enum indicating which
action to perform, or some user-specific claim ID, etc.</li>
The size of the returned arrays is not explicitly limited by this standard, but practical use should keep it
reasonable (dozens rather than thousands of calls) both for blockchain computation reasons and for the user’s ability
to comprehend the request.</li>
</ul>
Wallets should implement the following logic for programmable requests:</p>

Perform an eth_call</code> to resolver_address</code> with to = resolver_address</code>, from = address(0)</code>,
data = ABIEncodeWithSelector(UWUResolver.getCalls, userAddress, resolver_data)</code> against the latest block. The wallet
MAY</strong> use the pending block, or otherwise include transactions in the state that are yet to be included in a
confirmed block.</li>
If the call returns successfully, decode the result. This becomes the batch of calls to execute. The wallet should
then proceed exactly as if it were a static mode request containing those calls. It should display these calls to the
user for confirmation (including target addresses, values, and perhaps decoded method signatures if it can).</li>
If the call fails (reverts or is not implemented), the wallet MUST</strong> abort. It SHOULD surface an error to the user
like "Transaction request generation failed: resolver contract call was unsuccessful." The user then knows the dApp’s
request was bad or the contract might be wrong.</li>
</ol>
The dApp developer and resolver contract developer are responsible for ensuring that calling getCalls</code> is not too
gas-intensive to execute (since wallets will execute it off-chain but it still must complete execution). Excessive
computation could result in the node returning an error (out of gas exception in the eth_call context). Typically these
functions will just gather data from known contracts or encode some predefined calls, which should not be prohibitively
expensive.</p>
Example Usage</h3>
To illustrate how UWULink can be used in practice, consider the following scenarios:</p>
1. Static Mode – Token Approval and Swap (DeFi use-case):</strong></p>
Alice wants to trade tokens on a decentralized exchange (DEX) using her mobile wallet, but she doesn't want to connect
her wallet to the DEX website due to privacy concerns. The DEX dApp prepares a UWULink QR code for the trade. When Alice
selects the tokens and amount on the website, the dApp formulates two contract calls: one to the ERC-20</a> token contract
to approve()</code> the DEX's router contract, and one to the router contract to execute the swap (
swapExactTokensForTokens</code>, for example). Normally this would be two separate transactions with two confirmations.
Instead, the dApp bundles them:</p>

Call #1: to = TokenContract, data = approve(router, amount)</code></li>
Call #2: to = RouterContract, data = swapExactTokensForTokens(params...)</code></li>
</ul>
Both calls have value = 0</code> (no ETH being sent directly). The dApp encodes these into a UWULinkRequest (static mode) for
the current chain (e.g. Ethereum mainnet chain_id 1). The protobuf binary is base64 encoded and placed into a QR code
with a URI like:</p>
uwulink:CgEBEiAx...   (truncated)</span></span></code></pre>
Alice scans this QR with her wallet app. The wallet decodes the request: chain_id=1, two calls in batch. It recognizes
it can execute an atomic batch (Alice’s wallet supports EIP-7702</a>). The wallet UI shows Alice a summary: "This dApp is
requesting two actions: (1) Approve Token XYZ for spending, (2) Swap Token XYZ for Token ABC on DEX." Alice can inspect
the contract addresses (perhaps the wallet resolves known token/contract names or shows the hex addresses) and the
parameters. She sees that both will be submitted together in one transaction. The UI might look similar to a multi-call
confirmation screen.</p>
Alice accepts. Her wallet internally either crafts a 0x4 type transaction (since Alice is an EOA on Ethereum) embedding
bytecode to do the two calls, or uses its smart wallet module. It then signs and broadcasts the transaction. On-chain,
the two calls execute one after the other, and because of atomicity, if the swap were to fail, the approve would be
reverted too (avoiding a scenario where she approved tokens without actually swapping).</p>
The DEX backend or frontend can monitor the blockchain for the transaction receipt (it knows what actions it expected,
or Alice can manually input the tx hash if needed). The important part is the DEX never learned Alice’s address
beforehand; it only sees it when the transaction hits the blockchain, which is unavoidable for executing the trade but
at that point privacy is preserved as well as any normal on-chain interaction (the dApp cannot link it to Alice’s web
session unless Alice herself tells it out-of-band). This shows how UWULink achieves one-scan confirmation for what used
to be multi-step, and keeps Alice’s identity private until the on-chain execution.</p>
2. Programmable Mode – Personalized Airdrop Claim:</strong></p>
A project is running an airdrop where eligible users can claim several different token rewards based on on-chain
activity. Bob visits the airdrop dApp page. The page could ask Bob to connect his wallet to figure out what he’s
eligible for, but Bob is cautious. Instead, the dApp uses UWULink in programmable mode. It has a resolver contract
deployed on-chain which, given a user address, can determine all the reward token contracts and amounts that the user is
entitled to claim.</p>
The dApp shows Bob a “Claim Rewards” button, which reveals a QR code. This QR encodes a UWULink request with:</p>

chain_id = 5</code> (Goerli testnet, for example, where the airdrop is happening).</li>
resolver_address = 0xDeeD…1234</code> (the address of the AirdropResolver contract).</li>
resolver_data =</code> some bytes encoding maybe an airdrop campaign identifier or simply empty if one global campaign.</li>
</ul>
Bob scans this with his wallet. The wallet sees it's a resolver-type request. It calls
getBatchCalls(BobAddress, resolver_data)</code> on 0xDeeD...1234</code> (as a view call). The AirdropResolver contract looks up
internally that BobAddress is eligible for 3 tokens: TokenA, TokenB, and TokenC with certain amounts, and the claim
function for each is claim(address claimant, uint256 amount)</code> on each token’s distributor contract. It returns three
arrays: targets = [AddrA, AddrB, AddrC]</code>, values = [0,0,0]</code> (no ETH needed), callData =
[ abi.encodeWithSelector(Distributor.claim, Bob, amtA), ... ]</code> for each token.</p>
The wallet receives these arrays. It now has three calls to execute. It shows Bob: "Claim TokenA: amount X, Claim
TokenB: amount Y, Claim TokenC: amount Z" (assuming the wallet can decode the function signatures or at least show
contract addresses and method names if it has ABIs). Bob approves the batch. The wallet then either directly calls each
distributor’s claim</code> in one aggregated transaction. Because Bob’s address was provided to the resolver, each claim call
will credit tokens to Bob (likely the contract uses the provided address or msg.sender</code> – here it was likely coded to
use the address parameter, since the actual transaction sender will be Bob’s own address in the batch execution
context). The important part is Bob did not have to connect his wallet to the dApp; the eligibility and calls were
determined by the on-chain contract. The dApp never saw Bob’s address, yet Bob gets his tokens in one go.</p>
After execution, Bob’s wallet shows the transaction success. The dApp might simply tell him to check his balances (or it
could have a public page showing which addresses claimed, etc., but it did not get a direct notification — it relies on
Bob or the blockchain to know the claim happened).</p>
3. Cross-Device Payment via NFC (Point of Sale):</strong></p>
Carol is at a merchant's point-of-sale device that accepts cryptocurrency payments via Ethereum. The merchant’s device
can display a QR or emit an NFC message with a payment request. Instead of using a simple one-address payment URI (as in
EIP-681</a>), the merchant uses UWULink to request a more sophisticated transaction: perhaps Carol will pay through a
specific escrow contract or with a certain token if she has a discount coupon.</p>
The device sends an NFC payload</strong> which Carol’s phone picks up (many wallet apps can register as handlers for certain
NDEF messages or custom URI schemes). The payload contains a UWULinkRequest in static mode:</p>

chain_id = 137 (Polygon, where the merchant operates).</li>
Two calls: first call to a stablecoin contract’s transfer(merchantAddress, amount)</code> (to pay the merchant), second
call to a logging contract registerPurchase(merchantId, CarolAddress, amount)</code> (to log the sale in an on-chain
registry). Both calls are value 0 since a token transfer, not ETH, is used.</li>
</ul>
Carol’s wallet opens with the decoded request: It shows "Pay 50 USDC to Merchant XYZ and register purchase." Carol sees
the merchant name resolved from the merchant’s address (if her wallet has ENS or a local registry of known merchants).
She approves. The wallet then executes an atomic transaction on Polygon that calls the USDC token contract and the
registry contract. The merchant’s PoS waits for confirmation on-chain (or simply trust the signed transaction once
broadcast, depending on their risk tolerance). Carol’s identity remained pseudonymous; the merchant’s device did not
directly get her wallet info, it only received the on-chain payment. And Carol only had to tap once to approve both
token transfer and logging, rather than scan one QR to pay then perhaps another to log, etc.</p>
These examples demonstrate the flexibility of UWULink:</p>

In all cases, the user did not pre-connect their wallet to the application.</li>
The requests can be transferred via out-of-band channels (QR/NFC/URL).</li>
Multi-step operations become “one-click” (or one-scan) operations for the user.</li>
The on-chain outcome is the same as if the user had manually sent those transactions, but with improved UX and
privacy.</li>
</ul>
Rationale</h2>
TBD </p>
Backwards Compatibility</h2>
UWULink is an additive protocol and does not break any existing standards. It is designed to coexist with current
methods:</p>


Existing Wallet URIs (EIP-681</a>, EIP-831</a>):</strong> UWULink can be seen as an evolution of the idea behind EIP-681 (
transaction request URIs). EIP-681 defines URIs for a single transaction (or payment) and is already supported in a
limited number of wallets for QR code scanning. UWULink extends the concept to multiple calls and binary encoding. A
wallet that does not recognize the uwulink:</code> scheme should simply not act on it. Typically, such
a wallet would either show an error or ignore a scanned QR it cannot parse. This is a graceful failure from the user's
perspective (they'll know the wallet doesn't support that request). There is no risk of confusing an UWULink QR with
an EIP-681 QR, since the scheme and content format differ. Therefore, wallets that only implement support for EIP-681
will not mistakenly handle a UWULink payload as a valid request.</p>
</li>

Ensuring Backwards Compatibility in Data Format:</strong> The protobuf schema is designed such that new fields could be
added in the future in a non-breaking way (per Proto3 rules, unknown fields are ignored by receivers). For example, a
future version might add an optional uint64 expiration_timestamp</code> or string origin</code> field to carry a domain name for
UI display. An older wallet would ignore these and still execute the core request. This forward-compatibility means
UWULink can evolve without breaking older implementations, as long as additions are carefully made optional.</p>
</li>

Fall-back to Standard Flows:</strong> From a dApp perspective, implementing UWULink does not preclude supporting
traditional wallet connections. A dApp can offer UWULink QR codes for users who prefer privacy or are on devices (like
a separate mobile) without browser extensions. At the same time, it can have the usual “Connect Wallet” button for
users who are okay with that. This multi-modal approach ensures no user is left out. Over time, if UWULink (or similar
one-way flows) prove safer and more popular, they might become the default, allowing users to interact with dApps
without connecting a wallet.</p>
</li>

Network Compatibility:</strong> We limit scope to EVM-compatible chains. That means chains that use EIP-155</a> transaction
scheme and Ethereum-like addresses. On non-EVM chains, this standard doesn’t apply (though analogous concepts could).
Within EVM chains, a nuance: if a chain has a different maximum gas limit or transaction format peculiarity, the
wallet internally deals with that. UWULink just says "execute these calls." As long as the wallet can create a
transaction that does so, it’s fine. If an EVM chain does not support atomic multi-call (some L2s or sidechains might
not immediately support EIP-7702), the wallet has to handle it at the account abstraction layer if possible, or
otherwise MUST</strong> reject the request. This again falls to the wallet to know its capabilities (e.g. per EIP-5792</a>’s
capabilities query).</p>
</li>
</ul>
In conclusion, UWULink aims to introduce new functionality without disrupting existing user journeys. It is opt-in for
all parties. Early adopters (both dApps and wallets) can experiment with it while others continue as usual. As support
grows, it could become a widely recognized standard for secure one-way wallet interactions. The design takes into
account lessons from previous proposals (EIP-681</a> URIs, WalletConnect, EIP-5792</a>, etc.) and ensures that adopting UWULink
is a low-risk enhancement rather than a breaking change to Ethereum’s ecosystem.</p>

Security Considerations</h2>
Privacy</h3>
UWULink is designed with privacy in mind, but it introduces some new security aspects that implementers and users should
consider:</p>

No Wallet Identification:</em> The wallet does not disclose the user’s address or any wallet details to the dApp when
using UWULink. This significantly improves privacy compared to typical wallet connect flows. The dApp only learns of
the user's address if and when the transaction is broadcast on-chain. Even then, the dApp cannot easily correlate that
address with a specific user session (the user could be anonymous on the website until that point).</li>
On-Chain Resolver Calls:</em> In programmable mode, the user's address is supplied to the resolver contract as a
parameter. This happens off-chain via eth_call</code>, so it does not create a public transaction. However, the node or RPC
provider that the wallet uses will see that call (just like any read call). If the RPC provider is untrusted, this
could leak some information (e.g., that this address is interested in this resolver's data). In most cases this is a
minor concern (no more revealing than using the dApp itself while connected to an RPC), but users who are extremely
privacy-conscious might prefer static mode or ensure they use a privacy-respecting RPC. Importantly, the dApp backend
or frontend does not see this – only the blockchain infrastructure does.</li>
No Third-Party Tracking:</em> Because UWULink can be used via local channels (QR/NFC), it avoids relying on any
centralized relay. WalletConnect v1, for instance, used relay servers and handshake topics which, in theory, could be
tracked or snooped (even though payloads were encrypted, the metadata might leak usage patterns). UWULink in contrast
can be a completely peer-to-peer (user and dApp) interaction with minimal digital footprint aside from the eventual
blockchain transaction.</li>
User Consent:</em> As with any transaction, the user explicitly consents by scanning and approving the request. The
user relies on the wallet's simulation and multi-factor authorization capabilities to prevent sending of malicious
transactions.</li>
</ul>
Security of Transaction Requests</h3>


Phishing and Malicious QR Codes:</em> A malicious actor could present a user with a UWULink QR code that, if scanned and
approved blindly, could cause the user to transfer funds or approve tokens to the attacker. This risk is analogous to
phishing links or malicious dApp websites in today's context. Users should be educated to only approve UWULink
requests from sources they trust or understand. Wallets should help by displaying clear human-readable information</strong>
about what the request will do:</p>

Show the names or ENS of known contract addresses involved (or at least highlight unknown addresses).</li>
Decode function selectors to known function names if possible (e.g., show "approve(address _spender, uint256
_value)" instead of raw hex).</li>
For value transfers, show the ETH or token amount in a friendly format.</li>
Possibly warn if the request involves calling an unrecognized contract with large value transfers or if it sets a
high token allowance, etc.</li>
</ul>
</li>

Atomic Execution and Reverts:</em> By enforcing atomic execution, UWULink ensures that partial completion won't lead to
stuck funds or unintended states. However, this also means a malicious or buggy request could be crafted to always
revert (for example, by including an incompatible call), which could waste user gas fees if not caught. Wallets should
simulate the batch when possible. If the wallet can do a dry-run (for instance using eth_call</code> on a Bundler or
internal simulation) it might detect a guaranteed revert and inform the user that the call set is invalid (though this
might be complex to do reliably for all calls).</p>
</li>

Resolver Contract Trust:</em> The programmable mode introduces a potential trust issue: the user is effectively trusting
the resolver contract’s code to generate the calls honestly. If the resolver contract is malicious, it could return
call data that benefits an attacker. For example, a malicious resolver could ignore the input data and always return a
call transferring all of the user's ETH to the attacker’s address. Mitigations:</strong></p>

Ideally, resolver contracts should be open source and verified, and the dApp using them should be reputable. The
wallet can’t fully know if the resolver’s output is malicious until it sees it, but the user will have a chance to
review the resulting calls anyway. This is crucial: the wallet must display the resulting calls</em> from the
resolver to the user, just as it would in static mode. The user should then notice if something is off (e.g., a
transfer of all their ETH is about to happen).</li>
Wallet developers might consider adding special handling or warnings if a resolver returns calls that do not seem
correlated with the input. However, this is hard to generalize. At minimum, treat the resolver output with the
same suspicion as a static request. There’s no inherent additional risk beyond what static mode has, because the
user still confirms the final calls. The difference is just where the call data came from.</li>
We assume resolver contracts will often be provided by the same party as the dApp and thus come with an implied
level of trust (or at least, they can be audited by the community if the UWULink scheme becomes popular).</li>
</ul>
</li>

No Automatic Spending:</em> UWULink does not introduce new signing or authorization paradigms – it uses actual
transactions that the user signs on the spot. Thus, it’s less prone to the kind of issues where a signature can be
later reused (like the risks with off-chain signatures). Each UWULink request is one transaction (with possibly
multiple subcalls). After it's executed, the link cannot be reused to automatically trigger more actions (unless the
user scans it again). This is good from a security standpoint since it doesn't create long-lived permissions. One
exception: if a call within the batch is an approval or something, that is an on-chain permission that persists as
usual (the user should be made aware as normal).</p>
</li>

Denial of Service (DOS):</em> A malicious dApp could craft an extremely large UWULink payload (especially in static mode)
that could crash or slow a wallet app upon scanning (due to memory or decoding issues). Wallets should implement size
limits and perhaps streaming parsing for the protobuf to avoid crashes. If a payload exceeds a reasonable size (e.g.,
several kilobytes), the wallet can reject it for safety. Similarly, a resolver contract could try to return extremely
large results – wallets should guard against that by limiting the amount of gas provided to the resolver via eth_call.</p>
</li>

Capabilities and Future Extensions:</em> UWULink intentionally does not carry any additional flags like gas limits or
paymaster info (unlike EIP-5792 which has a capabilities system). This is to keep the format simple. However, this
means the wallet will apply its own heuristics for gas, and by default the user pays fees. If a future extension
wanted to allow gas sponsorship or other features, that could be added either by extending the protobuf (e.g., adding
an optional paymaster field) or by having the resolver contract itself handle that (e.g., a resolver could incorporate
a paymaster logic by returning a call to a paymaster contract as part of the batch). In any case, security
considerations around gas (like a malicious paymaster causing some weird behavior) would need to be analyzed. For now,
UWULink operates within the normal transaction model, so the main security focus is on the correctness of calls.</p>
</li>
</ul>
Comparison to Traditional Flows:</strong> One might ask, does eliminating the wallet <-> dApp handshake create any new risks?
In traditional connected dApp sessions, the wallet at least knows the origin of requests (e.g., which website is calling
eth_sendTransaction</code> or wallet_sendCalls</code>). In UWULink, the origin is essentially "the QR code the user scanned" – the
wallet might know the payload came via a QR/NFC but not which app or site. In security terms, this means the wallet
cannot apply domain-based whitelists or blocklists (since there's no domain, unless the URI contains one in the payload
which it typically wouldn't). Therefore, the user must manually trust and verify each request.</strong> This is akin to using
a hardware wallet: every transaction is shown on a screen and the user approves it, with no assumptions about where it
came from. This places responsibility on the user and makes the wallet’s job of displaying info accurately even more
important.</p>
Privacy vs. Usability Trade-off:</strong> Because UWULink doesn’t let the dApp query the wallet off-chain, some conveniences
are lost – e.g., the dApp cannot automatically fetch the user's address to display their balance or NFTs in the UI prior
to a transaction. This is a conscious privacy trade-off. Some advanced dApps might find workarounds (like asking the
user to input their address manually if they want to see personalized info, or shifting more logic on-chain as in
programmable mode). Users and dApp developers must understand this trade-off. In contexts where user personalization
without login is needed, UWULink might require a bit more creativity, but it ensures that if the user chooses not to
share anything, they truly don't until a transaction is made.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Confidential Transactions Supported Token
2025-05-09T00:00:00+00:00
Abstract</h2>
Classic token contracts like ERC-20</a> enable their token holders to make transfers and/or approve others to make transfers on their behalves. The generality of token standard ERC-20</a> catalyzed decentralizing finance and many other blockchain applications. However, when it comes to privacy, although some technical schemes have been proposed, few standards have been established, which limits the evolution of privacy-preserving blockchain applications.</p>
This proposal draws up a standard interface for fungible token contracts supporting confidential transactions. It provides basic transfer functionality without loss of generality, and allowance and approve functionalities. Contracts following the standard can provide confidentiality for users’ balances and token transfer value, and can enable other blockchain applications to make transfers on behalf of owners, which empowers more privacy-preserving capabilities to blockchain applications.</p>
Motivation</h2>
Confidential transactions have been implemented in many blockchains, either natively through blockchain protocols like Monero and Zcash, or through smart contracts like Zether1</a></sup> without modifying blockchain protocol.</p>
However, when it comes to the latter way, actually few standards are proposed yet on Ethereum (and/or other EVM-compatible blockchains) to illustrate such contracts. Users and applications cannot easily detect whether a token contract supports confidential transactions or not, and so hardly can they make transfers without revealing the actual amount.</p>
Consequently, this proposal is to standardize the confidential transaction supported token contracts, meanwhile without loss of generality, by only specifying core methods and events.</p>
Such standard interface allows confidential transactions of tokens to be applied by certain parties which are sensitive to transfer amount, or by privacy-preserving applications.</p>
Specification</h2>
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.</p>
Contract Interface</h3>
The proposed contract implements the following 2 interfaces: ITokenMetadata</code> and IConfidentialToken</code> .</p>
ITokenMetadata</code></h4>
Methods</h5>
name</code></h6>
function</span> name</span>(</span>)</span> public</span> view</span> returns</span> (</span>string</span>)</span></span></code></pre>
Returns the name of the token - e.g. "MyConfidentialToken"</code> .</p>
OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</p>
symbol</code></h6>
function</span> symbol</span>(</span>)</span> public</span> view</span> returns</span> (</span>string</span>)</span></span></code></pre>
Returns the symbol of the token. e.g. "cHIX"</code> .</p>
OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</p>
decimals</code></h6>
function</span> decimals</span>(</span>)</span> public</span> view</span> returns</span> (</span>uint8</span>)</span></span></code></pre>
Returns the number of decimals the token uses - e.g. 8</code> , means to divide the token amount by 100000000</code> to get its user representation.</p>
OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</p>
IConfidentialToken</code></h4>
Methods</h5>
confidentialBalanceOf</code></h6>
function</span> confidentialBalanceOf</span>(</span>address</span> owner</span>)</span> </span></span>
public</span> view</span> returns</span> (</span>bytes</span> memory</span> confidentialBalance</span>)</span></span></code></pre>
Returns the confidential balance of the account with address owner</code> .</p>
confidentialTransfer</code></h6>
function</span> confidentialTransfer</span>(</span></span>
  address</span> _to</span>,</span></span>
  bytes</span> memory</span> _confidentialTransferValue</span>,</span> </span></span>
  bytes</span> memory</span> _proof</span></span>
)</span> public</span> returns</span> (</span>bool</span> success</span>)</span></span></code></pre>
Transfers value</code> amount of tokens (behind _confidentialTransferValue</code> ) to address _to</code> , and MUST fire the ConfidentialTransfer</code> event. The function SHOULD throw</code> if the message caller’s _proof</code> of this transfer fails to be verified.</p>
Note:</p>


Callers MUST handle false</code> from returns (bool success). Callers MUST NOT assume that false</code> is never returned!</p>
</li>

Implementations can fully customize the proof system, (de)serialization strategies of bytes</code> and/or the business workflow. For example, when implementing "Zether"^{1</a></sup> confidential token contracts, the _confidentialTransferValue</code> and accounts' confidential balances will be encrypted homomorphically under ElGamal public keys, and _proof</code> will consist 3 parts to check:</p>}

_confidentialTransferValue</code> is well encrypted under both caller's public key and _to</code> 's;</li>
The plaintext value</code> behind _confidentialTransferValue</code> is non-negative;</li>
The caller's confidential balance is actually enough to pay the plaintext value</code> behind _confidentialTransferValue</code> .</li>
</ul>
</li>
</ul>
confidentialTransferFrom</code></h6>
function</span> confidentialTransferFrom</span>(</span></span>
  address</span> _from</span>,</span></span>
  address</span> _to</span>,</span></span>
  bytes</span> memory</span> _confidentialTransferValue</span>,</span> </span></span>
  bytes</span> memory</span> _proof</span></span>
)</span> public</span> returns</span> (</span>bool</span> success</span>)</span></span>
  </span></span></code></pre>
Transfers value</code> amount of tokens (behind _confidentialTransferValue</code> ) from address _from</code> to address _to</code> , and MUST fire the ConfidentialTransfer</code> event.</p>
The confidentialTransferFrom</code> method is used for a withdraw workflow, allowing contracts to transfer tokens on your behalf. This can be used for example to allow a contract to transfer tokens on your behalf and/or to charge fees in sub-currencies. The function SHOULD throw</code> unless the _from</code> account has deliberately authorized the sender of the message via some mechanism, and SHOULD throw</code> if the message caller’s _proof</code> of this transfer fails to be verified.</p>
Note:</p>


Callers MUST handle false</code> from returns (bool success). Callers MUST NOT assume that false</code> is never returned!</p>
</li>

Implementations can fully customize the proof system, (de)serialization strategies of bytes</code> and/or the business workflow. For example, when implementing "Zether" confidential token contracts, the _confidentialTransferValue</code> and accounts' confidential balances will be encrypted homomorphically under ElGamal public keys, and _proof</code> will consist 3 parts to check:</p>

_confidentialTransferValue</code> is well encrypted under public keys of _from</code> 's, _to</code> 's and caller's;</li>
The plaintext value</code> behind _confidentialTransferValue</code> is non-negative;</li>
The caller's confidential allowance is actually enough to pay the plaintext value</code> behind _confidentialTransferValue</code> .</li>
</ul>
</li>
</ul>
confidentialApprove</code></h6>
function</span> confidentialApprove</span>(</span></span>
  address</span> _spender</span>,</span></span>
  bytes</span> memory</span> _confidentialValue</span>,</span> </span></span>
  bytes</span> memory</span> _proof</span></span>
)</span> public</span> returns</span> (</span>bool</span> success</span>)</span></span></code></pre>
Allows _spender</code> to withdraw from caller's split part of balances multiple times, up to the amount (allowance value) behind _confidentialValue</code> to 0. This function SHOULD throw</code> if the message caller’s _proof</code> of this transfer fails to be verified.</p>
Caution:</p>
This function behaves much differently from</strong> approve(address,uint256)</code> in ERC-20</a>.</p>
Calling confidentialApprove</code> splits the confidential balance of caller's account into allowance part</em> and the left part</em>.</p>
The values behind two parts above after calling confidentialApprove</code> , and the value behind the original confidential balance of caller's account before calling confidentialApprove</code> satisfy the equation:</p>
$$
value_{Behind\ Allowance\ Part} + value_{Behind\ Left\ Part} = value_{Behind\ Original\ Confidential\ Balance}
$$</p>


The allowance part of confidential balance allows _spender</code> to withdraw multiple times through calling confidentialTransferFrom</code> until _spender</code> does not call it any more or the value behind this part is 0.</p>

Every time the _spender</code> calls confidentialTransferFrom</code> , the value behind this part will be decreased by the value behind _confidentialTransferValue</code> .</li>
</ul>
</li>

The left part remains as the new confidential balance of caller's account.</p>
</li>
</ul>
If this function is called again it,</p>

merges existing allowance part into the confidential balance of caller's account; and then</li>
overwrites the current allowance part with _confidentialValue</code> .</li>
</ul>
Note:</p>


Callers MUST handle false</code> from returns (bool success). Callers MUST NOT assume that false</code> is never returned!</p>
</li>

Implementations can fully customize the proof system, (de)serialization strategies of bytes</code> and/or the business workflow. For example, when implementing "Zether" confidential token contracts, the _confidentialValue</code> and accounts' confidential balances will be encrypted homomorphically under ElGamal public keys, and _proof</code> will consist 3 parts to check:</p>

_confidentialValue</code> is well encrypted under public keys of caller's and _spender</code>'s;</li>
The plaintext value</code> behind _confidentialValue</code> is non-negative;</li>
The caller's confidential balance is actually enough to pay the plaintext value</code> behind _confidentialValue</code> .</li>
</ul>
</li>
</ul>
confidentialAllowance</code></h6>
functinon </span>confidentialAllowance</span>(</span>address</span> _owner</span>,</span> address</span> _spender</span>)</span></span>
public</span> view</span> returns</span> (</span>bytes</span> memory</span> _confidentialValue</span>)</span></span></code></pre>
Returns the allowance part which _spender</code> is still allowed to withdraw from _owner</code>.</p>
Events</h5>
ConfidentialTransfer</code></h6>
event</span> ConfidentialTransfer</span>(</span></span>
  address</span> indexed</span> _spender</span>,</span></span>
  address</span> indexed</span> _from</span>, </span></span>
  address</span> indexed</span> _to</span>, </span></span>
  bytes</span> _confidentialTransferValue</span></span>
)</span></span></code></pre>
MUST trigger when tokens are transferred.</p>
Specifically, if tokens are transferred through function confidentialTransferFrom</code>, _spender</code> address MUST be set to caller's; otherwise, it SHOULD be set to 0x0</code>.</p>
A confidential token contract,</p>

which creates new tokens SHOULD trigger a ConfidentialTransfer</code> with the _from</code> address set to 0x0</code> when tokens are minted;</li>
which destroys existent tokens SHOULD trigger a ConfidentialTransfer</code> with the _to</code> address set to 0x0</code> when tokens are burnt.</li>
</ul>
ConfidentialApproval</code></h6>
event</span> ConfidentialApproval</span>(</span></span>
  address</span> indexed</span> _owner</span>,</span></span>
  address</span> indexed</span> _spender</span>,</span></span>
  bytes</span> _currentAllowancePart</span>,</span></span>
  bytes</span> _allowancePart</span></span>
)</span></span></code></pre>
MUST trigger on any successful call to confidentialApprove(address,bytes,bytes)</code>.</p>
Rationale</h2>
Optional Accessor of "Confidential Total Supply"</h3>
function</span> confidentialTotalSupply</span>(</span>)</span> public</span> view</span> returns</span> (</span>bytes</span> memory</span>)</span></span></code></pre>
Confidentiality of transfer amount makes it hard to support such field like totalSupply()</code> in ERC-20</a>. Because when it comes to the token "mint" or "burn", if every user in this contract can access totalSupply()</code> as well as decrypt it, these users will know the actual token value to be minted or burnt by comparing the totalSupply()</code> before and after such operations, which means that confidentiality no longer exists.</p>
Contract implementation can optionally support confidentialTotalSupply()</code> by evaluating if anti-money laundry (see next part) and audit are required. That would be much more plausible by making a small group of parties can know the plaintext total supply behind confidentialTotalSupply()</code>.</p>
Anti-money Laundry and Audit</h3>
To support audit of confidential transactions and total supply, especially such token issuers are banks or other financial institutes supervised by governments or monetary authorities, confidential transactions can be implemented without changing confidentialTransfer</code> method signature, by encoding more info into parameters.</p>
For example in Zether-like implementation[^2], if token transfers are required to be audited, confidentialTransfer</code> caller encrypts transfer value</code> redundantly under public keys of caller's, to</code>'s, a group of auditors', which makes it possible that related parties can exactly know the real value</code> behind. So does confidentialTotalSupply()</code>.</p>
Fat Token</h3>
Confidential transactions supported token can also implement ERC-20</a> at the same time.</p>
Token accounts in such tokens can hold 2 kinds of balances. Such token contracts can optionally provide methods to hide ERC-20</a> plaintext balances into confidential balances, and vice versa, to reveal confidential balances back to ERC-20</a> plaintext balances.</p>
ERC-20</a> interfaces will bring much more usability and utilities to confidential transaction supported tokens, realizing general confidentiality meantime.</p>
Backwards Compatibility</h2>
No backward compatibility issues found.</p>
Security Considerations</h2>
To realize full confidentiality, contracts implementing this presented interface SHOULD NOT create (mints) or destroy (burns) tokens with plaintext value parameters. For implementation, following the same encryption strategies in confidentialTransfer(address,bytes,bytes)</code> is RECOMMENDED.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>



Bünz, B., Agrawal, S., Zamani, M., & Boneh, D. (n.d.). Zether: Towards Privacy in a Smart Contract World</span>. https://doi.org/10.1007/978-3-030-51280-4_23</a> (Original work published 2020)[^2]: Chen, Y., Ma, X., Tang, C., & Au, M. H. (n.d.). PGC: Decentralized Confidential Payment System with Auditability</span>. https://doi.org/10.1007/978-3-030-58951-6_29</a> (Original work published 2020) ↩</a> ↩2</a></p>
</li>
</ol>
</section>


Account Abstraction Recovery Interface
2025-05-07T00:00:00+00:00
Abstract</h2>
Introduce a universal account abstraction recovery mechanism recoverAccess(subject, provider, proof)</code> along with recovery provider management functions for smart accounts to securely update their access subject.</p>
Motivation</h2>
Account abstraction and the "contractization" of EOAs are important Ethereum milestones for improving on-chain UX and off-chain security. A wide range of smart accounts emerge daily, aiming to simplify the steep onboarding curve for new users. The ultimate smart account experience is to never ask them to deal with private keys, yet still allow for full account control and access recovery. With the developments in the Zero-Knowledge Artificial Intelligence (ZKAI) and Zero-Knowledge Two Factor Authentication (ZK2FA) fields, settling on a common mechanism may even open the doors for "account recovery provider marketplaces" to emerge.</p>
The account recovery approach described in this proposal allows for multiple recovery providers to coexist and provide a wide variety of unique recovery services. In simple terms, smart accounts become "recovery provider aggregators", making it possible for the users to never rely on centralized services or projects.</p>
The Account Abstraction Recovery Interface (AARI) aims to define a flexible interface for any</em> smart account to implement, allowing users to actively manage their account recovery providers and restore the access of an account in case of a private key loss.</p>
Specification</h2>
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.</p>
A smart account willing to support AARI MUST implement the following interface:</p>
pragma</span> solidity</span> ^0.8.20</span>;</span></span>
</span>
/**</span></span>
 * </span>@notice</span> Defines a common account recovery interface for smart accounts to implement.</span></span>
 */</span></span>
interface</span> IAccountRecovery</span> {</span></span>
    /**</span></span>
     * MUST be emitted whenever the access of the account changes as a result </span></span>
     * of the account recovery (e.g. in the `recoverAccess` function).</span></span>
     */</span></span>
    event</span> AccessRecovered</span>(</span>bytes</span> subject</span>)</span>;</span></span>
    </span></span>
    /**</span></span>
     * MUST be emitted whenever a new recovery provider is added to</span></span>
     * the account (e.g. in the `addRecoveryProvider` function).</span></span>
     */</span></span>
    event</span> RecoveryProviderAdded</span>(</span>address</span> indexed</span> provider</span>)</span>;</span></span>
</span>
    /**</span></span>
     * MUST be emitted whenever a recovery provider is removed from</span></span>
     * the account (e.g. in the `removeRecoveryProvider` function).</span></span>
     */</span></span>
    event</span> RecoveryProviderRemoved</span>(</span>address</span> indexed</span> provider</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> A function to add a new recovery provider.</span></span>
     * SHOULD be access controlled.</span></span>
     * MUST check that `provider` is not `address(0)`.</span></span>
     * MUST call `subscribe` on the `provider`.</span></span>
     * MUST pass `recoveryData` to the `subscribe` function.</span></span>
     * </span></span>
     * </span>@param</span> provider</span> the address of a recovery provider (ZKP verifier) to add.</span></span>
     * </span>@param</span> recoveryData</span> custom data (commitment) for the recovery provider.</span></span>
     */</span></span>
    function</span> addRecoveryProvider</span>(</span>address</span> provider</span>,</span> bytes</span> memory</span> recoveryData</span>)</span> external</span> payable</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> A function to remove an existing recovery provider.</span></span>
     * SHOULD be access controlled.</span></span>
     * MUST call `unsubscribe` on the `provider`.</span></span>
     * </span></span>
     * </span>@param</span> provider</span> the address of a previously added recovery provider to remove.</span></span>
     */</span></span>
    function</span> removeRecoveryProvider</span>(</span>address</span> provider</span>)</span> external</span> payable</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> A view function to check if a provider has been previously added.</span></span>
     * </span></span>
     * </span>@param</span> provider</span> the provider to check.</span></span>
     * </span>@return</span> true</span> if the provider exists in the account, false otherwise.</span></span>
     */</span></span>
    function</span> recoveryProviderAdded</span>(</span>address</span> provider</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> A non-view function to recover access of a smart account.</span></span>
     * MUST check that `provider` exists in the account.</span></span>
     * MUST call `recover` on the `provider`.</span></span>
     * MUST update the account access according to `subject` if `proof` verification succeeds.</span></span>
     * MUST return `true` if the access recovery is successful.</span></span>
     * </span></span>
     * </span>@param</span> subject</span> the recovery subject (encoded owner address, access control role, etc).</span></span>
     * </span>@param</span> provider</span> the address of a recovery provider.</span></span>
     * </span>@param</span> proof</span> an encoded proof of recovery (ZKP/ZKAI, signature, etc).</span></span>
     * </span>@return</span> `true` if recovery is successful, `false` (or revert) otherwise.</span></span>
     */</span></span>
    function</span> recoverAccess</span>(</span></span>
        bytes</span> memory</span> subject</span>,</span></span>
        address</span> provider</span>,</span></span>
        bytes</span> memory</span> proof</span></span>
    )</span> external</span> returns</span> (</span>bool</span>)</span>;</span></span>
}</span></span></code></pre>
A recovery provider MUST implement the following interface:</p>
/**</span></span>
 * </span>@notice</span> Defines a common recovery provider interface.</span></span>
 */</span></span>
interface</span> IRecoveryProvider</span> {</span></span>
    /**</span></span>
     * MUST be emitted whenever a new account subscribes to</span></span>
     * the recovery provider (e.g. in the `subscribe` function).</span></span>
     */</span></span>
    event</span> AccountSubscribed</span>(</span>address</span> indexed</span> account</span>)</span>;</span></span>
</span>
    /**</span></span>
     * MUST be emitted whenever an account unsubscribes from</span></span>
     * the recovery provider (e.g. in the `unsubscribe` function).</span></span>
     */</span></span>
    event</span> AccountUnsubscribed</span>(</span>address</span> indexed</span> account</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> A function that "subscribes" a smart account (msg.sender) to a recovery provider.</span></span>
     * SHOULD process and assign the `recoveryData` to the `msg.sender`.</span></span>
     * </span></span>
     * </span>@param</span> recoveryData</span> a recovery commitment (hash/ZKP public output) to be used </span></span>
     * in the `recover` function to check a recovery proof validity.</span></span>
     */</span></span>
    function</span> subscribe</span>(</span>bytes</span> memory</span> recoveryData</span>)</span> external</span> payable</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> A function that revokes a smart account subscription.</span></span>
     * MUST delete all the recovery data associated with the `msg.sender`.</span></span>
     */</span></span>
    function</span> unsubscribe</span>(</span>)</span> external</span> payable</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> A function to get a recovery data (commitment) of an account.</span></span>
     * </span></span>
     * </span>@param</span> account</span> the account to get the recovery data of.</span></span>
     * </span>@return</span> the</span> associated recovery data.</span></span>
     */</span></span>
    function</span> getRecoveryData</span>(</span>address</span> account</span>)</span> external</span> view</span> returns</span> (</span>bytes</span> memory</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> A function that checks if a recovery of a smart account (msg.sender)</span></span>
     * to the new subject is possible.</span></span>
     * SHOULD use `msg.sender`'s `recoveryData` to check the `proof` validity.</span></span>
     * MUST ensure that the `proof` can't be reused, e.g. update nonce.</span></span>
     * </span></span>
     * </span>@param</span> object</span> the new object (may be different to subject) to recover the `msg.sender` access to.</span></span>
     * </span>@param</span> proof</span> the recovery proof.</span></span>
     */</span></span>
    function</span> recover</span>(</span>bytes</span> memory</span> object</span>,</span> bytes</span> memory</span> proof</span>)</span> external</span>;</span></span>
}</span></span></code></pre>Rationale</h2>
The AARI is expected to work with any</em> account abstraction standard to allow for maximum account recovery flexibility. Whether it is EIP-4337</a> or EIP-7702</a>, a particular smart account provider may support account recovery by simply implementing a common interface.</p>
Since the whole account recovery process is nothing but proving the knowledge of some alternative secret to a private key, it is essential for accounts to be able to "commit" to this secret. The subscribe</code> function in the recovery provider interface allows precisely for that. Moreover, if at some point in time a user wanted to "recommit" to a new secret (due to security reasons), they could multicall unsubscribe</code> + subscribe</code> functions to achieve the desired result.</p>
The recovery functions accept arbitrary bytes as subject</code> and object</code> parameters to allow for a variety of access control rules to be recovered, since many smart accounts are ownerless and have no "owner" address to be directly substituted.</p>
Backwards Compatibility</h2>
This EIP is fully backwards compatible.</p>
Security Considerations</h2>
There are several security concerns to point out:</p>

It is up to a smart account developer to properly access control addRecoveryProvider</code> and removeRecoveryProvider</code> functions.</li>
A smart account user may be "phished" to add a malicious recovery provider to their account. In that case, a recovery provider may gain full control over the account by accepting fake recovery proofs.</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Versioned Proxy Contract Interface
2025-04-17T00:00:00+00:00
Abstract</h2>
This EIP standardizes an interface for proxy contracts that allows callers to explicitly select which version of an implementation contract they want to interact with. Unlike traditional proxy patterns that only expose the latest implementation, this standard enables backward compatibility by maintaining access to previous implementations while supporting upgrades. The versioned proxy maintains a registry of implementation addresses mapped to version identifiers, allowing callers to specify their desired version at call time.</p>
Motivation</h2>
Smart contract upgrades are essential for fixing bugs and adding features. Current proxy patterns typically force all callers to use the latest implementation, which can break existing integrations when interfaces change.</p>
Furthermore, traditional proxy patterns expose all users to risk if an upgrade is malicious, as they have no choice but to use the latest implementation. This standard allows users to remain on verified versions they trust, mitigating the risk of a compromised admin key or governance process deploying harmful code.</p>
This EIP addresses several key problems:</p>

Breaking Changes</strong>: Interface changes in new implementations can break existing integrations.</li>
Gradual Adoption</strong>: There is no standard way to allow gradual adoption of new contract versions.</li>
Malicious Upgrades</strong>: Users today must trust proxy admins indefinitely, as they can't opt out of potentially harmful upgrades without ceasing use of the contract entirely.</li>
Trust Assumptions</strong>: Contract users must maintain perpetual trust in governance or admin keys, with no ability to selectively trust specific, audited implementations.</li>
</ol>
Specification</h2>
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.</p>
Interface</h3>
interface</span> IVersionedProxy</span> {</span></span>
    ///</span> @notice</span> Emitted when a new implementation version is registered</span></span>
    ///</span> @param</span> version</span> The version identifier</span></span>
    ///</span> @param</span> implementation</span> The address of the implementation contract</span></span>
    event</span> VersionRegistered</span>(</span>bytes32</span> version</span>, </span>address</span> implementation</span>)</span>;</span></span>
        </span></span>
    ///</span> @notice</span> Emitted when the default version is </span>changed</span></span>
    ///</span> @param</span> oldVersion</span> The previous default version</span></span>
    ///</span> @param</span> newVersion</span> The new default version</span></span>
    event</span> DefaultVersionChanged</span>(</span>bytes32</span> oldVersion</span>, </span>bytes32</span> newVersion</span>)</span>;</span></span>
    </span></span>
    ///</span> @notice</span> Registers a new implementation version</span></span>
    ///</span> @param</span> version</span> The version identifier (e.g., "1.0.0")</span></span>
    ///</span> @param</span> implementation</span> The address of the implementation contract</span></span>
    function</span> registerVersion</span>(</span>bytes32</span> version</span>,</span> address</span> implementation</span>)</span> external</span>;</span></span>
    </span></span>
    ///</span> @notice</span> Removes a version from the registry</span></span>
    ///</span> @param</span> version</span> The version identifier to remove</span></span>
    function</span> removeVersion</span>(</span>bytes32</span> version</span>)</span> external</span>;</span></span>
    </span></span>
    ///</span> @notice</span> Sets the default version to use when no version is specified</span></span>
    ///</span> @param</span> version</span> The version identifier to set as default</span></span>
    function</span> setDefaultVersion</span>(</span>bytes32</span> version</span>)</span> external</span>;</span></span>
    </span></span>
    ///</span> @notice</span> Gets the implementation address for a specific version</span></span>
    ///</span> @param</span> version</span> The version identifier</span></span>
    ///</span> @return</span> The</span> implementation address for the specified version</span></span>
    function</span> getImplementation</span>(</span>bytes32</span> version</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
    </span></span>
    ///</span> @notice</span> Gets the current default version</span></span>
    ///</span> @return</span> The</span> current default version identifier</span></span>
    function</span> getDefaultVersion</span>(</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span>
    </span></span>
    ///</span> @notice</span> Gets all registered versions</span></span>
    ///</span> @return</span> An</span> array of all registered version identifiers</span></span>
    function</span> getVersions</span>(</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>[</span>]</span> memory</span>)</span>;</span></span>
    </span></span>
    ///</span> @notice</span> Executes a call to a specific implementation version</span></span>
    ///</span> @param</span> version</span> The version identifier of the implementation to call</span></span>
    ///</span> @param</span> data</span> The calldata to forward to the implementation</span></span>
    ///</span> @return</span> The</span> return data from the implementation call</span></span>
    function</span> executeAtVersion</span>(</span>bytes32</span> version</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> payable</span> returns</span> (</span>bytes</span> memory</span>)</span>;</span></span>
}</span></span></code></pre>Behavior Requirements</h3>

The proxy contract MUST maintain a mapping of version identifiers to implementation addresses.</li>
The proxy contract MUST maintain a default version that is used when no version is specified.</li>
When executeAtVersion</code> is called, the proxy MUST:

Verify the specified version exists</li>
Forward the call to the corresponding implementation</li>
Return any data returned by the implementation</li>
</ul>
</li>
The proxy contract MUST emit appropriate events when versions are registered, or when the default version changes.</li>
The proxy contract SHOULD implement access control for administrative functions (registering versions, setting default).</li>
The proxy contract MAY implement EIP-1967</a> storage slots for compatibility with existing tools.</li>
</ol>
Fallback Function</h3>
The proxy contract SHOULD implement a fallback function that forwards calls to the default implementation version when no version is specified. This maintains compatibility with traditional proxy patterns.</p>
Rationale</h2>
Version Identifiers as bytes32</h3>
Version identifiers are specified as bytes32</code> rather than semantic versioning strings to:</p>

Provide flexibility in versioning schemes</li>
Reduce gas costs for storage and comparison</li>
Allow for both string-based versions (converted to bytes32) and numeric versions</li>
Allow for storing a Git commit identifier in SHA-1 or SHA-256</li>
</ol>
Explicit Version Selection</h3>
The standard requires callers to explicitly select a version through executeAtVersion</code> rather than encoding version information in the call data to:</p>

Maintain a clean separation between version selection and function calls</li>
Avoid modifying existing function signatures</li>
Make version selection explicit and auditable</li>
</ol>
Registry Pattern</h3>
The registry pattern was chosen over alternatives like:</p>

Multiple Proxies</strong>: Having separate proxies for each version would increase deployment costs and complexity</li>
Version in Storage</strong>: Storing a single "current version" would not allow different callers to use different versions simultaneously</li>
</ol>
Default Version</h3>
The default version mechanism allows the proxy to maintain compatibility with traditional proxy patterns and supports callers that don't need to specify a version.</p>
Backwards Compatibility</h2>
This EIP is designed to enhance backward compatibility for smart contracts. It does not introduce any backward incompatibilities with existing Ethereum standards or implementations.</p>
Existing contracts that interact with proxy contracts can continue to do so without modification, as the fallback function will route calls to the default implementation.</p>
Security Considerations</h2>
This EIP is meant to significantly improve the security of the widely used proxy pattern.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


PermaLink Asset Bound Token
2025-04-01T00:00:00+00:00
Abstract</h2>
This standard introduces a subclass of tokens known as PermaLink Asset Bound Tokens (PermaLink-ABTs)</strong>. They are a specific implementation of the broader Asset Bound Token (ABT)</strong> concept. ABTs establish a novel ownership paradigm where an asset can own another asset</strong>, enabling composable, nested, and portfolio-like token structures that evolve together over time.</p>
PermaLink-ABTs implement a permanent binding mechanism where a token in one smart contract is irreversibly linked to a token in another contract. These links mirror key state data such as ownerOf</code>, tokenId</code>, totalSupply</code>, and balanceOf</code> using the assetBoundContract</code> interface. Traditional token transfer and approval functions are omitted to enforce immutability and structural cohesion between bound assets.</p>
Instead of utilizing a mint</code> function, PermaLink-ABTs employ a reveal</code> mechanism that activates tokens from a predefined supply. This approach enables permissionless binding and significantly reduces gas costs. A single token can have multiple PermaLink-ABTs bound to it, acting as multiple subordinate assets, forming a unified, transferable unit that simplifies asset mobility across digital identities, NFTs, and real-world assets (RWAs).</p>
By encouraging asset composability over competition, PermaLink-ABTs introduce a dynamic, future-proof model for on-chain asset evolution.</p>
Motivation</h2>
Traditional ownership models on Ethereum are inherently limited. Only externally owned accounts (EOAs) or smart contracts can own blockchain assets. This creates rigidity, especially as the blockchain ecosystem expands to include digital identities, tokenized real-world assets (RWAs), and NFTs. Current smart contracts are static in nature, meaning once deployed, they cannot adapt to evolving systems, unforeseen use cases, or new integration layers. There is a need for a more flexible and modular ownership model that allows for dynamic interactions between assets.</p>
This standard proposes Asset Bound Tokens (ABTs)</strong> as a solution to this challenge. ABTs allow one token to be permanently bound to another across contracts, creating a dynamic, flexible, and composable ownership model. By enabling tokens to move and evolve together, ABTs pave the way for new possibilities in the on-chain economy. The following use cases illustrate why ABTs are needed:</p>


On-Chain Identity Systems</strong>

Governments and institutions worldwide are piloting or implementing blockchain-based identity systems, digital passports, national IDs, and verifiable credentials such as with the ongoing European Blockchain Services Infrastructure (EBSI) initiatives. These systems often require credentials to be linked across multiple registries (e.g., healthcare, banking, voting). ABTs enable the binding of identity-linked tokens into a cohesive unit, so they move together instead of requiring manual coordination and transfers. This ensures that identity-linked assets remain interconnected and dynamic, making it easier to manage and update linked data as users interact with various systems.</p>
</li>

Real-World Asset (RWA) Ownership Structures</strong>

Tokenized businesses and assets (e.g., land, equipment, commodities) need flexible ownership models. These dynamic—businesses acquire, divest, and restructure their holdings and various assets. ABTs allow contracts to represent complex, evolving ownership hierarchies, where nested assets follow changes in their parent entity’s structure (e.g., a farming company acquiring new land or an IT firm merging with another and inheriting intellectual property). ABTs ensure businesses can efficiently manage and transfer assets on-chain without the constraints of rigid smart contracts.</p>
</li>

Manufacturing and Supply Chain Management</strong>

Supply chains involve multiple layers of assets: raw materials → parts → products → packaging → containers. Blockchain’s transparency is invaluable, but traditional methods of creating individual tokens or smart contracts for each stage are inefficient and costly. ABTs streamline this by linking tokens across the supply chain, allowing them to be aggregated when products are built up (e.g., shoes packed in boxes, boxes placed on pallets, pallets loaded into containers) and broken down as they move through different stages (e.g., containers unloaded, pallets split, boxes unpacked). This dynamic linking and unlinking reduce redundancy, maintain transparent immutable records, and ensure seamless tracking while minimizing gas costs. By enabling the efficient flow of assets throughout the supply chain, ABTs help reduce complexity and provide a cohesive, real-time view of the entire process.</p>
</li>

NFT Ecosystem Optimization</strong>

NFT projects often expand by launching secondary collections (e.g., additional editions, special releases). Without ABTs, this leads to fragmented value and user confusion as older and newer assets compete. ABTs allow new NFTs to be bound to originals, enhancing their value while maintaining a unified ecosystem. This strengthens liquidity and preserves market metrics, ensuring that the value of the original collection is retained and supported by the newer assets, thus benefiting both creators and collectors.</p>
</li>

New Opportunities for Creators</strong>

ABTs empower creators to build on top of existing assets permissionlessly without needing ownership of or permission from the original smart contract. This enables a new wave of creative expression, where artists can augment and enhance NFTs (e.g., adding new visuals, audio, or interactive layers) and collaborate on existing collections. Such contributions can generate new revenue streams through shared royalties, consignment, or collaborative upgrades. Owners benefit as well, since bound enhancements can increase the inherent value of their holdings, particularly in projects involving established creators or cross-collection collaborations.</p>
</li>
</ol>
In essence, ABTs introduce a framework where tokens are linked rather than owned. This allows for dynamic and evolving asset systems, where assets move together in harmony. If a binding token moves, all associated ABTs move with it, ensuring seamless updates and reducing the need for manual transfers. This innovation transforms traditional smart contracts from static repositories into living, evolving systems capable of adapting to changing use cases, technologies, and business models.</p>
The PermaLink-ABTs</strong> implementation takes the ABT model further by enforcing a permanent binding between one token and another—whether it's another ABT, NFT or NFKBT. This permanent binding ensures that tokens can be transferred as a single unit, reducing complexity and gas fees. Instead of relying on traditional minting, PermaLink-ABTs use a reveal</code> mechanism, activating tokens from a predefined supply. This reduces gas costs and encourages efficient linking of assets, enabling greater composability across multiple sectors.</p>
PermaLink-ABTs consolidate asset value by allowing multiple subordinate tokens to be linked to a single binding token, providing enhanced composability and reducing fragmentation. By requiring only the binding token to be transferred, all associated assets move in sync, making it easier to manage portfolios and move groups of assets together. This approach fosters collaboration, value accrual, and compatibility across ecosystems, whether for digital identities, RWAs, NFTs, or other on-chain assets.</p>
Specification</h2>
IERC7929</code> (Token Interface)</h3>
NOTES</strong>:</p>

The following specifications use syntax from Solidity 0.8.27</code> (or above)</li>
</ul>
interface</span> IERC7929</span> {</span></span>
    event</span> AssetBoundContractSet</span>(</span>address</span> assetBoundContract</span>)</span>;</span></span>
</span>
    function</span> ownerOf</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
    function</span> tokenExists</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
    function</span> totalSupply</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
    function</span> balanceOf</span>(</span>address</span> owner</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
}</span></span></code></pre>Events</h3>
AssetBoundContractSet</code> Event</h4>
Emitted when the contract is deployed and bound to assetBoundContract</code></p>
event</span> AssetBoundContractSet</span>(</span>address</span> assetBoundContract</span>)</span>;</span></span></code></pre>Functions</h3>
The functions detailed below MUST be implemented.</p>
ownerOf</code></h4>
Returns the owner of the NFT specified by the tokenId</code>. Will read from the assetBoundContract</code> the owner and return it.</p>
function</span> ownerOf</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span></code></pre>tokenExists</code></h4>
Returns true if the token read from the assetBoundContract</code> exists.
Tokens usually start existing when minted and stop existing when burned.</p>
function</span> tokenExists</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span></code></pre>totalSupply</code></h4>
Gets the total amount of tokens stored by the assetBoundContract</p>
function</span> totalSupply</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span></code></pre>balanceOf</code></h4>
Returns the number of NFTs in the assetBoundContract that an owner has.</p>
function</span> balanceOf</span>(</span>address</span> owner</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span></code></pre>IERC7929Reveal</code> (Optional Token Interface)</h3>
NOTES</strong>:</p>

The following specifications use syntax from Solidity 0.8.27</code> (or above)</li>
The Reveal extension is OPTIONAL for ERC-7929</a> contracts</li>
</ul>
interface</span> IERC7929Reveal</span> is</span> IERC7929</span> {</span></span>
    event</span> TokenRevealed</span>(</span>uint256</span> tokenId</span>)</span>;</span></span>
</span>
    function</span> reveal</span>(</span>uint256</span>[</span>]</span> calldata</span> tokenIds</span>)</span> external</span> payable</span>;</span></span>
}</span></span></code></pre>Events</h3>
TokenRevealed</code> Event</h4>
Emitted when the tokenId</code> is revealed</p>
event</span> TokenRevealed</span>(</span>uint256</span> tokenId</span>)</span>;</span></span></code></pre>Functions</h3>
The functions detailed below MUST be implemented.</p>
reveal</code></h3>
The reveal</code> function should be implemented to allow pre-allocated tokens to be activated on demand.

This method reduces gas consumption compared to traditional minting and simplifies token activation mechanics.</p>
function</span> reveal</span>(</span>uint256</span>[</span>]</span> calldata</span> tokenIds</span>)</span> external</span> payable</span>;</span></span></code></pre>Rationale</h2>
The design of PermaLink-ABTs centers around the goal of enabling permanent token binding while optimizing for gas efficiency, composability, and secure ownership structures. We adopted the assetBoundContract</code> interface to mirror essential metadata such as ownerOf</code>, tokenId</code>, totalSupply</code>, and balanceOf</code> from the binding token’s contract. This ensures that PermaLink-ABTs remain synchronized with the asset they are bound to, without duplicating logic or requiring manual updates. The mirroring also ensures traceability and visibility across contracts, allowing observers and off-chain systems to reliably interpret the token relationship. To preserve the permanent nature of the bond, standard transfer</code> and approve</code> methods are omitted. This immutability guarantees that PermaLink-ABTs cannot be separated from their bound asset once revealed. If the primary token moves, all attached PermaLink-ABTs move with it. This behavior supports composability, value aggregation, and consistent ownership logic.</p>
An alternative considered was allowing flexible transfer mechanics via opt-in transfer functions or whitelisting. However, this introduced unnecessary complexity and undermined the core principle of permanence. It also increased the risk of token desynchronization, accidental fragmentation, and security vulnerabilities in contract implementations. By contrast, the current design provides a simpler and more robust foundation.</p>
By implementing an optional</strong> reveal</code> function in place of a traditional mint</code> function it reduce gas costs and simplifies on-chain state changes for both the deployer and owner of the token having an ABT bound to it. Unlike minting, which creates tokens at runtime and incurs higher gas fees, the reveal</code> function maps pre-allocated tokens stored in an array or mapping. This allows tokens to be activated on demand without the overhead of dynamic token creation. As a result, token issuers can prepare and store an entire supply in advance, with users later revealing and binding tokens when needed. This approach aligns with the use case of portfolio binding and asset hierarchies, where large numbers of tokens may need to be activated and bound efficiently.</p>
PermaLink-ABTs enforce strict one-way binding with immutable relationships, making them especially suitable for use cases like identity systems, real-world asset (RWA) structures, and portfolio-locked NFTs. They act as permanently attached extensions to existing tokens, reducing complexity and avoiding redundant contract logic. This approach also provides a cleaner and more secure way to augment existing assets while maintaining compatibility across various blockchain use cases. This standard is intentionally minimal to ensure wide compatibility and flexibility. Developers can extend the base logic for specialized use cases, such as embedding royalty splits, upgrade paths, or linking to dynamic data feeds, without altering the underlying PermaLink mechanism.</p>
Reference Implementation</h2>
ERC7929</code> (Token implementation)</h3>
NOTES</strong>:</p>

The interface ID is (0x0b76916c</code>)</li>
Callers MUST handle false</code> from returns (bool success)</code>. Callers MUST NOT assume that false</code> is never returned!</li>
</ul>
contract</span> ERC7929</span> is</span> IERC165</span>, </span>ERC721Enumerable</span>, </span>Ownable</span>, </span>IERC7929</span> {</span></span>
    ERC721Enumerable </span>public</span> assetBoundContract</span>;</span></span>
</span>
    constructor</span>(</span></span>
        address</span> _assetBoundContract</span>,</span></span>
        string</span> memory</span> _name</span>,</span></span>
        string</span> memory</span> _symbol</span></span>
    )</span> ERC721</span>(</span>_name, _symbol) </span>{</span></span>
        assetBoundContract </span>=</span> ERC721Enumerable</span>(</span>_assetBoundContract</span>)</span>;</span></span>
</span>
        emit</span> AssetBoundContractSet</span>(</span>_assetBoundContract</span>)</span>;</span></span>
    }</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span> region EIP-165 Implementation</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
</span>
    /**</span></span>
     * </span>@dev</span> See {IERC165-supportsInterface}.</span></span>
     */</span></span>
    function</span> supportsInterface</span>(</span></span>
        bytes4</span> interfaceId</span></span>
    )</span> public</span> view</span> virtual</span> override</span>(</span>ERC721Enumerable</span>,</span> IERC165</span>)</span> returns</span> (</span>bool</span>)</span> {</span></span>
        return</span></span>
            interfaceId </span>==</span> type</span>(</span>IERC7929</span>)</span>.</span>interfaceId </span>||</span></span>
            super</span>.</span>supportsInterface</span>(</span>interfaceId</span>)</span>;</span></span>
    }</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span> endregion</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span> region Modifiers</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
</span>
    modifier</span> tokensMustExist</span>(</span>uint256</span>[</span>]</span> calldata</span> tokenIds</span>)</span> {</span></span>
        for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> tokenIds</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span>
            require</span>(</span>tokenExists</span>(</span>tokenIds</span>[</span>i</span>]</span>)</span>,</span> "ERC7929: Token does not exist"</span>)</span>;</span></span>
        }</span></span>
        _</span>;</span></span>
    }</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span> endregion Modifiers</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span> region mirror functions</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
</span>
    function</span> ownerOf</span>(</span></span>
        uint256</span> tokenId</span></span>
    )</span></span>
        public</span></span>
        view</span></span>
        virtual</span></span>
        override</span>(</span>ERC721</span>,</span> IERC7929</span>,</span> IERC721</span>)</span></span>
        returns</span> (</span>address</span>)</span></span>
    {</span></span>
        return</span> assetBoundContract</span>.</span>ownerOf</span>(</span>tokenId</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> tokenExists</span>(</span>uint256</span> tokenId</span>)</span> public</span> view</span> virtual</span> returns</span> (</span>bool</span>)</span> {</span></span>
        return</span> assetBoundContract</span>.</span>ownerOf</span>(</span>tokenId</span>)</span> !=</span> address</span>(</span>0</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> totalSupply</span>(</span>)</span></span>
        public</span></span>
        view</span></span>
        virtual</span></span>
        override</span>(</span>ERC721Enumerable</span>,</span> IERC7929</span>)</span></span>
        returns</span> (</span>uint256</span>)</span></span>
    {</span></span>
        return</span> assetBoundContract</span>.</span>totalSupply</span>(</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> balanceOf</span>(</span></span>
        address</span> owner</span></span>
    )</span></span>
        public</span></span>
        view</span></span>
        virtual</span></span>
        override</span>(</span>ERC721</span>,</span> IERC7929</span>,</span> IERC721</span>)</span></span>
        returns</span> (</span>uint256</span>)</span></span>
    {</span></span>
        return</span> assetBoundContract</span>.</span>balanceOf</span>(</span>owner</span>)</span>;</span></span>
    }</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span>endregion</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span>region Disabling approve and transfer functions to prevent transfers of ABT tokens</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
</span>
    function</span> approve</span>(</span>address</span>,</span> uint256</span>)</span> public</span> pure</span> override</span>(</span>ERC721</span>,</span> IERC721</span>)</span> {</span></span>
        revert</span>(</span>"ERC7929: Approvals not allowed"</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> setApprovalForAll</span>(</span></span>
        address</span>,</span></span>
        bool</span></span>
    )</span> public</span> pure</span> override</span>(</span>ERC721</span>,</span> IERC721</span>)</span> {</span></span>
        revert</span>(</span>"ERC7929: Approvals not allowed"</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> transferFrom</span>(</span></span>
        address</span>,</span></span>
        address</span>,</span></span>
        uint256</span></span>
    )</span> public</span> pure</span> override</span>(</span>ERC721</span>,</span> IERC721</span>)</span> {</span></span>
        revert</span>(</span>"ERC7929: Transfers not allowed"</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> safeTransferFrom</span>(</span></span>
        address</span>,</span></span>
        address</span>,</span></span>
        uint256</span></span>
    )</span> public</span> pure</span> override</span>(</span>ERC721</span>,</span> IERC721</span>)</span> {</span></span>
        safeTransferFrom</span>(</span>address</span>(</span>0</span>)</span>,</span> address</span>(</span>0</span>)</span>,</span> 0</span>,</span> ""</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> safeTransferFrom</span>(</span></span>
        address</span>,</span></span>
        address</span>,</span></span>
        uint256</span>,</span></span>
        bytes</span> memory</span></span>
    )</span> public</span> pure</span> override</span>(</span>ERC721</span>,</span> IERC721</span>)</span> {</span></span>
        revert</span>(</span>"ERC7929: Transfers not allowed"</span>)</span>;</span></span>
    }</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span>endregion</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
}</span></span></code></pre>IERC7929Reveal</code> (Token implementation)</h3>
NOTES</strong>:</p>

This is an OPTIONAL extension for ERC-7929</a> contracts</li>
The interface ID is (0xb93f208a</code>)</li>
Callers MUST handle false</code> from returns (bool success)</code>. Callers MUST NOT assume that false</code> is never returned!</li>
</ul>
contract</span> ERC7929Reveal</span> is</span> ERC7929</span>, </span>IERC7929Reveal</span> {</span></span>
    mapping</span>(</span>uint256</span> =></span> bool</span>)</span> public</span> isRevealed</span>;</span></span>
</span>
    constructor</span>(</span></span>
        address</span> _assetBoundContract</span>,</span></span>
        string</span> memory</span> _name</span>,</span></span>
        string</span> memory</span> _symbol</span></span>
    )</span> ERC7929</span>(</span>_assetBoundContract, _name, _symbol) </span>{</span>}</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span> region EIP-165 Implementation</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
</span>
    /**</span></span>
     * </span>@dev</span> See {IERC165-supportsInterface}.</span></span>
     */</span></span>
    function</span> supportsInterface</span>(</span></span>
        bytes4</span> interfaceId</span></span>
    )</span> public</span> view</span> virtual</span> override</span> returns</span> (</span>bool</span>)</span> {</span></span>
        return</span></span>
            interfaceId </span>==</span> type</span>(</span>IERC7929Reveal</span>)</span>.</span>interfaceId </span>||</span></span>
            super</span>.</span>supportsInterface</span>(</span>interfaceId</span>)</span>;</span></span>
    }</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span> endregion</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span> region Modifiers</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
</span>
    modifier</span> tokensMustNotBeRevealed</span>(</span>uint256</span>[</span>]</span> calldata</span> tokenIds</span>)</span> {</span></span>
        for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> tokenIds</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span>
            require</span>(</span></span>
                !</span>isRevealed</span>[</span>tokenIds</span>[</span>i</span>]</span>]</span>,</span></span>
                "ERC7929: Token already revealed"</span></span>
            )</span>;</span></span>
        }</span></span>
        _</span>;</span></span>
    }</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span> endregion Modifiers</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span> region mirror functions</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
</span>
    function</span> ownerOf</span>(</span></span>
        uint256</span> tokenId</span></span>
    )</span> public</span> view</span> override</span>(</span>ERC7929</span>,</span> IERC7929</span>)</span> returns</span> (</span>address</span>)</span> {</span></span>
        return</span> super</span>.</span>ownerOf</span>(</span>tokenId</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> tokenExists</span>(</span></span>
        uint256</span> tokenId</span></span>
    )</span> public</span> view</span> override</span>(</span>ERC7929</span>,</span> IERC7929</span>)</span> returns</span> (</span>bool</span>)</span> {</span></span>
        return</span> super</span>.</span>tokenExists</span>(</span>tokenId</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> totalSupply</span>(</span>)</span></span>
        public</span></span>
        view</span></span>
        override</span>(</span>ERC7929</span>,</span> IERC7929</span>)</span></span>
        returns</span> (</span>uint256</span>)</span></span>
    {</span></span>
        return</span> super</span>.</span>totalSupply</span>(</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> balanceOf</span>(</span></span>
        address</span> owner</span></span>
    )</span> public</span> view</span> override</span>(</span>ERC7929</span>,</span> IERC7929</span>)</span> returns</span> (</span>uint256</span>)</span> {</span></span>
        return</span> super</span>.</span>balanceOf</span>(</span>owner</span>)</span>;</span></span>
    }</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span>endregion</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span>region Reveal function to reveal the token URI for a given token ID(s)</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
</span>
    function</span> reveal</span>(</span></span>
        uint256</span>[</span>]</span> calldata</span> tokenIds</span></span>
    )</span></span>
        public</span></span>
        payable</span></span>
        virtual</span></span>
        tokensMustExist</span>(</span>tokenIds</span>)</span></span>
        tokensMustNotBeRevealed</span>(</span>tokenIds</span>)</span></span>
    {</span></span>
        for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> tokenIds</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span>
            isRevealed</span>[</span>tokenIds</span>[</span>i</span>]</span>]</span> =</span> true</span>;</span></span>
            emit</span> TokenRevealed</span>(</span>tokenIds</span>[</span>i</span>]</span>)</span>;</span></span>
        }</span></span>
    }</span></span>
</span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
    //</span>endregion</span></span>
    ///</span>////////////////////////////////////////////////////////////</span></span>
}</span>    </span></span></code></pre>Security Considerations</h2>
PermaLink-ABTs are linked to another non-fungible token. If an individual loses access to this token, what we call the binding token</strong>, they also lose access to all PermaLink-ABTs that have been bound to it. This introduces a critical security consideration: the entire value of bound assets depends on the integrity and availability of the binding token.</p>
To mitigate this risk, we strongly recommend the use of standards like ERC-6809</a>, a Non-Fungible Key Bound Token</strong>, which introduces on-chain two-factor authentication (2FA). ERC-6809 allows a user to bind sensitive tokens (like PermaLink-ABTs) to a secured identity layer, complete with recovery mechanisms. In the event that a user loses access to their original wallet or interacts with a malicious contract, ERC-6809 provides a safeFallback function to re-establish control.</p>
In essence, all of the security guarantees of ERC-6809 extend to any PermaLink-ABTs bound to it. This layered security model not only protects against loss but also ensures recoverability and long-term viability for high-value bound assets. It is strongly encouraged that developers implementing PermaLink-ABTs integrate this or similar standards to provide a robust security foundation for users.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Signature Verifiers
2025-03-21T00:00:00+00:00
Abstract</h2>
Externally Owned Accounts (EOA) can sign messages with their associated private keys. Additionally ERC-1271</a> defines a method for signature verification by smart accounts such as multisig. In both cases the identity of the signer is an ethereum address. We propose a standard to extend this concept of signer description, and signature verification, to keys that do not have an ethereum identity of their own, in the sense that they don't have their own address to represent them.</p>
This new mechanism can be used to integrate new signers such as non-ethereum cryptographic curves, hardware devices, or even email addresses. This is particularly relevant when dealing with things like social-recovery of smart accounts.</p>
Motivation</h2>
With the development of account abstraction, there is an increasing need for non-ethereum signature verification. Cryptographic algorithms besides the natively supported secp256k1 are being used for controlling smart accounts. In particular, curves such as secp256r1 (supported by many mobile devices) and RSA keys (that are distributed by traditional institutions) are widely available. Beyond these two examples, we also see the emergence of ZK solutions for signing with emails or JWT from big Web2 services.</p>
All these signature mechanisms have one thing in common: they do not have a canonical ethereum address to represent them onchain. While users could deploy ERC-1271 compatible contracts for each key individually, this would be cumbersome and expensive. As account abstraction tries to separate account addresses (that hold assets) from the key that controls them, giving fixed on-chain addresses to keys (and possibly sending assets to these addresses by mistake) is not the right approach. Instead, using a small number of verifier contracts that can process signatures in a standard way, and having the accounts rely on these verifiers, feels like the correct approach. This has the advantage that once the verifier is deployed, any key can be represented using a (verifier, key)</code> pair without requiring any setup cost.</p>
The (verifier, key)</code> pairs can be given permission to control a smart account, perform social recovery, or do any other operation without ever having a dedicated on-chain address. Systems that want to adopt this approach need to transition away from the model where signers are identified by their address to a new model where signers may not have an address, and are identified by a bytes</code> object.</p>
This definition is backward compatible with EOA and ERC-1271 contracts: in that case, we use the address of the identity (EOA or contract) as the verifier and the key is empty.</p>
Specification</h2>
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.</p>
Nomenclature</h3>

Keys are represented using bytes</code> objects of arbitrary length. For example a P256 or RSA public key. Keys MUST NOT be empty.</li>
Verifiers are smart contracts in charge of signature verification for a given type of key. They have an ethereum address.</li>
</ul>
Signature Verifier interface</h3>
Verifiers MUST implement the following interface:</p>
interface</span> IERC7913SignatureVerifier</span> {</span></span>
  /**</span></span>
   * </span>@dev</span> Verifies `signature` as a valid signature of `hash` by `key`.</span></span>
   *</span></span>
   * MUST return the bytes4 magic value 0x024ad318 (IERC7913SignatureVerifier.verify.selector) if the signature is valid.</span></span>
   * SHOULD return 0xffffffff or revert if the signature is not valid.</span></span>
   * SHOULD return 0xffffffff or revert if the key is empty</span></span>
   */</span></span>
  function</span> verify</span>(</span>bytes</span> calldata</span> key</span>,</span> bytes32</span> hash</span>,</span> bytes</span> calldata</span> signature</span>)</span> external</span> view</span> returns</span> (</span>bytes4</span>)</span>;</span></span>
}</span></span></code></pre>
Verifiers SHOULD be stateless.</p>
Rationale</h2>
Verifiers can be used to avoid deploying many ERC-1271 "identity contract" (one per key), which would be expensive. Using this model, new keys can be used without any deployment costs.</p>
ERC-1271 already covers the cases were a key is not necessary. To avoid ambiguity, the verifiers contracts should not support (or be expected to support) empty keys. Signers that are 20 bytes long (empty key) should be handled using ERC-1271.</p>
Consistency with existing systems (ecrecover and ERC-1271) requires the message to be bytes32</code> hash. These are usually produced following ERC-191</a> or ERC-712</a>. Cryptographic systems that use different hashing methods SHOULD see this hash as a message, and possibly rehash it following the relevant standards.</p>
Backwards Compatibility</h2>
A system can support ERC-7913</a> signers alongside EOAs and ERC-1271 in the following way.</p>
A signer is a bytes</code> object that is the concatenation of an address and optionally a key: verifier || key</code>. A signer is at least 20 bytes long.</p>
Given a signer signer</code>, a message hash hash</code>, and a signature sign</code>, verification is done as follows:</p>

if signer.length < 20</code>: verification fails;</li>
split signer</code> into (verifier, key)</code> with verifier</code> being the first 20 bytes and key</code> being the rest (potentially empty)</li>
if key</code> is empty, then consider that verifier</code> is the identity.

verification is done using ERC-1271's isValidSignature if there is code at verifier</code> address, or ecrecover otherwise</li>
</ul>
</li>
if key</code> is not empty, call IERC7913SignatureVerifier(verifier).verify(key, hash, signature)</code>

if the return value is the expected magic value (0x024ad318</code>) then verification is successful,</li>
otherwise, verification fails.</li>
</ul>
</li>
</ul>
Reference Implementation</h2>
In solidity, signature verification could be implemented in the following library:</p>
import</span> {</span>SignatureChecker</span>}</span> from</span> '@openzeppelin/contracts/utils/cryptography/SignatureChecker.sol'</span>;</span></span>
</span>
///</span> @dev</span> Extention of openzeppelin's SignatureChecker library</span></span>
library</span> SignatureCheckerExtended</span> {</span></span>
  function</span> isValidSignatureNow</span>(</span>bytes</span> calldata</span> signer</span>,</span> bytes32</span> hash</span>,</span> bytes</span> memory</span> signature</span>)</span> internal</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span>
      if</span> (</span>signer</span>.</span>length </span><</span> 20</span> )</span> {</span></span>
        return</span> false</span>;</span></span>
      }</span> else</span> if</span> (</span>signer</span>.</span>length </span>==</span> 20</span>)</span> {</span></span>
        return</span> SignatureChecker</span>.</span>isValidSignatureNow</span>(</span>address</span>(</span>bytes20</span>(</span>signer</span>)</span>)</span>,</span> hash</span>,</span> signature</span>)</span>;</span></span>
      }</span> else</span> {</span></span>
        try</span> IERC7913SignatureVerifier</span>(</span>address</span>(</span>bytes20</span>(</span>signer</span>[</span>0</span>:</span>20</span>]</span>)</span>)</span>)</span>.</span>verify</span>(</span>signer</span>[</span>20</span>:</span>]</span>,</span> hash</span>,</span> signature</span>)</span> returns</span> (</span>bytes4</span> magic</span>)</span> {</span></span>
          return</span> magic </span>==</span> IERC7913SignatureVerifier</span>.</span>verify</span>.</span>selector</span>;</span></span>
        }</span> catch</span> {</span></span>
          return</span> false</span>;</span></span>
        }</span></span>
      }</span></span>
  }</span></span>
}</span></span></code></pre>Security Considerations</h2>
Signer may be used for anything from smart account session key (with a short lifetime of a few hours/days) to social recovery "guardians" that may only be used several years after they are setup. In order to ensure that these signers remain valid "in perpetuity", the verifier contract should be trustless. This means that the verifiers should not be upgradeable contracts.</p>
Verifiers should also not depend on any value that can be modified after deployment. In solidity terms, the verify</code> function should be pure. Any parameters that are involved in signature verification should either be part of the key, or part of immutable code of the verifier. Using immutable</code> variable (in solidity) would be safe. The stateless aspect of the verifier also ensure compliance (of the verifier) with ERC-7562</a> scope rules.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Composite EIP-712 Signatures
2025-03-20T00:00:00+00:00
Abstract</h2>
This ERC provides a standard for signing multiple typed-data messages with a single signature by encoding them into a Merkle tree. This allows components to independently verify messages, without requiring full knowledge of the others. It provides a significant UX improvement by reducing the number of signature prompts to one, while preserving the security and flexibility of the EIP-712</a> standard.</p>
This ERC also gives applications the flexibility to verify messages in isolation, or in aggregate. This opens up new verification modalities: for e.g, an application can require that message (x</code>) is only valid when signed in combination message (y</code>).</p>
Motivation</h2>
As the ecosystem moves towards ETH-less transactions, users are often required to sign multiple off-chain messages in quick succession. Typically, a first signature is needed for a precise spend allowance (via Permit2, ERC-2612</a>, etc.), followed by subsequent messages to direct the use of funds. This creates a frictional user experience as each signature requires a separate wallet interaction and creates confusion about what, in aggregate, is being approved.</p>
Current solutions have significant drawbacks:</p>

Pre-approving ERC-20</a> allowance:</strong> spend creates security vulnerabilities</li>
Merging multiple messages into a single message:</strong> prevents independent verifiability. Each message cannot be verified without knowledge of the entire batch</li>
Separate signature requests:</strong> creates friction in the user experience</li>
</ul>
This ERC has the following objectives:</p>
Single Signature</h3>
A single signature should cover multiple messages</p>
Isolated Verification</h3>
Messages should be independently verifiable without knowledge of others</p>
Human-readable</h3>
Readability benefits of EIP-712 should be preserved. Giving wallets and users insight into what is being signed.</p>
Specification</h2>
Overview</h3>
The composite signature scheme uses a Merkle tree to hash multiple typed-data data messages together under a single root. The user signs only the Merkle root. The process is described below.</p>
Generating a Composite Signature</h3>


For a set of messages [m₁, m₂, ..., mₙ]</code>, encode each using EIP-712's encode</code> and compute its hash:</p>
hashₙ = keccak256(encode(mₙ))</span></span></code></pre></li>

Use these message hashes as leaf nodes in a Merkle tree and compute a merkleRoot</code></p>
</li>

Sign the merkle root.</p>
signature = sign(merkleRoot)</span></span></code></pre></li>
</ol>
Verification Process</h3>
To verify that an individual message mₓ</code> was included in a composite signature:</p>


Verify the signature on the merkleRoot</code>:</p>
recoveredSigner = ecrecover(merkleRoot, signature)</span></span>
isValidSignature = (recoveredSigner == expectedSigner)</span></span></code></pre></li>

Compute the leaf node for message mₓ</code> and verify its path to the Merkle root, using the proof:</p>
leaf = keccak256(encode(mₓ))</span></span>
isValidProof = _verifyMerkleProof(leaf, merkleProof, merkleRoot)</span></span></code></pre></li>
</ol>
Where _verifyMerkleProof()</code> is defined as:</p>
function</span> _verifyMerkleProof</span>(</span></span>
   bytes32</span> leaf</span>,</span></span>
   bytes32</span>[</span>]</span> calldata</span> proof</span>,</span></span>
   bytes32</span> merkleRoot</span></span>
)</span> internal</span> pure</span> returns</span> (</span>bool</span>)</span> {</span></span>
   bytes32</span> computedRoot </span>=</span> leaf</span>;</span></span>
   for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> proof</span>.</span>length</span>;</span> +</span>+</span>i</span>)</span> {</span></span>
       if</span> (</span>computedRoot </span><</span> proof</span>[</span>i</span>]</span>)</span> {</span></span>
           computedRoot </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>computedRoot</span>,</span> proof</span>[</span>i</span>]</span>)</span>)</span>;</span></span>
       }</span> else</span> {</span></span>
           computedRoot </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>proof</span>[</span>i</span>]</span>,</span> computedRoot</span>)</span>)</span>;</span></span>
       }</span></span>
   }</span></span>
</span>
   return</span> computedRoot </span>==</span> merkleRoot</span>;</span></span>
}</span></span></code></pre>
The message is verified if and only if (1) and (2) succeed.</p>
isVerified = isValidSignature && isValidProof</span></span></code></pre>Specification of eth_signTypedData_v5</code> JSON RPC method.</h3>
This ERC adds a new method eth_signTypedData_v5</code> to Ethereum JSON-RPC. This method allows signing multiple typed data messages with a single signature using the specification described above. The signing account must be prior unlocked.</p>
This method returns: the signature, merkle root, and an array of proofs (each corresponding to an input message).</p>
Parameters</h4>

Address</code> - Signing account</li>
TypedData | TypedDataArray</code> - A single TypedData object or Array of TypedData</code> objects from EIP-712.</li>
</ol>
Returns</h5>
{</span></span>
  signature</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>;</span> //</span> Hex encoded 65 byte signature (same format as eth_sign)</span></span>
  merkleRoot</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>;</span> //</span> 32 byte Merkle root as hex string</span></span>
  proofs</span>:</span> Array</span><</span>Array</span><</span>`</span>0x</span>${</span>string</span>}</span>`</span>>></span>;</span> //</span> Array of Merkle proofs (one for each input message)</span></span>
}</span></span></code></pre>Example</h5>
Request:</p>
{</span></span>
  "</span>jsonrpc</span>"</span>:</span> "</span>2.0</span>"</span>,</span></span>
  "</span>method</span>"</span>:</span> "</span>eth_signTypedData_v5</span>"</span>,</span></span>
  "</span>params</span>"</span>:</span> [</span></span>
    "</span>0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826</span>"</span>,</span></span>
    [</span></span>
      {</span></span>
        "</span>types</span>"</span>:</span> {</span></span>
          "</span>EIP712Domain</span>"</span>:</span> [</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>name</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>string</span>"</span></span>
            }</span>,</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>version</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>string</span>"</span></span>
            }</span>,</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>chainId</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>uint256</span>"</span></span>
            }</span>,</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>verifyingContract</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>address</span>"</span></span>
            }</span></span>
          ]</span>,</span></span>
          "</span>Person</span>"</span>:</span> [</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>name</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>string</span>"</span></span>
            }</span>,</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>wallet</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>address</span>"</span></span>
            }</span></span>
          ]</span>,</span></span>
          "</span>Mail</span>"</span>:</span> [</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>from</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>Person</span>"</span></span>
            }</span>,</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>to</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>Person</span>"</span></span>
            }</span>,</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>contents</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>string</span>"</span></span>
            }</span></span>
          ]</span></span>
        }</span>,</span></span>
        "</span>primaryType</span>"</span>:</span> "</span>Mail</span>"</span>,</span></span>
        "</span>domain</span>"</span>:</span> {</span></span>
          "</span>name</span>"</span>:</span> "</span>Ether Mail</span>"</span>,</span></span>
          "</span>version</span>"</span>:</span> "</span>1</span>"</span>,</span></span>
          "</span>chainId</span>"</span>:</span> 1</span>,</span></span>
          "</span>verifyingContract</span>"</span>:</span> "</span>0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC</span>"</span></span>
        }</span>,</span></span>
        "</span>message</span>"</span>:</span> {</span></span>
          "</span>from</span>"</span>:</span> {</span></span>
            "</span>name</span>"</span>:</span> "</span>Cow</span>"</span>,</span></span>
            "</span>wallet</span>"</span>:</span> "</span>0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826</span>"</span></span>
          }</span>,</span></span>
          "</span>to</span>"</span>:</span> {</span></span>
            "</span>name</span>"</span>:</span> "</span>Bob</span>"</span>,</span></span>
            "</span>wallet</span>"</span>:</span> "</span>0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB</span>"</span></span>
          }</span>,</span></span>
          "</span>contents</span>"</span>:</span> "</span>Hello, Bob!</span>"</span></span>
        }</span></span>
      }</span>,</span></span>
      {</span></span>
        "</span>types</span>"</span>:</span> {</span></span>
          "</span>EIP712Domain</span>"</span>:</span> [</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>name</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>string</span>"</span></span>
            }</span>,</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>version</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>string</span>"</span></span>
            }</span>,</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>chainId</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>uint256</span>"</span></span>
            }</span>,</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>verifyingContract</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>address</span>"</span></span>
            }</span></span>
          ]</span>,</span></span>
          "</span>Transfer</span>"</span>:</span> [</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>amount</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>uint256</span>"</span></span>
            }</span>,</span></span>
            {</span></span>
              "</span>name</span>"</span>:</span> "</span>recipient</span>"</span>,</span></span>
              "</span>type</span>"</span>:</span> "</span>address</span>"</span></span>
            }</span></span>
          ]</span></span>
        }</span>,</span></span>
        "</span>primaryType</span>"</span>:</span> "</span>Transfer</span>"</span>,</span></span>
        "</span>domain</span>"</span>:</span> {</span></span>
          "</span>name</span>"</span>:</span> "</span>Ether Mail</span>"</span>,</span></span>
          "</span>version</span>"</span>:</span> "</span>1</span>"</span>,</span></span>
          "</span>chainId</span>"</span>:</span> 1</span>,</span></span>
          "</span>verifyingContract</span>"</span>:</span> "</span>0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC</span>"</span></span>
        }</span>,</span></span>
        "</span>message</span>"</span>:</span> {</span></span>
          "</span>amount</span>"</span>:</span> "</span>1000000000000000000</span>"</span>,</span></span>
          "</span>recipient</span>"</span>:</span> "</span>0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB</span>"</span></span>
        }</span></span>
      }</span></span>
    ]</span></span>
  ]</span>,</span></span>
  "</span>id</span>"</span>:</span> 1</span></span>
}</span></span></code></pre>
Result:</p>
{</span></span>
  "</span>id</span>"</span>: </span>1</span>,</span></span>
  "</span>jsonrpc</span>"</span>: </span>"</span>2.0</span>"</span>,</span></span>
  "</span>result</span>"</span>:</span> {</span></span>
    "</span>signature</span>"</span>:</span> "</span>0x4355c47d63924e8a72e509b65029052eb6c299d53a04e167c5775fd466751c9d07299936d304c153f6443dfa05f40ff007d72911b6f72307f996231605b915621c</span>"</span>,</span></span>
    "</span>merkleRoot</span>"</span>:</span> "</span>0x7de103665e21d6c9d9f82ae59675443bd895ed42b571c7f952c2fdc1a5b6e8d2</span>"</span>,</span></span>
    "</span>proofs</span>"</span>:</span> [</span></span>
      [</span>"</span>0x4bdbac3830d492ac3f4b0ef674786940fb33481b32392e88edafd45d507429f2</span>"</span>]</span>,</span></span>
      [</span>"</span>0x95be87f8abefcddc8116061a06b18906f32298a4644882d06baff852164858c6</span>"</span>]</span></span>
    ]</span></span>
  }</span></span>
}</span></span></code></pre>Rationale</h2>
The choice of using a Merkle tree to bundle messages provides the following additional benefits:</p>
Efficient verification on-chain</h3>
_verifyMerkleProof</code> has a runtime of O(log2(N))</code> where N is the number of messages that were signed.</p>
Flexible Verification Modes</h3>
Applications can require combination of messages be signed together to enhance security.</p>
N=1</code> backwards compatibility</h3>
Merkle signature for single message bundles are equal to eth_signTypedData_v4</code>. Requiring no onchain changes.</p>
Backwards Compatibility</h2>
When the number of message is one, eth_signTypedData_v5</code> produces the same signature as eth_signTypedData_v4</code> since merkleRoot == keccak256(encode(message))</code>. This allows eth_signTypedData_v5</code> to be a drop-in replacement for eth_signTypedData_v4</code> with no changes to on-chain verification.</p>
Reference Implementation</h2>
eth_signTypedData_v5</code></h3>
Reference implementation of eth_signTypedData_v5</code> can be found the assets directory</a>.</p>
Verifier</h3>
Solidity implementation of a onchain verifier can be found the assets directory</a>.</p>
Merkle</h3>
Reference Merkle tree can be found in the assets directory</a>.</p>
Security Considerations</h2>
Replay Protection</h3>
This ERC focuses on generating composite messages and verifying their signatures. It does not contain mechanisms to prevent replays. Developers must</strong> ensure their applications can handle receiving the same message twice.</p>
Partial Message Verification</h3>
During verification, care must</strong> be taken to ensure that both</strong> of these checks pass:</p>

EIP-712 signature on the Merkle root is valid</li>
Merkle proof is valid against the root</li>
</ol>
User Understanding</h3>
Wallets must</strong> communicate to users that they are signing multiple messages at once. Wallets must</strong> display of all message types before signing.</p>
To ensure batch signature requests are digestible, it is recommended to limit the maximum number of messages to 10.</p>
Merkle Tree Construction</h3>
Merkle tree should be constructed in a consistent manner.</p>

The hashing function must</strong> be keccak256</code></li>
To ensure predictable/consistent proof sizes, implementations must</strong> pad leaves with zero hashes to reach next power of two to ensure balance. Let n</code> be the number of messages. Before constructing the tree, compute the smallest k</code> such that 2^(k-1) < n ≤ 2^k</code>. Insert zero hashes into the list of messages until list of messages is equal to 2^k</code>.</li>
To ensure an implicit verification path, pairs must</strong> be sorted lexicographically before constructing parent hash.</li>
</ol>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


HD wallet In Treasury Management
2025-03-07T00:00:00+00:00
Abstract</h2>
This proposal aims to provide a standardized method for on-chain treasury management of institutional assets, ensuring secure private key generation, hierarchical management, and departmental permission isolation while supporting asset security and transaction efficiency in multi-chain environments. By defining a unified derivation path and security mechanisms, this proposal offers an efficient and secure solution for treasury management.</p>
Motivation</h2>
With the rapid development of blockchain and DeFi, secure management of on-chain assets has become critical. Traditional private key management struggles to meet the security demands of large organizations in complex scenarios, where hierarchical key management, permission controls, and multi-signature mechanisms are essential. This proposal provides a standardized solution for institutional treasury management, ensuring asset security and transaction efficiency.</p>
Specification</h2>
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</a> and RFC 8174</a>.</p>
Derivation Path</h3>
For secure on-chain treasury account key management, implementations MUST use the following hierarchical
deterministic (HD) path:</p>
m/44'/60'/entity_id' / department_id' / account_index</span></span></code></pre>
Path Components:</p>


Master Key (</strong>m</code>)</strong></p>

SHALL represent the root HD wallet private key.</li>
</ul>
</li>

BIP 44</a> Compliance Layer (44'</code>)</strong></p>

MUST use 44'</code> (hardened) to indicate BIP 44 compliance.</li>
</ul>
</li>

Coin Type Layer ( 60'</code> )</strong></p>

SHALL use 60'</code> (hardened) for Ethereum and EVM-compatible chains.</li>
</ul>
</li>

Entity Identifier ( entity_id'</code></strong>)</p>

MUST be derived by hashing the subsidiary name into a hardened index.</li>
MUST NOT reuse the same entity_id'</code> across distinct subsidiaries.</li>
</ul>
</li>

Department Identifier (</strong>department_id'</code>)</strong></p>

SHALL be derived by hashing the department name into a hardened index.</li>
MUST isolate keys between departments via hardened derivation.</li>
</ul>
</li>

Account Index (</strong>account_index</code>)</strong></p>

MUST use non-hardened derivation to allow unified account management.</li>
</ul>
</li>
</ol>
Note on BIP 44 Adaptation</strong>:</p>

The BIP 44 change</code> layer SHOULD be omitted for Ethereum/EVMs due to their account model (not UTXO).</li>
</ul>
Hash Conversion</h3>
To derive entity_id</code> and department_id</code>:</p>


Entity Index Calculation</strong></p>

SHALL compute entity_id</code> as:</li>
</ul>
</li>
</ol>
entity_hash</span> =</span> sha256</span>(</span>f</span>"</span>ENTITY:</span>{</span>entity</span>}</span>"</span>.</span>encode</span>(</span>)</span>)</span>.</span>digest</span>(</span>)</span>  </span></span>
entity_index</span> =</span> int</span>.</span>from_bytes</span>(</span>entity_hash</span>[</span>:</span>4</span>]</span>,</span> "</span>big</span>"</span>)</span> |</span> 0x</span>80000000</span>   #</span> 2^31 ≤ index < 2^32</span></span></code></pre>


Department Index Calculation</strong></p>

MUST compute department_id</code> as:</li>
</ul>
</li>
</ol>
dept_hash</span> =</span> sha256</span>(</span>f</span>"</span>DEPT:</span>{</span>entity_hash</span>}</span>:</span>{</span>department</span>}</span>"</span>.</span>encode</span>(</span>)</span>)</span>.</span>digest</span>(</span>)</span>  </span></span>
dept_index</span> =</span> int</span>.</span>from_bytes</span>(</span>dept_hash</span>[</span>:</span>4</span>]</span>,</span> "</span>big</span>"</span>)</span> |</span> 0x</span>80000000</span>   #</span> 2^31 ≤ index < 2^32</span></span></code></pre>


Output Constraints</strong></p>

Generated indices MUST be integers in [2^31, 2^32-1]</code> to enforce hardened derivation.</li>
</ul>
</li>
</ol>
Extended Path for Role-Based Access</h3>
For finer access control (e.g., roles within departments):</p>
m/60'/entity_id' / department_id' /role_id'/ account_index</span></span></code></pre>


Role Identifier (</strong>role_id'</code>)</strong></p>

SHOULD use hardened derivation to isolate role-specific keys.</li>
</ul>
</li>
</ol>
Compatibility Note</strong>:</p>

Omitting the 44'</code> layer MAY cause incompatibility with standard wallets (e.g., MetaMask).</li>
Integrations with such wallets MUST implement custom plugins to handle this deviation.</li>
</ul>
Simplified Path for Smaller Entities</h3>
For entities without subsidiaries:</p>
m/44'/60' / department_id' /0/ account_index</span></span></code></pre>
Compatibility Guarantee</strong></p>

This structure SHOULD ensure compatibility with mainstream BIP 44 wallets.</li>
</ul>
Key Derivation Algorithm</h3>
Implementations MUST adhere to:</p>
E = Map<entity, List<Department>></span></span>
n = Layer2 curve order</span></span>
path = m/44'/60'/entity_id' / department_id' / account_index</span></span>
BIP32() = Official BIP-0032 derivation function on secp256k1</span></span>
hash = SHA256</span></span>
root_key = BIP32(path)</span></span>
for each E:</span></span>
	key = hash(root_key|hierarchical_hash_to_index(entity,department))</span></span>
	return key</span></span></code></pre>
Cryptographic Requirements</strong>:</p>

SHALL use BIP 32</a> with secp256k1</code> for HD derivation.</li>
MUST concatenate hashes with root keys to prevent cross-layer key leakage.</li>
</ul>
Compatibility Considerations</strong></h3>
This specification is inspired by BIP 44 (m/purpose'/coin_type'/account'/change/address_index</code>), but:</p>

SHALL NOT use the change</code> layer for Ethereum-based systems.</li>
MAY extend the hierarchy beyond BIP 44’s 5-layer structure for organizational needs.</li>
</ul>
Rationale</h2>
The scenarios for which the proposal applies are:</p>

Company and Department Isolation</strong>: Different subsidiaries within the group, as well as different departments within each subsidiary, can create isolated on-chain accounts. Enhanced derivation is used to isolate exposure risks.</li>
Group Unified Management Authority</strong>: The group administrator holds the master private key, which can derive all subsidiary private keys, granting the highest authority to view and initiate transactions across the entire group, facilitating unified management by the group administrator.</li>
Shared Department Private Key</strong>: If subsidiary A's administrator, Alice, needs to share accounts under subsidiary A with a new administrator, Bob, she only needs to share the master private key of subsidiary A. Accounts from various departments can then be derived from this key.</li>
Shared Audit Public Key</strong>: If the audit department needs to audit transactions under a specific department, the extended public key of the specified department can be shared with the audit department. Through this extended public key, all subordinate public keys under the department can be derived, allowing the audit department to track all transactions associated with these public key addresses.</li>
</ol>
Backwards Compatibility</h2>
This standard complies with BIP 39, BIP 32, and BIP 44.</p>
Reference Implementation</h2>
"""</span></span>
Secure Treasury Management System</span></span>
Enterprise-grade hierarchical deterministic wallet implementation compliant with BIP-44</span></span>
"""</span></span>
</span>
import</span> hashlib</span></span>
import</span> logging</span></span>
from</span> typing</span> import</span> Tuple</span>,</span> Dict</span></span>
from</span> bip32utils</span> import</span> BIP32Key</span></span>
from</span> eth_account</span> import</span> Account</span></span>
from</span> mnemonic</span> import</span> Mnemonic</span>  #</span> Add BIP39 support</span></span>
</span>
#</span> Configure logging</span></span>
logging</span>.</span>basicConfig</span>(</span>level</span>=</span>logging</span>.</span>INFO</span>)</span></span>
logger</span> =</span> logging</span>.</span>getLogger</span>(</span>"</span>TreasurySystem</span>"</span>)</span></span>
</span>
class</span> TreasurySystem</span>:</span></span>
    def</span> __init__</span>(</span>self</span>,</span> mnemonic</span>:</span> str</span>)</span>:</span></span>
        """</span></span>
        Initialize the treasury system</span></span>
        :param mnemonic: BIP-39 mnemonic (12/24 words)</span></span>
        """</span></span>
        if</span> not</span> Mnemonic</span>(</span>"</span>english</span>"</span>)</span>.</span>check</span>(</span>mnemonic</span>)</span>:</span></span>
            raise</span> ValueError</span>(</span>"</span>Invalid BIP-39 mnemonic</span>"</span>)</span></span>
        </span></span>
        #</span> Generate seed using standard BIP-39</span></span>
        self</span>.</span>seed</span> =</span> Mnemonic</span>.</span>to_seed</span>(</span>mnemonic</span>,</span> passphrase</span>=</span>"</span>"</span>)</span></span>
        self</span>.</span>root_key</span> =</span> BIP32Key</span>.</span>fromEntropy</span>(</span>self</span>.</span>seed</span>)</span></span>
        </span></span>
        logger</span>.</span>info</span>(</span>"</span>Treasury system initialized. Master key fingerprint: </span>%s</span>"</span>,</span> </span></span>
                  self</span>.</span>root_key</span>.</span>Fingerprint</span>(</span>)</span>.</span>hex</span>(</span>)</span>)</span></span>
</span>
    @</span>staticmethod</span></span>
    def</span> _hierarchical_hash</span>(</span>entity</span>:</span> str</span>,</span> department</span>:</span> str</span>)</span> -></span> Tuple</span>[</span>int</span>,</span> int</span>]</span>:</span></span>
        """</span></span>
        Hierarchical hash calculation (compliant with proposal spec)</span></span>
        Returns: (entity_index, department_index)</span></span>
        """</span></span>
        #</span> Entity hash</span></span>
        entity_hash</span> =</span> hashlib</span>.</span>sha256</span>(</span>f</span>"</span>ENTITY:</span>{</span>entity</span>}</span>"</span>.</span>encode</span>(</span>)</span>)</span>.</span>digest</span>(</span>)</span></span>
        entity_index</span> =</span> int</span>.</span>from_bytes</span>(</span>entity_hash</span>[</span>:</span>4</span>]</span>,</span> '</span>big</span>'</span>)</span> |</span> 0x</span>80000000</span></span>
        </span></span>
        #</span> Department hash (chained)</span></span>
        dept_input</span> =</span> f</span>"</span>DEPT:</span>{</span>entity_hash</span>.</span>hex</span>(</span>)</span>}</span>:</span>{</span>department</span>}</span>"</span>.</span>encode</span>(</span>)</span></span>
        dept_hash</span> =</span> hashlib</span>.</span>sha256</span>(</span>dept_input</span>)</span>.</span>digest</span>(</span>)</span></span>
        dept_index</span> =</span> int</span>.</span>from_bytes</span>(</span>dept_hash</span>[</span>:</span>4</span>]</span>,</span> '</span>big</span>'</span>)</span> |</span> 0x</span>80000000</span></span>
        </span></span>
        return</span> entity_index</span>,</span> dept_index</span></span>
</span>
    def</span> _derive_key</span>(</span>self</span>,</span> path</span>:</span> list</span>)</span> -></span> BIP32Key</span>:</span></span>
        """</span>General key derivation method</span>"""</span></span>
        current_key</span> =</span> self</span>.</span>root_key</span></span>
        for</span> index</span> in</span> path</span>:</span></span>
            if</span> not</span> isinstance</span>(</span>index</span>,</span> int</span>)</span>:</span></span>
                raise</span> TypeError</span>(</span>f</span>"</span>Invalid derivation index type: </span>{</span>type</span>(</span>index</span>)</span>}</span>"</span>)</span></span>
            current_key</span> =</span> current_key</span>.</span>ChildKey</span>(</span>index</span>)</span></span>
        return</span> current_key</span></span>
</span>
    def</span> generate_account</span>(</span>self</span>,</span> entity</span>:</span> str</span>,</span> department</span>:</span> str</span>,</span> </span></span>
                        account_idx</span>:</span> int</span> =</span> 0</span>)</span> -></span> Dict</span>[</span>str</span>,</span> str</span>]</span>:</span></span>
        """</span></span>
        Generate department account (BIP44 5-layer structure)</span></span>
        Path: m/44'/60'/entity'/dept'/account_idx</span></span>
        """</span></span>
        e_idx</span>,</span> d_idx</span> =</span> self</span>.</span>_hierarchical_hash</span>(</span>entity</span>,</span> department</span>)</span></span>
        </span></span>
        #</span> BIP-44 standard path</span></span>
        derivation_path</span> =</span> [</span></span>
            0x</span>8000002C</span>,</span>  #</span> 44' (hardened)</span></span>
            0x</span>8000003C</span>,</span>  #</span> 60' (Ethereum)</span></span>
            e_idx</span>,</span>       #</span> entity_index (hardened)</span></span>
            d_idx</span>,</span>       #</span> department_index (hardened)</span></span>
            account_idx</span>  #</span> address index</span></span>
        ]</span></span>
        </span></span>
        key</span> =</span> self</span>.</span>_derive_key</span>(</span>derivation_path</span>)</span></span>
        priv_key</span> =</span> key</span>.</span>PrivateKey</span>(</span>)</span>.</span>hex</span>(</span>)</span></span>
        </span></span>
        return</span> {</span></span>
            '</span>path</span>'</span>:</span> f</span>"</span>m/44</span>'/60</span>'/</span>{</span>e_idx</span>}</span>'/</span>{</span>d_idx</span>}</span>'/</span>{</span>account_idx</span>}</span>"</span>,</span></span>
            '</span>private_key</span>'</span>:</span> priv_key</span>,</span>  #</span> Warning: Never expose this in production</span></span>
            '</span>address</span>'</span>:</span> Account</span>.</span>from_key</span>(</span>priv_key</span>)</span>.</span>address</span></span>
        }</span></span>
</span>
    def</span> get_audit_xpub</span>(</span>self</span>,</span> entity</span>:</span> str</span>,</span> department</span>:</span> str</span>)</span> -></span> str</span>:</span></span>
        """</span></span>
        Retrieve department-level extended public key (for auditing)</span></span>
        Path: m/44'/60'/entity'/dept'</span></span>
        """</span></span>
        e_idx</span>,</span> d_idx</span> =</span> self</span>.</span>_hierarchical_hash</span>(</span>entity</span>,</span> department</span>)</span></span>
        path</span> =</span> [</span></span>
            0x</span>8000002C</span>,</span>  #</span> 44'</span></span>
            0x</span>8000003C</span>,</span>  #</span> 60'</span></span>
            e_idx</span>,</span>       #</span> entity'</span></span>
            d_idx</span>        #</span> dept'</span></span>
        ]</span></span>
        return</span> self</span>.</span>_derive_key</span>(</span>path</span>)</span>.</span>ExtendedKey</span>(</span>)</span></span>
</span>
    def</span> get_dept_xprv</span>(</span>self</span>,</span> entity</span>:</span> str</span>,</span> department</span>:</span> str</span>)</span> -></span> str</span>:</span></span>
        """</span></span>
        Get department-level extended private key (strictly controlled)</span></span>
        Path: m/44'/60'/entity'/dept'</span></span>
        """</span></span>
        e_idx</span>,</span> d_idx</span> =</span> self</span>.</span>_hierarchical_hash</span>(</span>entity</span>,</span> department</span>)</span></span>
        path</span> =</span> [</span></span>
            0x</span>8000002C</span>,</span>  #</span> 44'</span></span>
            0x</span>8000003C</span>,</span>  #</span> 60'</span></span>
            e_idx</span>,</span>       #</span> entity'</span></span>
            d_idx</span>        #</span> dept'</span></span>
        ]</span></span>
        return</span> self</span>.</span>_derive_key</span>(</span>path</span>)</span>.</span>ExtendedKey</span>(</span>)</span></span>
</span>
</span>
    @</span>staticmethod</span></span>
    def</span> derive_addresses_from_xpub</span>(</span>xpub</span>:</span> str</span>,</span> count</span>:</span> int</span> =</span> 20</span>)</span> -></span> list</span>:</span></span>
        """</span>Derive addresses from extended public key (audit use)</span>"""</span></span>
        audit_key</span> =</span> BIP32Key</span>.</span>fromExtendedKey</span>(</span>xpub</span>)</span></span>
        return</span> [</span></span>
            Account</span>.</span>from_key</span>(</span></span>
                audit_key</span></span>
                        .</span>ChildKey</span>(</span>i</span>)</span>   #</span> Address index</span></span>
                        .</span>PrivateKey</span>(</span>)</span></span>
            )</span>.</span>address</span></span>
            for</span> i</span> in</span> range</span>(</span>count</span>)</span></span>
        ]</span></span>
</span>
</span>
if</span> __name__</span> ==</span> "</span>__main__</span>"</span>:</span></span>
    #</span> Example usage (remove private key printing in production)</span></span>
    try</span>:</span></span>
        #</span> Use standard mnemonic</span></span>
        mnemo</span> =</span> Mnemonic</span>(</span>"</span>english</span>"</span>)</span></span>
        mnemonic</span> =</span> mnemo</span>.</span>generate</span>(</span>strength</span>=</span>256</span>)</span></span>
        treasury</span> =</span> TreasurySystem</span>(</span>mnemonic</span>)</span></span>
        print</span>(</span>f</span>"</span>mnemonic: </span>{</span>mnemonic</span>}</span>"</span>)</span></span>
        </span></span>
        print</span>(</span>"</span>\n</span>=== Finance Department Account Generation ===</span>"</span>)</span></span>
        finance_acc1</span> =</span> treasury</span>.</span>generate_account</span>(</span>"</span>GroupA</span>"</span>,</span> "</span>Finance</span>"</span>,</span> 0</span>)</span></span>
        finance_acc2</span> =</span> treasury</span>.</span>generate_account</span>(</span>"</span>GroupA</span>"</span>,</span> "</span>Finance</span>"</span>,</span> 1</span>)</span></span>
        print</span>(</span>f</span>"</span>Account1 path: </span>{</span>finance_acc1</span>[</span>'</span>path</span>'</span>]</span>}</span>"</span>)</span></span>
        print</span>(</span>f</span>"</span>Account1 address: </span>{</span>finance_acc1</span>[</span>'</span>address</span>'</span>]</span>}</span>"</span>)</span></span>
        print</span>(</span>f</span>"</span>Account1 private key: </span>{</span>finance_acc1</span>[</span>'</span>private_key</span>'</span>]</span>}</span>"</span>)</span></span>
        print</span>(</span>f</span>"</span>Account2 path: </span>{</span>finance_acc2</span>[</span>'</span>path</span>'</span>]</span>}</span>"</span>)</span></span>
        print</span>(</span>f</span>"</span>Account2 address: </span>{</span>finance_acc2</span>[</span>'</span>address</span>'</span>]</span>}</span>"</span>)</span></span>
        print</span>(</span>f</span>"</span>Account2 private key: </span>{</span>finance_acc2</span>[</span>'</span>private_key</span>'</span>]</span>}</span>"</span>)</span></span>
</span>
        print</span>(</span>"</span>\n</span>=== Audit Verification Test===</span>"</span>)</span></span>
        audit_xpub</span> =</span> treasury</span>.</span>get_audit_xpub</span>(</span>"</span>GroupA</span>"</span>,</span> "</span>Finance</span>"</span>)</span></span>
        print</span>(</span>f</span>"</span>Audit xpub: </span>{</span>audit_xpub</span>}</span>"</span>)</span></span>
        audit_addresses</span> =</span> TreasurySystem</span>.</span>derive_addresses_from_xpub</span>(</span>audit_xpub</span>,</span> 2</span>)</span></span>
        print</span>(</span>f</span>"</span>Audit-derived addresses: </span>{</span>audit_addresses</span>}</span>"</span>)</span></span>
        </span></span>
        assert</span> finance_acc1</span>[</span>'</span>address</span>'</span>]</span> in</span> audit_addresses</span>,</span> "</span>Audit verification failed</span>"</span></span>
        assert</span> finance_acc2</span>[</span>'</span>address</span>'</span>]</span> in</span> audit_addresses</span>,</span> "</span>Audit verification failed</span>"</span></span>
        print</span>(</span>"</span>✅ Audit verification successful</span>"</span>)</span></span>
</span>
        print</span>(</span>"</span>\n</span>=== Department Isolation Test ===</span>"</span>)</span></span>
        other_dept_acc</span> =</span> treasury</span>.</span>generate_account</span>(</span>"</span>GroupA</span>"</span>,</span> "</span>Audit</span>"</span>,</span> 0</span>)</span></span>
        print</span>(</span>f</span>"</span>Account3 path: </span>{</span>other_dept_acc</span>[</span>'</span>path</span>'</span>]</span>}</span>"</span>)</span></span>
        print</span>(</span>f</span>"</span>Account3 address: </span>{</span>other_dept_acc</span>[</span>'</span>address</span>'</span>]</span>}</span>"</span>)</span></span>
        assert</span> other_dept_acc</span>[</span>'</span>address</span>'</span>]</span> not</span> in</span> audit_addresses</span>,</span> "</span>Isolation breach</span>"</span></span>
        print</span>(</span>"</span>✅ Department isolation effective</span>"</span>)</span></span>
</span>
</span>
        print</span>(</span>"</span>\n</span>=== Department Private Key Sharing Test ===</span>"</span>)</span></span>
        #</span> Gets the department layer extension private key</span></span>
        dept_xprv</span> =</span> treasury</span>.</span>get_audit_xpub</span>(</span>"</span>GroupA</span>"</span>,</span> "</span>Finance</span>"</span>)</span>.</span>replace</span>(</span>'</span>xpub</span>'</span>,</span> '</span>xprv</span>'</span>)</span>  #</span> 实际应通过专用方法获取</span></span>
        print</span>(</span>f</span>"</span>Fiance xprv: </span>{</span>dept_xprv</span>}</span>"</span>)</span></span>
        #</span> Derive the account private key from the extension private key</span></span>
        dept_key</span> =</span> BIP32Key</span>.</span>fromExtendedKey</span>(</span>dept_xprv</span>)</span></span>
        derived_acc0_key</span> =</span> dept_key</span>.</span>ChildKey</span>(</span>0</span>)</span>.</span>PrivateKey</span>(</span>)</span>.</span>hex</span>(</span>)</span></span>
        derived_acc1_key</span> =</span> dept_key</span>.</span>ChildKey</span>(</span>1</span>)</span>.</span>PrivateKey</span>(</span>)</span>.</span>hex</span>(</span>)</span></span>
        print</span>(</span>f</span>"</span>Fiance derived_acc0_key: </span>{</span>derived_acc0_key</span>}</span>"</span>)</span></span>
        print</span>(</span>f</span>"</span>Fiance derived_acc1_key: </span>{</span>derived_acc1_key</span>}</span>"</span>)</span></span>
        #</span> Verify the private key derivation capability</span></span>
        assert</span> derived_acc0_key</span> ==</span> finance_acc1</span>[</span>'</span>private_key</span>'</span>]</span>,</span> \</span></span>
            "</span>Account 0 private key derivation failed</span>"</span></span>
        assert</span> derived_acc1_key</span> ==</span> finance_acc2</span>[</span>'</span>private_key</span>'</span>]</span>,</span> \</span></span>
            "</span>Account 1 private key derivation failed</span>"</span></span>
        print</span>(</span>"</span>✅ Private key derivation from department xprv successful</span>"</span>)</span></span>
</span>
    except</span> Exception</span> as</span> e</span>:</span></span>
        logger</span>.</span>error</span>(</span>"</span>System error: </span>%s</span>"</span>,</span> e</span>,</span> exc_info</span>=</span>True</span>)</span></span></code></pre>
run script:</p>
pip</span> install</span> bip32utils</span> eth_account</span></span>
</span>
python</span> stms.py</span></span></code></pre>
output：</p>
</p>
Security Considerations</h2>
For treasury managers, hierarchical deterministic wallet management is more convenient, but it requires additional consideration of protective measures for the master key, such as schemes for splitting and storing mnemonic phrases or master keys.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Wallet Capabilities for Account Abstraction
2025-03-01T00:00:00+00:00
Abstract</h2>
EIP-5792</a> defines a baseline JSON-RPC API for a communication between wallets and dapps,
and provides an ability to extend the base protocol with "capabilities".</p>
This proposal defines a set of "capabilities" the wallets may want to implement in order to provide a comprehensive
support for Account Abstraction (AA).</p>
These "capabilities" enable passing any data that may be required when using a Paymaster contract,
allows limiting the time range during which the UserOperation is considered valid,
provides a way for the dApp to manually control the semi-abstracted nonce and AA-specific gas limits of the UserOp,
and even allow the dApp to take part in selecting the EIP-7702</a> account implementation.</p>
Motivation</h2>
ERC-4337</a> introduced Account Abstraction, enabling Smart Contract Accounts to function as first-class citizens in Ethereum.
However, while ERC-4337</a> and ERC-7769</a> define a low-level RPC API for Account Abstraction,
they do not specify a way for advanced AA-aware dApps to communicate their supported features and parameters to the advanced AA Wallet Applications.</p>
This ERC addresses the issue by defining a structured set of capabilities tailored for AA-aware dApps and Wallet Applications.</p>
It utilises the EIP-5792</a> wallet capability model to express some of the critical aspects of AA,
ensuring dApps can seamlessly adapt to different AA Wallets without requiring custom solutions.</p>
Specification</h2>
All actions in Account Abstraction within the context of EIP-5792 must be done on a single chain and atomically.</p>
We define the following list of new "capabilities" which together cover many features necessary for Account Abstraction.
Note that use of Paymasters managed by a "paymaster web service" is described in ERC-7677</a>.</p>
Create EIP-7702</a> Authorization Capability</h3>
This capability is designed to be used with EIP-7702</a> and requests the Wallet Application to provide
an EIP-7702 authorization tuple for the specified address as part of the AA transaction.</p>
Identifier:</p>
eip7702Auth</code></p>
Interface:</p>
type</span> SetCodeForEOACapabilityParams</span> =</span> Record</span><</span></span>
  {</span></span>
    account</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span>       //</span> EOA address</span></span>
    delegation</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span>    //</span> delegation address</span></span>
  }</span></span>
></span></span></code></pre>
Supporting Wallet Applications MUST generate an EIP-7702 compatible transaction that sets a code of the account</code> EOA address
to the code of delegation</code> specified in the request.</p>
Static Paymaster Configuration Capability</h3>
The purpose of this capability is allowing applications to integrate with Paymasters that do not require
the Wallet Application to resolve any dynamic configuration.</p>
The application may hard-code or resolve these parameters first and pass them with this capability.</p>
Identifier:</p>
staticPaymasterConfiguration</code></p>
Interface:</p>
type</span> StaticPaymasterConfigurationCapabilityParams</span> =</span> Record</span><</span></span>
  {</span></span>
    paymaster</span>:</span> string</span>;</span></span>
    paymasterData</span>:</span> string</span>;</span></span>
    paymasterValidationGasLimit</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>;</span></span>
    paymasterPostOpGasLimit</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>;</span></span>
  }</span></span>
></span>;</span></span></code></pre>Validity Time Range Capability</h3>
The purpose of this capability is allowing the applications to explicitly specify the time range during which
the requested operations will be valid after signing.</p>
Identifier:</p>
validityTimeRange</code></p>
Interface:</p>
type</span> ValidityTimeRangeCapabilityParams</span> =</span> Record</span><</span></span>
  {</span></span>
    validAfter</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span> //</span> operation valid only after this timestamp, in seconds</span></span>
    validUntil</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>  //</span> operation valid only before this timestamp, in seconds</span></span>
  }</span></span>
></span></span></code></pre>
The Wallet Application MUST verify the time range [validAfter</code>..validUntil</code>] is valid and present it to the
user in a human-readable way for confirmation as part of the transaction information.</p>
The Smart Contract Account MUST specify the time range [validAfter</code>..validUntil</code>] as the transaction validity range.</p>
Multidimensional Nonce Capability</h3>
The purpose of this capability is allowing the applications to explicitly specify the components of the
semi-abstracted nonce as defined in ERC-4337</a>.</p>
Identifier:</p>
multiDimensionalNonce</code></p>
Interface:</p>
type</span> MultiDimensionalNonceCapabilityParams</span> =</span> Record</span><</span></span>
  {</span></span>
    nonceKey</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span></span>
    nonceSequence</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span></span>
  }</span></span>
></span></span></code></pre>
For Smart Contract Accounts that support multidimensional nonce values,
the wallet must specify these parameters during the actual on-chain execution of the batch.</p>
Account Abstraction Gas Parameters Override Capability</h3>
The purpose of this capability is allowing the applications to override the Wallet Application's suggested values
for all gas-related parameters.</p>
This capability provides very low-level access to the underlying Account Abstraction protocol and should only
be used by applications closely coupled to a specific version of a specific protocol.
It may also prove useful in the context of development and debugging.</p>
It is generally recommended that production dapps rely on higher-level features of Wallet Applications instead.</p>
Identifier:</p>
accountAbstractionGasParamsOverride</code></p>
Interface:</p>
type</span> AAGasParamsOverrideCapabilityParams</span> =</span> Record</span><</span></span>
  {</span></span>
    preVerificationGas</span>?</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span></span>
    verificationGasLimit</span>?</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span></span>
    callGasLimit</span>?</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span></span>
    paymasterVerificationGasLimit</span>?</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span></span>
    paymasterPostOpGasLimit</span>?</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span></span>
    maxFeePerGas</span>?</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span>,</span></span>
    maxPriorityFeePerGas</span>?</span>:</span> `</span>0x</span>${</span>string</span>}</span>`</span></span>
  }</span></span>
></span></span></code></pre>
Notice that all fields in the AAGasParamsOverrideCapabilityParams</code> are optional.
Only the values that callers want to override must be provided.</p>
Wallet Applications should warn the users about the overrides being supplied by the call and use these values instead.</p>
Wallet Applications may choose to reject calls with conflicting configurations.</p>
Rationale</h2>

Security Considerations</h2>
eip7702Auth</code></h3>
This is by far the most sensitive capability in the document.
There is no limit to the damage that can be done by signing the wrong capability.</p>
Wallet Applications MUST take extreme care when working with EIP-7702</a>.</p>
Wallet Applications MUST maintain a strict shortlist of well-known and publicly audited Smart Contract Account
implementations that are acceptable as delegation</code>.</p>
Authorization is an extremely sensitive operation and any vulnerability or malicious code in delegation</code> will
result in complete draining of the account</code>.</p>
staticPaymasterConfiguration</code></h3>
This capability has an opportunity to provide the paymaster</code> and paymasterData</code> values for the call.
Incorrect or malicious values can be an attack vector.
For example, a Paymaster contract may hold approvals for ERC-20</a> tokens which may be drained this way.</p>
The Wallet Applications MUST make sure the provided values correspond to user intent.
Fundamentally, this is not very different to how regular transactions' calldata</code> must be verified.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Cancelation for ERC-7540 Tokenized Vaults
2025-02-18T00:00:00+00:00
Abstract</h2>
The following standard extends ERC-7540</a> by adding support for asynchronous cancelation flows.</p>
New methods are added to asynchronously cancel a deposit or redeem Request, view the status of the cancelation Request, and claim the assets or shares as a result of the cancelation Request.</p>
Motivation</h2>
Shares or assets locked for Requests can be stuck in the Pending state. For some use cases, such as redeeming from a pool of long-dated real-world assets, this can take a considerable amount of time.</p>
This standard expands the scope of Asynchronous ERC-7540 Vaults by adding cancelation support.</p>
Specification</h2>
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.</p>
Definitions</h3>
The existing definitions from ERC-7540</a> apply.</p>
Cancelation Lifecycle</h3>
After submission, cancelation Requests go through Pending, Claimable, and Claimed stages. An example lifecycle for a deposit cancelation Request is visualized in the table below.</p>
State</strong></th> User</strong></th> Vault</strong></th></tr></thead>

Pending</td> cancelDepositRequest(requestId, controller)</code></td> pendingCancelDepositRequest[controller] = true</code></td></tr>
Claimable</td> </td> Internal cancelation fulfillment</em>:  pendingCancelDepositRequest[controller] = false</code>; claimableCancelDepositRequest[controller] = assets</code></td></tr>
Claimed</td> claimCancelDepositRequest(requestId, receiver, controller)</code></td> claimableDepositRequest[controller] -= assets</code>; asset.balanceOf[receiver] += assets</code></td></tr>
</tbody></table>
pendingCancelDepositRequest</code> and claimableCancelDepositRequest</code> are defined in the Methods</a> section.</p>
Requests MUST NOT skip or otherwise short-circuit the Claim state. In other words, to initiate and claim a Request, a user MUST call both cancel* and the corresponding Claim function separately, even in the same block. Vaults MUST NOT "push" tokens onto the user after a Request, users MUST "pull" the tokens via the Claim function.</p>
Requests MAY skip straight from the Pending to the Claimable stage, in the case of synchronous cancelation flows.</p>
While a deposit cancelation Request is Pending, new deposit Requests are blocked. Likewise, while a redeem cancelation Request is Pending, new redeem Requests are blocked.</p>
Methods</h3>
cancelDepositRequest</code></h4>
Submits a Request for asynchronous deposit cancelation. This places the Request in Pending state, with a corresponding increase in pendingCancelDepositRequest</code> for the full amount of the pending deposit Request.</p>
When the cancelation is Pending, new deposit Requests are blocked and requestDeposit</code> MUST revert.</p>
When the cancelation is Claimable, claimableCancelDepositRequest</code> will be increased for the controller</code>. claimCancelDepositRequest</code> can subsequently be called by controller</code> to receive assets</code>. A Request MAY transition straight to Claimable state but MUST NOT skip the Claimable state.</p>
controller</code> MUST equal msg.sender</code> unless the controller</code> has approved the msg.sender</code> as an operator.</p>
MUST emit the CancelDepositRequest</code> event.</p>
-</span> n</span>ame</span>:</span> c</span>ancelDepositRequest</span></span>
  t</span>ype</span>:</span> f</span>unction</span></span>
  s</span>tateMutability</span>:</span> n</span>onpayable</span></span>
</span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> r</span>equestId</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> c</span>ontroller</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
  o</span>utputs</span>:</span></span></code></pre>pendingCancelDepositRequest</code></h4>
Whether the given requestId</code> and controller</code> have a pending deposit cancelation Request.</p>
MUST NOT show any variations depending on the caller.</p>
MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</p>
-</span> n</span>ame</span>:</span> p</span>endingCancelDepositRequest</span></span>
  t</span>ype</span>:</span> f</span>unction</span></span>
  s</span>tateMutability</span>:</span> v</span>iew</span></span>
</span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> r</span>equestId</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> c</span>ontroller</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
</span>
  o</span>utputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> i</span>sPending</span></span>
      t</span>ype</span>:</span> b</span>ool</span></span></code></pre>claimableCancelDepositRequest</code></h4>
The amount of assets</code> in Claimable cancelation state for the controller</code> to claim.</p>
MUST NOT show any variations depending on the caller.</p>
MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</p>
-</span> n</span>ame</span>:</span> c</span>laimableCancelDepositRequest</span></span>
  t</span>ype</span>:</span> f</span>unction</span></span>
  s</span>tateMutability</span>:</span> v</span>iew</span></span>
</span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> r</span>equestId</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> c</span>ontroller</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
</span>
  o</span>utputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> a</span>ssets</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span></code></pre>claimCancelDepositRequest</code></h4>
Claims the deposit cancelation Request with requestId</code> and controller</code>.</p>
Transfers assets</code> to receiver</code>.</p>
controller</code> MUST equal msg.sender</code> unless the controller</code> has approved the msg.sender</code> as an operator.</p>
MUST emit the ClaimCancelDepositRequest</code> event.</p>
-</span> n</span>ame</span>:</span> c</span>laimCancelDepositRequest</span></span>
  t</span>ype</span>:</span> f</span>unction</span></span>
  s</span>tateMutability</span>:</span> n</span>onpayable</span></span>
</span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> r</span>equestId</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> r</span>eceiver</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
    -</span> n</span>ame</span>:</span> c</span>ontroller</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
  o</span>utputs</span>:</span></span></code></pre>cancelRedeemRequest</code></h4>
Submits a Request for asynchronous redeem cancelation. This places the Request in Pending state, with a corresponding increase in pendingCancelRedeemRequest</code> for the full amount of the pending redeem Request.</p>
When the cancelation is Pending, new redeem Requests are blocked and requestRedeem</code> MUST revert.</p>
When the cancelation is Claimable, claimableCancelRedeemRequest</code> will be increased for the controller</code>. claimCancelRedeemRequest</code> can subsequently be called by controller</code> to receive shares</code>. A Request MAY transition straight to Claimable state but MUST NOT skip the Claimable state.</p>
controller</code> MUST equal msg.sender</code> unless the controller</code> has approved the msg.sender</code> as an operator.</p>
MUST emit the CancelRedeemRequest</code> event.</p>
-</span> n</span>ame</span>:</span> c</span>ancelRedeemRequest</span></span>
  t</span>ype</span>:</span> f</span>unction</span></span>
  s</span>tateMutability</span>:</span> n</span>onpayable</span></span>
</span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> r</span>equestId</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> c</span>ontroller</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
  o</span>utputs</span>:</span></span></code></pre>pendingCancelRedeemRequest</code></h4>
Whether the given requestId</code> and controller</code> have a pending redeem cancelation Request.</p>
MUST NOT show any variations depending on the caller.</p>
MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</p>
-</span> n</span>ame</span>:</span> p</span>endingCancelRedeemRequest</span></span>
  t</span>ype</span>:</span> f</span>unction</span></span>
  s</span>tateMutability</span>:</span> v</span>iew</span></span>
</span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> r</span>equestId</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> c</span>ontroller</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
</span>
  o</span>utputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> i</span>sPending</span></span>
      t</span>ype</span>:</span> b</span>ool</span></span></code></pre>claimableCancelRedeemRequest</code></h4>
The amount of shares</code> in Claimable cancelation state for the controller</code> to claim.</p>
MUST NOT show any variations depending on the caller.</p>
MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</p>
-</span> n</span>ame</span>:</span> c</span>laimableCancelRedeemRequest</span></span>
  t</span>ype</span>:</span> f</span>unction</span></span>
  s</span>tateMutability</span>:</span> v</span>iew</span></span>
</span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> r</span>equestId</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> c</span>ontroller</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
</span>
  o</span>utputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> s</span>hares</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span></code></pre>claimCancelRedeemRequest</code></h4>
Claims the redeem cancelation Request with requestId</code> and controller</code>.</p>
Transfers assets</code> to receiver</code>.</p>
controller</code> MUST equal msg.sender</code> unless the controller</code> has approved the msg.sender</code> as an operator.</p>
MUST emit the ClaimCancelRedeemRequest</code> event.</p>
-</span> n</span>ame</span>:</span> c</span>laimCancelRedeemRequest</span></span>
  t</span>ype</span>:</span> f</span>unction</span></span>
  s</span>tateMutability</span>:</span> n</span>onpayable</span></span>
</span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> r</span>equestId</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> r</span>eceiver</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
    -</span> n</span>ame</span>:</span> o</span>wner</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
  o</span>utputs</span>:</span></span></code></pre>Events</h3>
CancelDepositRequest</code></h4>
controller</code> has requested cancelation of their deposit Request with request ID requestId</code>. sender</code> is the caller of the cancelDepositRequest</code> which may not be equal to the controller</code>.</p>
MUST be emitted when a deposit cancelation Request is submitted using the cancelDepositRequest</code> method.</p>
-</span> n</span>ame</span>:</span> C</span>ancelDepositRequest</span></span>
  t</span>ype</span>:</span> e</span>vent</span></span>
</span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> c</span>ontroller</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
    -</span> n</span>ame</span>:</span> r</span>equestId</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> s</span>ender</span></span>
      i</span>ndexed</span>:</span> false</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span></code></pre>CancelDepositClaim</code></h4>
controller</code> has claimed their deposit cancelation Request with request ID requestId</code>. receiver</code> is the destination of the assets</code>. sender</code> is the caller of the claimCancelDepositRequest</code> which may not be equal to the controller</code>.</p>
MUST be emitted when a deposit cancelation Request is submitted using the claimCancelDepositRequest</code> method.</p>
-</span> n</span>ame</span>:</span> C</span>ancelDepositClaim</span></span>
  t</span>ype</span>:</span> e</span>vent</span></span>
</span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> c</span>ontroller</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
    -</span> n</span>ame</span>:</span> r</span>eceiver</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
    -</span> n</span>ame</span>:</span> r</span>equestId</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> s</span>ender</span></span>
      i</span>ndexed</span>:</span> false</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
    -</span> n</span>ame</span>:</span> a</span>ssets</span></span>
      i</span>ndexed</span>:</span> false</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span></code></pre>CancelRedeemRequest</code></h4>
controller</code> has requested cancelation of their deposit Request with request ID requestId</code>. sender</code> is the caller of the cancelRedeemRequest</code> which may not be equal to the controller</code>.</p>
MUST be emitted when a redeem cancelation Request is submitted using the cancelRedeemRequest</code> method.</p>
-</span> n</span>ame</span>:</span> C</span>ancelRedeemRequest</span></span>
  t</span>ype</span>:</span> e</span>vent</span></span>
</span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> c</span>ontroller</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
    -</span> n</span>ame</span>:</span> r</span>equestId</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> s</span>ender</span></span>
      i</span>ndexed</span>:</span> false</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span></code></pre>CancelRedeemClaim</code></h4>
controller</code> has claimed their redeem cancelation Request with request ID requestId</code>. receiver</code> is the destination of the shares</code>. sender</code> is the caller of the claimCancelRedeemRequest</code> which may not be equal to the controller</code>.</p>
MUST be emitted when a redeem cancelation Request is submitted using the claimCancelRedeemRequest</code> method.</p>
-</span> n</span>ame</span>:</span> C</span>ancelRedeemClaim</span></span>
  t</span>ype</span>:</span> e</span>vent</span></span>
</span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> c</span>ontroller</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
    -</span> n</span>ame</span>:</span> r</span>eceiver</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
    -</span> n</span>ame</span>:</span> r</span>equestId</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> s</span>ender</span></span>
      i</span>ndexed</span>:</span> false</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
    -</span> n</span>ame</span>:</span> s</span>hares</span></span>
      i</span>ndexed</span>:</span> false</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span></code></pre>ERC-165</a> support</h3>
Smart contracts implementing this Vault standard MUST implement the ERC-165</a> supportsInterface</code> function.</p>
Asynchronous deposit Vaults with cancelation support MUST return the constant value true</code> if 0x8bf840e3</code> is passed through the interfaceID</code> argument.</p>
Asynchronous redemption Vaults with cancelation support MUST return the constant value true</code> if 0xe76cffc7</code> is passed through the interfaceID</code> argument.</p>
Rationale</h2>
Blocking Requests during Cancelation</h3>
When cancelDepositRequest</code> is called by a controller</code>, new deposit Requests are blocked for this controller</code>, and the equivalent applies to the redeem flow.</p>
This requirement simplifies the possible states of vaults implementing asynchronous cancelation flows.</p>
The alternative would create possible states where a cancelation is pending and a new deposit Request is triggered, leading to the current state being complex to read for integrators.</p>
Mandated Support for ERC-165</a></h3>
Implementing support for ERC-165</a> is mandated because of the optionality of flows as defined in ERC-7540</a>. Integrations can use the supportsInterface</code> method to check whether a vault is fully asynchronous, partially asynchronous, or fully synchronous (for which it is just following the ERC-4626</a>), and use a single contract to support all cases.</p>
Backwards Compatibility</h2>
The interface is fully backwards compatible with ERC-7540</a>.</p>
Security Considerations</h2>
Existing security considerations from ERC-7540</a> apply.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Crosschain Broadcaster
2025-02-18T00:00:00+00:00
Abstract</h2>
This ERC defines a protocol for cross-rollup messaging using state commitments. Users can broadcast messages on a source chain, and those messages can be verified on any other chain that shares a common ancestor with the source chain.</p>
A state commitment is a bytes32</code> hash that commits to a chain's state (e.g., block hash or state root). The protocol supports different types of state commitments depending on what the rollup commits to its parent chain. Block hashes are the recommended state commitment, but state roots or other commitments may be used, such as batch hashes (since some rollups don't commit single blocks, but batches of blocks instead).</p>
Each chain deploys a singleton Receiver and Broadcaster contract. Broadcasters store messages; Receivers verify the Broadcasters' state on remote chains. To do this, a Receiver first verifies a chain of state commitment proofs to recover a remote state commitment, then verifies the Broadcaster's state at that commitment.</p>
Critically, the logic for verifying state commitment proofs is not hardcoded in the Receiver. Instead, it delegates this to a user specified list of StateProver contracts. Each StateProver defines how to verify a state commitment proof for a specific home chain to recover the state commitment of a specific target chain. Because the state commitment schemes and layouts of rollup contracts can change over time, the state commitment proof verification process itself must also be upgradeable—hence the StateProvers are upgradeable. This flexible, upgradeable proof verification model is the core contribution of this standard.</p>
Motivation</h2>
The Ethereum ecosystem is experiencing a rapid growth in the number of rollup chains. As the number of chains grows, the experience becomes more fragmented for users, creating a need for trustless "interop" between rollup chains. These rollup chains, hosted on different rollup stacks, have heterogeneous properties, and as yet there does not exist a simple, trustless, unified mechanism for sending messages between these diverse chains.</p>
Many classes of applications could benefit from a unified system for broadcasting messages across chains. Some examples include:</p>

Intent-Based Protocols:</strong> These protocols enable "fillers" to quickly execute crosschain actions on behalf of users, followed by slower, trustless messaging to settle these actions. However, due to the lack of a simple, unified interface for sending settlement messages, intent protocols often develop proprietary methods. This raises adoption barriers for fillers, integrators, and new protocols. A pluggable, standardized messaging solution that works across rollup stacks would allow developers and standards authors to focus on other components of the intent stack, such as fulfillment constraints, order formats, and escrow.</li>
Governance of multichain apps:</strong> Multichain apps often have a single chain where core governance contracts are located. A standardized broadcast messaging system simplifies the dissemination of proposal results to all instances of a multichain app.</li>
Multichain Oracles:</strong> Some classes of oracles may benefit from being able to post their data to a single chain, while having that same data easily accessible across many other chains.</li>
</ul>
Specification</h2>
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.</p>
Compatibility Requirements</h3>
Chains must satisfy the following conditions to be compatible with the system:</p>

Must store finalized state commitments on the parent chain</li>
Must store parent chain state commitments in child chain state</li>
Must be EVM equivalent with L1. StateProvers are deployed as copies on many chains, so need to behave the same on all those chains</li>
</ul>
Constants</h3>
uint256</span> constant</span> STATE_PROVER_POINTER_SLOT </span>=</span> uint256</span>(</span>keccak256</span>(</span>"eip7888.pointer.slot"</span>)</span>)</span> -</span> 1</span>;</span></span></code></pre>State Commitments</h3>
A state commitment</strong> is a bytes32</code> hash that commits to the state of a chain at a particular point in time. This commitment is produced by the rollup and serves as a cryptographic representation of the chain's state. The most common state commitments are:</p>

Block hash</strong>: A hash of the block header, which is the recommended state commitment for most implementations</li>
State root</strong>: The root of the state tree (e.g., Merkle-Patricia Trie) or other state commitment structure</li>
Batch hash</strong>: A hash of a batch of blocks, used by some rollups that commit batches of blocks rather than individual blocks</li>
</ul>
The choice of state commitment depends on what the rollup commits to its parent chain. Different rollups may use different state commitments, and the StateProver is responsible for verifying proofs that recover these commitments from the parent chain's state.</p>
Broadcaster</h3>
The Broadcaster is responsible for storing messages in state to be read by Receivers on other chains. Callers of the Broadcaster are known as Publishers. The Broadcaster stores only 32 byte messages.</p>
The Broadcaster does not accept duplicate messages from the same publisher.</p>



Figure 1: A Publisher at address 0x4 calling a Broadcaster at address 0x3</em>
</div>
///</span> @notice</span> Broadcasts messages to receivers.</span></span>
interface</span> IBroadcaster</span> {</span></span>
    ///</span> @notice</span> Emitted when a message is broadcast.</span></span>
    ///</span> @param</span>  message</span> The message that was broadcast by the publisher.</span></span>
    ///</span> @param</span>  publisher</span> The address of the publisher.</span></span>
    event</span> MessageBroadcast</span>(</span>bytes32</span> indexed</span> message</span>, </span>address</span> indexed</span> publisher</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Broadcasts a message. Callers are called "publishers".</span></span>
    ///</span> @dev</span>    MUST revert if the publisher has already broadcast the message.</span></span>
    ///</span>         MUST emit MessageBroadcast.</span></span>
    ///</span>         MUST store block.timestamp in slot keccak(message, msg.sender).</span></span>
    ///</span>         MAY use additional transmission mechanisms (e.g., child-to-parent native bridges) to make messages visible.</span></span>
    ///</span> @param</span>  message</span> The message to broadcast.</span></span>
    function</span> broadcastMessage</span>(</span>bytes32</span> message</span>)</span> external</span>;</span></span>
}</span></span></code></pre>StateProvers</h3>
StateProvers prove a unidirectional link between two chains that have direct access to each other's finalized state commitments. The chains in this link are called the home chain</strong> and the target chain</strong>. StateProvers are responsible for verifying state commitment proofs to prove the existence of finalized target state commitments in the state of the home chain. Block hashes are the recommended state commitment, but implementations may use other commitments (e.g., state roots, batch hashes).</p>
Since the StateProvers are unidirectional, each chain needs to have two:</p>

One whose home is the child chain and target is the parent chain.</li>
One whose home is the parent chain and target is the child chain.</li>
</ul>
StateProvers MUST ensure that they will have the same deployed code hash on all chains.</p>



Figure 2: A StateProver with home chain L and target chain M</em>
</div>
///</span> @notice</span> The IStateProver is responsible for retrieving the state commitment of its target chain given its home chain's state.</span></span>
///</span>         The home chain's state is given either by a state commitment and proof, or by the StateProver executing on the home chain.</span></span>
///</span>         A single home and target chain are fixed by the logic of this contract.</span></span>
interface</span> IStateProver</span> {</span></span>
    ///</span> @notice</span> Verify the state commitment of the target chain given the state commitment of the home chain and a proof.</span></span>
    ///</span> @dev</span>    MUST revert if called on the home chain.</span></span>
    ///</span>         MUST revert if the input is invalid or the input is not sufficient to determine the state commitment.</span></span>
    ///</span>         MUST return a target chain state commitment.</span></span>
    ///</span>         MUST be pure, with 1 exception: MAY read address(this).code.</span></span>
    ///</span> @param</span>  homeStateCommitment</span> The state commitment of the home chain.</span></span>
    ///</span> @param</span>  input</span> Any necessary input to determine a target chain state commitment from the home chain state commitment.</span></span>
    ///</span> @return</span> targetStateCommitment</span> The state commitment of the target chain.</span></span>
    function</span> verifyTargetStateCommitment</span>(</span>bytes32</span> homeStateCommitment</span>,</span> bytes</span> calldata</span> input</span>)</span></span>
        external</span></span>
        view</span></span>
        returns</span> (</span>bytes32</span> targetStateCommitment</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Get the state commitment of the target chain. Does so by directly accessing state on the home chain.</span></span>
    ///</span> @dev</span>    MUST revert if not called on the home chain.</span></span>
    ///</span>         MUST revert if the target chain's state commitment cannot be determined.</span></span>
    ///</span>         MUST return a target chain state commitment.</span></span>
    ///</span>         SHOULD use the input to determine a specific state commitment to return. (e.g. input could be a block number)</span></span>
    ///</span>         SHOULD NOT read from its own storage. This contract is not meant to have state.</span></span>
    ///</span>         MAY make external calls.</span></span>
    ///</span> @param</span>  input</span> Any necessary input to fetch a target chain state commitment.</span></span>
    ///</span> @return</span> targetStateCommitment</span> The state commitment of the target chain.</span></span>
    function</span> getTargetStateCommitment</span>(</span>bytes</span> calldata</span> input</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span> targetStateCommitment</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Verify a storage slot given a target chain state commitment and a proof.</span></span>
    ///</span> @dev</span>    This function MUST NOT assume it is being called on the home chain.</span></span>
    ///</span>         MUST revert if the input is invalid or the input is not sufficient to determine a storage slot and its value.</span></span>
    ///</span>         MUST return a storage slot and its value on the target chain.</span></span>
    ///</span>         MUST be pure, with 1 exception: MAY read address(this).code.</span></span>
    ///</span>         While messages MUST be stored in storage slots, alternative reading mechanisms may be used in some cases.</span></span>
    ///</span> @param</span>  targetStateCommitment</span> The state commitment of the target chain.</span></span>
    ///</span> @param</span>  input</span> Any necessary input to determine a single storage slot and its value.</span></span>
    ///</span> @return</span> account</span> The address of the account on the target chain.</span></span>
    ///</span> @return</span> slot</span> The storage slot of the account on the target chain.</span></span>
    ///</span> @return</span> value</span> The value of the storage slot.</span></span>
    function</span> verifyStorageSlot</span>(</span>bytes32</span> targetStateCommitment</span>,</span> bytes</span> calldata</span> input</span>)</span></span>
        external</span></span>
        view</span></span>
        returns</span> (</span>address</span> account</span>,</span> uint256</span> slot</span>,</span> bytes32</span> value</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> The version of the state commitment prover.</span></span>
    ///</span> @dev</span>    MUST be pure, with 1 exception: MAY read address(this).code.</span></span>
    function</span> version</span>(</span>)</span> external</span> pure</span> returns</span> (</span>uint256</span>)</span>;</span></span>
}</span></span></code></pre>StateProverPointers</h3>
StateProvers can be used to get or verify target state commitments, however since their verification logic is immutable, changes to the structure of the home or target chain can break the logic in these Provers. A StateProverPointer is a Pointer to a StateProver which can be updated if proving logic needs to change.</p>
StateProverPointers are used to reference StateProvers as opposed to referencing Provers directly. To that end, wherever a StateProver is deployed a StateProverPointer needs to be deployed to reference it.</p>
StateProverPointers allow a permissioned party to update the Prover reference within the Pointer. Choosing which party should have the permission to update the Prover reference should be carefully considered. The general rule is that if an update to the target or home chain could break the logic in the current Prover, then the party, or mechanism, able to make that update should also be given permission to update the Prover. See Security Considerations</a> for more information on StateProverPointer ownership and updates.</p>
When updating a StateProverPointer to point to a new StateProver implementation:</p>

The home and target chain of the new StateProver MUST be identical to the previous StateProver.</li>
The new StateProver MUST have a higher version than the previous StateProver.</li>
</ul>
StateProverPointers MUST store the code hash of the StateProver implementation in slot STATE_PROVER_POINTER_SLOT</code>.</p>



Figure 3: A StateProverPointer at address 0xA pointing to a StateProver with home chain L and target chain M</em>
</div>
///</span> @title</span>  IStateProverPointer</span></span>
///</span> @notice</span> Keeps the code hash of the latest version of a state commitment prover.</span></span>
///</span>         MUST store the code hash in storage slot STATE_PROVER_POINTER_SLOT.</span></span>
///</span>         Different versions of the prover MUST have the same home and target chains.</span></span>
///</span>         If the pointer's prover is updated, the new prover MUST have a higher IStateProver::version() than the old one.</span></span>
///</span>         These pointers are always referred to by their address on their home chain.</span></span>
interface</span> IStateProverPointer</span> {</span></span>
    ///</span> @notice</span> Return the code hash of the latest version of the prover.</span></span>
    function</span> implementationCodeHash</span>(</span>)</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Return the address of the latest version of the prover on the home chain.</span></span>
    function</span> implementationAddress</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
}</span></span></code></pre>Routes</h3>
A route is a relative path from a Receiver on a local chain to a remote chain. It is constructed of many single degree links dictated by StateProverPointers. Receivers use the StateProvers that the Pointers reference to verify a series of proofs to obtain the remote chain's state commitment. A route works with any state commitment scheme (block hashes, state roots, etc.) and is defined by the list of Pointer addresses on their home chains.</p>
A valid route MUST obey the following:</p>

Home chain of the route[0]</code> Pointer must equal the local chain</li>
Target chain of the route[i]</code> Pointer must equal home chain of the route[i+1]</code> Pointer</li>
</ul>



Figure 4: A route [0xA, 0xB, 0xC] from chain L to chain R
Chain L is an L2, Chain M is Ethereum Mainnet, Chain P is another L2, and Chain R is an L3 settling to Chain P</em>
</div>
Identifiers</h3>
Accounts on remote chains are identified by the route taken from the local chain plus the address on the remote chain. The Pointer addresses used in the route, along with the remote address, are cumulatively keccak256 hashed together to form a Remote Account ID</strong>.</p>
In this way any address on a remote chain, including Pointers and Broadcasters, can be uniquely identified relative to the local chain by their Remote Account ID.</p>
ID's depend on a route and are therefore always relative</em> to a local chain. In other words, the same account on a given chain will have different ID's depending on the route from the local chain.</p>
The Remote Account ID is defined as accumulator([...route, remoteAddress])</code></p>
function</span> accumulator</span>(</span>address</span>[</span>]</span> memory</span> elems</span>)</span> pure</span> returns</span> (</span>bytes32</span> acc</span>)</span> {</span></span>
    for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> elems</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span>
        acc </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>acc</span>,</span> elems</span>[</span>i</span>]</span>)</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>
In Figure 4:</p>

The Remote Account ID of Broadcaster at 0x3</code> is accumulator([0xA, 0xB, 0xC, 0x3])</code></li>
The Remote Account ID of StateProverPointer 0xC</code> is accumulator([0xA, 0xB, 0xC])</code>.</li>
</ul>
StateProverCopies</h3>
StateProverCopies are exact copies of StateProvers deployed on non-home chains. When a StateProver code hash is de-referenced from a Pointer, a copy of the StateProver may be used to execute its logic. Since the Pointer references the prover by code hash, a local copy of the Prover can be deployed and used to execute specific proving logic. The Receiver caches a map of mapping(bytes32 stateProverPointerId => IStateProver stateProverCopy)</code> to keep track of StateProverCopies.</p>



Figure 5: A StateProverCopy of StateProver M->P on chain L</em>
</div>
Receiver</h3>
The Receiver is responsible for verifying 32 byte messages deposited in Broadcasters on other chains. The caller provides the Receiver with a route to the remote account and proof to verify the route.</p>



Figure 6: Example of a Receiver reading a message from a Broadcaster on chain R</em>
</div>
The calls in Figure 6 perform the following operations:</p>

Subscriber calls IReceiver::verifyBroadcastMessage</code>, passing route [0xA, 0xB, 0xC]</code>, proof data, message, publisher.</li>
Receiver calls IStateProverPointer(0xA)::implementationAddress</code> to get the address of StateProver L->M</li>
Receiver calls IStateProver(Prover L->M)::getTargetState</code>, passing input given by Subscriber to get a state commitment of chain M.</li>
Receiver calls IStateProver(Prover Copy M->P)::verifyTargetState</code>, passing chain M's state commitment and proof data by Subscriber to get a state commitment of chain P.</li>
Receiver calls IStateProver(Prover Copy P->R)::verifyTargetState</code>, passing chain P's state commitment and proof data by Subscriber to get a state commitment of chain R.</li>
Finally, Receiver calls IStateProver(Prover Copy P->R)::verifyStateValue</code>, passing input given by Subscriber to get a storage slot from the Broadcaster. The Receiver returns the Broadcaster's Remote Account ID and the message's timestamp to Subscriber.</li>
</ol>
///</span> @notice</span> Reads messages from a broadcaster.</span></span>
interface</span> IReceiver</span> {</span></span>
    ///</span> @notice</span> Arguments required to read state of an account on a remote chain.</span></span>
    ///</span> @dev</span>    The proof is always for a single storage slot. If the proof is for multiple slots the IReceiver MUST revert.</span></span>
    ///</span>         The proof format depends on the state commitment scheme used by the StateProver (e.g., storage proofs).</span></span>
    ///</span>         While messages MUST be stored in storage slots, alternative reading mechanisms may be used in some cases.</span></span>
    ///</span> @param</span>  route</span> The home chain addresses of the StateProverPointers along the route to the remote chain.</span></span>
    ///</span> @param</span>  scpInputs</span> The inputs to the StateProver / StateProverCopies.</span></span>
    ///</span> @param</span>  proof</span> Proof passed to the last StateProver / StateProverCopy</span></span>
    ///</span>               to verify a storage slot given a target state commitment.</span></span>
    struct</span> RemoteReadArgs</span> {</span></span>
        address</span>[</span>]</span> route</span>;</span></span>
        bytes</span>[</span>]</span> scpInputs</span>;</span></span>
        bytes</span> proof</span>;</span></span>
    }</span></span>
</span>
    ///</span> @notice</span> Reads a broadcast message from a remote chain.</span></span>
    ///</span> @param</span>  broadcasterReadArgs</span> A RemoteReadArgs object:</span></span>
    ///</span>         - The route points to the broadcasting chain</span></span>
    ///</span>         - The account proof is for the broadcaster's account</span></span>
    ///</span>         - The proof is for the message storage slot (MAY accept proofs of other transmission mechanisms (e.g., child-to-parent native bridges) if the broadcaster contract uses other transmission mechanisms)</span></span>
    ///</span> @param</span>  message</span> The message to read.</span></span>
    ///</span> @param</span>  publisher</span> The address of the publisher who broadcast the message.</span></span>
    ///</span> @return</span> broadcasterId</span> The broadcaster's unique identifier.</span></span>
    ///</span> @return</span> timestamp</span> The timestamp when the message was broadcast.</span></span>
    function</span> verifyBroadcastMessage</span>(</span>RemoteReadArgs</span> calldata</span> broadcasterReadArgs</span>,</span> bytes32</span> message</span>,</span> address</span> publisher</span>)</span></span>
        external</span></span>
        view</span></span>
        returns</span> (</span>bytes32</span> broadcasterId</span>,</span> uint256</span> timestamp</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Updates the state commitment prover copy in storage.</span></span>
    ///</span>         Checks that StateProverCopy has the same code hash as stored in the StateProverPointer</span></span>
    ///</span>         Checks that the version is increasing.</span></span>
    ///</span> @param</span>  scpPointerReadArgs</span> A RemoteReadArgs object:</span></span>
    ///</span>         - The route points to the StateProverPointer's home chain</span></span>
    ///</span>         - The account proof is for the StateProverPointer's account</span></span>
    ///</span>         - The proof is for the STATE_PROVER_POINTER_SLOT</span></span>
    ///</span> @param</span>  scpCopy</span> The StateProver copy on the local chain.</span></span>
    ///</span> @return</span> scpPointerId</span> The ID of the StateProverPointer</span></span>
    function</span> updateStateProverCopy</span>(</span>RemoteReadArgs</span> calldata</span> scpPointerReadArgs</span>,</span> IStateProver</span> scpCopy</span>)</span></span>
        external</span></span>
        returns</span> (</span>bytes32</span> scpPointerId</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> The StateProverCopy on the local chain corresponding to the scpPointerId</span></span>
    ///</span>         MUST return 0 if the StateProverPointer does not exist.</span></span>
    function</span> stateProverCopy</span>(</span>bytes32</span> scpPointerId</span>)</span> external</span> view</span> returns</span> (</span>IStateProver</span> scpCopy</span>)</span>;</span></span>
}</span></span></code></pre>Rationale</h2>
Broadcast vs Unicast</h3>
A contract on any given chain cannot dictate which other chains can and cannot inspect its state. Contracts are naturally broadcasting their state to anything capable of reading it. Targeted messaging applications can always be built on top of a broadcast messaging system.</p>
See Reference Implementation</a> for an example of a unicast application.</p>
Using Storage Proofs</h3>
Message reading SHOULD use storage proofs to read messages from storage slots. However, an alternative method to this would be to pass messages (perhaps batched) via the canonical bridges of the chains. However storage proofs have some advantages over this method:</p>

They only require gas tokens on the chains where the message is sent and received, none on the chains on the route in between.</li>
Batching by default. Since storage slots share a common state root, caching the state root allows readers to open adjacent slots at lower cost. This provides a form of implicit batching, whereas canonical bridges would need to create a form of explicit batching.</li>
If the common ancestor of the two chains is Ethereum, sending a message using the canonical bridges would require sending a transaction on Ethereum, which would likely incur a high cost.</li>
</ul>
No duplicate messages per publisher</h3>
To allow publishers to send the same message multiple times, some kind of nonce system would need to exist in this ERC. Since nonces can be implemented at the Publisher / Subscriber layer, and not all Publishers / Subscribers require this feature, it is left out of this ERC.</p>
Cost Comparison</h4>
Here we compare the cost of using storage proofs vs sending messages via the canonical bridge, where the parent chain is Ethereum. Here, we will only consider the cost of the L1 gas as we assume it to dominate the L2 gas costs.</p>
Each step along the route requires 1 storage proof. These proofs can be estimated at roughly 6.5k bytes. These proofs will likely be submitted on an L2/L3 and therefore be included in blobs on the L1, which have a fluctuating blob gas price. Since rollups can dynamically switch between calldata and blobs, we can work out a maximum amount of normal L1 gas that could be using the standard cost of calldata as an upper bound. Post Pectra, the upper bound for non-zero-byte calldata is 40 gas per byte, which for 6.5k bytes equates to 260,000 L1 gas.</p>
We want to compare this to sending a single message via a canonical rollup bridge, which is either a parent->child or child->parent message. This estimate is dependent on specific implementations of the bridge for different rollup frameworks, but we estimate it to be around 150,000 gas.</p>
This puts the upper bound of the storage proof to be around 2x that of the canonical bridge, but in practice this upper bound is rarely reached. On top of that, the Receiver can implement a caching policy allowing many messages to share the same storage proofs.</p>
Caching</h3>
This ERC does not currently describe how the Receiver can cache the results of storage proofs to improve efficiency. In brief, once a storage proof is executed it never needs to be executed again, and instead the result can be stored by the Receiver. This allows messages that share the same, or partially the same, route to share previously executed proofs and instead lookup the result. As an example we can consider the route between two L2s using storage proofs:</p>

Ethereum block hash is looked up directly on L2' by the Receiver on L2'</li>
The block hash of L2'' is proven using a storage proof</li>
The account root of the Broadcaster on L2'' is proven using a storage proof</li>
The slot value in the Broadcaster account is proven using a storage proof
The result of everything up to step 4 in this process can be stored in a Receiver cache and re-used by any unread messages in the Broadcaster. The Receiver can even go further and cache individual nodes in the account trie to make step 4. cheaper for previous messages.</li>
</ol>
Using Routes in Identifiers</h3>
Chains are often identified by chain ID's. Chain ID's are set by the chain owner so they are not guaranteed to be unique. Using the addresses of the Pointers is guaranteed to be unique as it provides a way to unwrap the nested state commitments embedded in the state roots. A storage slot on a remote chain can be identified by many different remote account ID's, but one remote account ID cannot identify more than one storage slot.</p>
StateProvers, Pointers, and Copies</h3>
StateProvers</h4>
Each rollup implements unique logic for managing and storing state commitments. To accommodate this diversity, StateProvers implement chain-specific procedures. This flexibility allows integration with each rollup's distinct architecture and state commitment scheme.</p>
The StateProver handles the final step of verifying a storage slot given a target state commitment to accommodate rollups with differing state commitment schemes and formats.</p>
StateProverPointers</h4>
Routes reference StateProvers through Pointers rather than directly. This indirection is crucial because:</p>

Chain upgrades may require StateProver redeployments</li>
Routes must remain stable and valid across these upgrades - ensuring in-flight messages are not broken</li>
Pointers maintain route consistency while allowing StateProver implementations to evolve</li>
</ul>
StateProverCopies</h4>
Since StateProverPointers reference StateProvers via their code hash, a copy of the StateProver can be deployed anywhere and reliably understood to contain the same code as that referenced by the Pointer. This allows the Receiver to locally use the code of a StateProver whose home chain is a remote chain.</p>
Reference Implementation</h2>
The following is an example of a one-way crosschain token migrator. The burn side of the migrator is a publisher which sends burn messages through a Broadcaster. The mint side subscribes to these burn messages through a Receiver on another chain.</p>
///</span> @notice</span> Message format for the burn and mint migrator.</span></span>
struct</span> BurnMessage</span> {</span></span>
    address</span> mintTo</span>;</span></span>
    uint256</span> amount</span>;</span></span>
    uint256</span> nonce</span>;</span></span>
}</span></span></code></pre>///</span> @notice</span> The burn side of an example one-way cross chain token migrator.</span></span>
///</span> @dev</span>    This contract is considered a "publisher"</span></span>
contract</span> Burner</span> {</span></span>
    ///</span> @notice</span> The token to burn.</span></span>
    IERC20 </span>public</span> immutable</span> burnToken</span>;</span></span>
    ///</span> @notice</span> The broadcaster to publish messages through.</span></span>
    IBroadcaster </span>public</span> immutable</span> broadcaster</span>;</span></span>
    ///</span> @notice</span> An incrementing nonce, so each burn is a unique message.</span></span>
    uint256</span> public</span> burnCount</span>;</span></span>
</span>
    ///</span> @notice</span> Event emitted when tokens are burned.</span></span>
    ///</span> @dev</span>    Publishers SHOULD emit enough information to reconstruct the message.</span></span>
    event</span> Burn</span>(</span>BurnMessage</span> messageData</span>)</span>;</span></span>
</span>
    constructor</span>(</span>IERC20</span> _burnToken</span>,</span> IBroadcaster</span> _broadcaster</span>)</span> {</span></span>
        burnToken </span>=</span> _burnToken</span>;</span></span>
        broadcaster </span>=</span> _broadcaster</span>;</span></span>
    }</span></span>
</span>
    ///</span> @notice</span> Burn the tokens and broadcast the event.</span></span>
    ///</span>         The corresponding token minter will subscribe to the message on another chain and mint the tokens.</span></span>
    function</span> burn</span>(</span>address</span> mintTo</span>,</span> uint256</span> amount</span>)</span> external</span> {</span></span>
        //</span> first, pull in the tokens and burn them</span></span>
        burnToken</span>.</span>transferFrom</span>(</span>msg.sender</span>,</span> address</span>(</span>this</span>)</span>,</span> amount</span>)</span>;</span></span>
        burnToken</span>.</span>burn</span>(</span>amount</span>)</span>;</span></span>
</span>
        //</span> next, build a unique message</span></span>
        BurnMessage </span>memory</span> messageData </span>=</span> BurnMessage</span>(</span>{</span>mintTo</span>:</span> mintTo</span>,</span> amount</span>:</span> amount</span>,</span> nonce</span>:</span> burnCount</span>+</span>+</span>}</span>)</span>;</span></span>
        bytes32</span> message </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>messageData</span>)</span>)</span>;</span></span>
</span>
        //</span> finally, broadcast the message</span></span>
        broadcaster</span>.</span>broadcastMessage</span>(</span>message</span>)</span>;</span></span>
</span>
        emit</span> Burn</span>(</span>messageData</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>///</span> @notice</span> The mint side of an example one-way cross chain token migrator.</span></span>
///</span>         This contract must be given minting permissions on its token.</span></span>
///</span> @dev</span>    This contract is considered a "subscriber"</span></span>
contract</span> Minter</span> {</span></span>
    ///</span> @notice</span> Address of the Burner contract on the other chain.</span></span>
    address</span> public</span> immutable</span> burner</span>;</span></span>
    ///</span> @notice</span> The BroadcasterID corresponding to the broadcaster on the other chain that the Burner uses.</span></span>
    ///</span>         The Minter will only accept messages published by the Burner through this Broadcaster.</span></span>
    bytes32</span> public</span> immutable</span> broadcasterId</span>;</span></span>
    ///</span> @notice</span> The receiver to listen for messages through.</span></span>
    IReceiver </span>public</span> immutable</span> receiver</span>;</span></span>
    ///</span> @notice</span> A mapping to keep track of which messages have been processed.</span></span>
    ///</span>         Subscribers SHOULD keep track of processed messages because the Receiver does not.</span></span>
    ///</span>         The Broadcaster ensures messages are unique, so true duplicates are not possible.</span></span>
    mapping</span>(</span>bytes32</span> =></span> bool</span>)</span> public</span> processedMessages</span>;</span></span>
    ///</span> @notice</span> The token to mint.</span></span>
    IERC20 </span>public</span> immutable</span> mintToken</span>;</span></span>
</span>
    constructor</span>(</span>address</span> _burner</span>,</span> bytes32</span> _broadcasterId</span>,</span> IReceiver</span> _receiver</span>,</span> IERC20</span> _mintToken</span>)</span> {</span></span>
        burner </span>=</span> _burner</span>;</span></span>
        broadcasterId </span>=</span> _broadcasterId</span>;</span></span>
        receiver </span>=</span> _receiver</span>;</span></span>
        mintToken </span>=</span> _mintToken</span>;</span></span>
    }</span></span>
</span>
    ///</span> @notice</span> Mint the tokens when a message is received.</span></span>
    function</span> mintTokens</span>(</span>IReceiver</span>.</span>RemoteReadArgs</span> calldata</span> broadcasterReadArgs</span>,</span> BurnMessage</span> calldata</span> messageData</span>)</span></span>
        external</span></span>
    {</span></span>
        //</span> calculate the message from the data</span></span>
        bytes32</span> message </span>=</span> keccak256</span>(</span>abi</span>.</span>encode</span>(</span>messageData</span>)</span>)</span>;</span></span>
</span>
        //</span> ensure the message has not been processed</span></span>
        require</span>(</span>!</span>processedMessages</span>[</span>message</span>]</span>,</span> "Minter: Message already processed"</span>)</span>;</span></span>
</span>
        //</span> verify the broadcast message</span></span>
        (</span>bytes32</span> actualBroadcasterId</span>,</span>)</span> =</span> receiver</span>.</span>verifyBroadcastMessage</span>(</span>broadcasterReadArgs</span>,</span> message</span>,</span> burner</span>)</span>;</span></span>
</span>
        //</span> ensure the message is from the expected broadcaster</span></span>
        require</span>(</span>actualBroadcasterId </span>==</span> broadcasterId</span>,</span> "Minter: Invalid broadcaster ID"</span>)</span>;</span></span>
</span>
        //</span> mark the message as processed</span></span>
        processedMessages</span>[</span>message</span>]</span> =</span> true</span>;</span></span>
</span>
        //</span> mint tokens to the recipient</span></span>
        mintToken</span>.</span>mint</span>(</span>messageData</span>.</span>mintTo</span>,</span> messageData</span>.</span>amount</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Security Considerations</h2>
Chain Upgrades</h3>
If a chain upgrades such that a StateProver's verifyTargetState</code> or getTargetState</code> functions might return data besides a finalized target state commitment, then invalid messages could be read by a Receiver</code>. For instance, if a chain stores its state commitments on the parent chain in a specific mapping, and that storage slot is later repurposed, then an old StateProver might be able to pass along an invalid state commitment. It is therefore important that either:</p>

the StateProver is written in such a way to detect changes like this</li>
the owner who is able to repurpose these storage slots is aware of the StateProver and ensures they don't break it</li>
</ul>
StateProverPointer Ownership / Updates</h3>
A malicious StateProverPointer owner can DoS or forge messages. However, so can the chain owner responsible for setting the slot of historical parent/child state commitments. Therefore it is expected that this chain owner be the same as the owner of the StateProverPointer so as not to introduce additional risks.</p>

If the target chain of the referenced StateProver is the parent chain, the home chain owner is expected to be the StateProverPointer's owner.</li>
If the target chain of the referenced StateProver is the child chain, the target chain owner is expected to be the StateProverPointer's owner.</li>
</ul>
If an owner neglects their responsibility to update the Pointer with new StateProver implementations when necessary, messages could fail to reach their destinations.</p>
If an owner maliciously updates a Pointer to point to a StateProver that produces fraudulent results, messages can be forged.</p>
If there is confidence that a chain along the route connecting them will not upgrade to break a StateProver, an unowned StateProverPointer can be deployed in the absence of a properly owned one.</p>
Message guarantees</h3>
This ERC describes a protocol for ensuring that messages from remote chains CAN be read, but not that they WILL be read. It is the responsibility of the Receiver caller to choose which messages they wish to read.</p>
Since the ERC only uses finalized blocks, messages may take a long time to propagate between chains. Finalisation occurs sequentially in the route, therefore time to read a message is the sum of the finalisation of each of the state commitments at each step in the route.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>

Ethereum Improvement Proposals - ERC

Compressed Display Format for Addresses

1. Trigger Condition</h3> Compression SHOULD be applied if a sequence of identical hexadecimal nibbles has a length $L$, where $L \geq 6$.</p>

2. Formatting Rules</h3> The standard defines two modes of display. Implementations must preserve the first character of the repeating sequence to indicate which character is being repeated, followed by a count of the total length of the sequence.</p>

Mode B: ASCII Fallback (CLI/Logs)</h4> Recommended for Developer Consoles, Logs, and Copy-Paste operations.</p> Syntax:</strong> 0x</code> + [repeating_char]</code> + {</code> + [count]</code> + }</code> + [remainder]</code></p> Example:</strong></p>

Rationale</h2>

Series Accounting for Incentivized Vaults

Backwards Compatibility</h2> Note that ERC-8113 is not backwards compatible with ERC-7540 or ERC-4626.</p> The incompatibilties with ERC-4626 are as follows:</p>

Copyright</h2> Copyright and related rights waived via CC0</a>.</p>

Bound Signatures

Abstract</h2> Recoverable ECDSA signatures can flip s</code> and v</code> while remaining valid, so they can be compressed to 64 bytes by restricting v</code>.</p>

Security Considerations</h2> Bound signatures are recoverable and not malleable.</p>

Diamonds, Simplified

Abstract</h2> A diamond is a proxy contract that delegatecall</code>s to multiple implementation contracts called facets.</p> </p>

Specification</h2>

Diamond Diagram</h3> This diagram shows the structure of a diamond.</p> It shows that a diamond has a mapping from function to facet and that facets can access the storage inside a diamond.</p> </p>

Function Not Found</h4> If the fallback function cannot find a facet for a function selector, and there is no default function or other mechanism to handle the call, the fallback MUST revert with the error FunctionNotFound(bytes4 _selector)</code>.</p>

Events</h3> Adding/Replacing/Removing Functions</h4> These events are REQUIRED.</p> For each function selector that is added, replaced, or removed, the corresponding event MUST be emitted.</p>

Adding/Replacing/Removing Functions</h4> These events are REQUIRED.</p> For each function selector that is added, replaced, or removed, the corresponding event MUST be emitted.</p>

Implementation Requirements</h3> A diamond MUST implement the following:</p> Diamond Structure</strong> A diamond MUST implement a fallback()</code> function.</li> </ul> </li>

Diamond Upgrades</h3> This standard does not specify an upgrade function.</p> This means several things:</p>

2. Other Standards Can Build on ERC-8109</h4> Other standards can build on ERC-8109 by specifying an upgrade function(s), while remaining compliant with this standard.</p>

Facets Sharing Storage & Functionality</h3> Facets are separately deployed, independent units, but can share state and functionality in the following ways:</p> Facets can share state variables by using the same structs at the same storage positions.</li>

Security Considerations</h2>

Transparency</h3> A diamond emits an event every time a function is added, replaced or removed. Source code can be verified. This enables people and software to monitor changes to a diamond.</p> Security and domain experts can review a diamond's upgrade history.</p>

Domain Architecture for Diamonds

Specification</h2>

Copyright</h2> Copyright and related rights waived via CC0</a>.</p>

RWA Event-based Compliance Framework

Missing Capabilities</h3> Entity Classification</strong>: No standardized way to distinguish regulated corporate entities from decentralized participants</li> Compliance Observability</strong>: No uniform event semantics for tracking compliance-relevant transfers</li>

Why Event-Based?</h3> This standard adopts an event-driven approach rather than enforcement through reverts:</p>

Specification</h2> 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.</p>

Recommended Flagging Policy (Non-normative)</h4> Implementations SHOULD apply the following flagging heuristics:</p>

Event-Based Compliance</h4> Implementations SHOULD NOT revert transactions solely based on compliance flags. This event-based approach enables:</p>

Rationale</h2>

Reference Implementation</h2> Implementation Patterns</h3> Embedded Registry</strong>: Store entity types in the token contract itself</p>

Implementation Patterns</h3> Embedded Registry</strong>: Store entity types in the token contract itself</p>

Security Considerations</h2> Event Integrity:</strong> Implementations MUST emit ComplianceObserved</code> events only after actual ERC-20</a> balance changes. Emitting events without value movement compromises auditability.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p>

ENS Trust Registry for Agent Coordination

Semantics</h3>

1. Trigger Condition</h3>
Compression SHOULD be applied if a sequence of identical hexadecimal nibbles has a length $L$, where $L \geq 6$.</p>

2. Formatting Rules</h3>
The standard defines two modes of display. Implementations must preserve the first character of the repeating sequence to indicate which character is being repeated, followed by a count of the total length of the sequence.</p>

Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>

Abstract</h2>
Recoverable ECDSA signatures can flip `s</code> and v</code> while remaining valid, so they can be compressed to 64 bytes by restricting v</code>.</p>`

Security Considerations</h2>
Bound signatures are recoverable and not malleable.</p>

Diamond Diagram</h3>
This diagram shows the structure of a diamond.</p>
It shows that a diamond has a mapping from function to facet and that facets can access the storage inside a diamond.</p>
</p>

Function Not Found</h4>
If the fallback function cannot find a facet for a function selector, and there is no default function or other mechanism to handle the call, the fallback MUST revert with the error `FunctionNotFound(bytes4 _selector)</code>.</p>`

Diamond Upgrades</h3>
This standard does not specify an upgrade function.</p>
This means several things:</p>

2. Other Standards Can Build on ERC-8109</h4>
Other standards can build on ERC-8109 by specifying an upgrade function(s), while remaining compliant with this standard.</p>

Transparency</h3>
A diamond emits an event every time a function is added, replaced or removed. Source code can be verified. This enables people and software to monitor changes to a diamond.</p>
Security and domain experts can review a diamond's upgrade history.</p>

Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>

Specification</h2>
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.</p>

`Security Considerations</h2> Event Integrity:</strong> Implementations MUST emit ComplianceObserved</code> events only after actual ERC-20</a> balance changes. Emitting events without value movement compromises auditability.</p> Copyright</h2> Copyright and related rights waived via CC0</a>.</p>`