SSZ ProgressiveList

2025-03-24T00:00:00+00:00

Abstract</h2>
This EIP introduces a new Merkle tree shape for Simple Serialize (SSZ)</a> types that results in fewer hashes when only a small number of leaves is used. The new tree shape grows progressively with increased leaf count and no longer has a bounded capacity. It also offers forward compatibility: a given chunk index is always assigned the same stable generalized index (gindex)</a> regardless of leaf count.
New types are defined to use the progressive Merkle tree shape: `ProgressiveList[type]</code> and ProgressiveBitlist</code>. These new types represent lists of arbitrary length with stable merkleization, reducing hashing overhead for small lists and avoiding arbitrary capacity limits.`

`Motivation</h2> Current SSZ List[type, N]</code> types require a predefined capacity N</code>, which leads to several issues:`Inefficient hashing: Lists often contain far fewer elements than their maximum capacity (e.g., Transaction</code></a>), resulting in unnecessary zero-padding and dozens of extra hash computations. This is exacerbated when nesting List[type, N]</code>, e.g., in a design where each of up to X</code> transactions has up to Y</code> access lists, each with up to Z</code> storage slots.</li> Arbitrary Limits: The capacity N</code> is often chosen arbitrarily (e.g., MAX_BYTES_PER_TRANSACTION</code></a>, MAX_TRANSACTIONS_PER_PAYLOAD</code></a>) and set to artificially large values to anticipate future design space, which are not always correct.</li> Unstable proofs: Modifying N</code> across forks (e.g., MAX_ATTESTER_SLASHINGS_ELECTRA</code></a>, MAX_ATTESTATIONS_ELECTRA</code></a>) alters gindices, breaking downstream verifiers.</li> </ul> The progressive Merkle tree shape addresses these by: Using a recursive tree structure that progressively grows to the actual leaf count with minimal overhead</li> Dropping the notion of a maximum capacity, relying instead on practical limits, e.g., SSZ's 4 GB variable offset cap, network payload limits, gas limits, bounds on the number of signatures.</li> Maintaining stable gindices for each element, ensuring provers remain valid as the leaf count changes.</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. Progressive Merkle tree</h3> The SSZ Merkleization specification</a> is extended with a helper function: merkleize_progressive(chunks, num_leaves=1)</code>: Given ordered BYTES_PER_CHUNK</code>-byte chunks: The merkleization depends on the number of input chunks and is defined recursively: If len(chunks) == 0</code>: the root is a zero value, Bytes32()</code>.</li> Otherwise: compute the root using hash(a, b)</code> a</code>: Merkleize the first up to num_leaves</code> chunks as a binary tree using merkleize(chunks[:num_leaves], num_leaves)</code>.</li> b</code>: Recursively merkleize chunks beyond num_leaves</code> using merkleize_progressive(chunks[num_leaves:], num_leaves * 4)</code>.</li> </ul> </li> </ul> </li> </ul> </li> </ul> This results in a 0-terminated sequence of binary subtrees with increasing leaf count. The deepest subtree is padded with zeroed chunks (virtually for memory efficiency). root /\ / \ 1: chunks[0 ..< 1] /\ / \ 4: chunks[1 ..< 5] /\ / \ 16: chunks[5 ..< 21] /\ / \ 64: chunks[21 ..< 85] 0</code></pre>Depth</th> Added chunks</th> Total chunks</th> Total capacity (bytes)</th></tr></thead> 0</td> 0</td> 0</td> 0</td></tr> 1</td> 1</td> 1</td> 32</td></tr> 2</td> 4</td> 5</td> 160</td></tr> 3</td> 16</td> 21</td> 672</td></tr> 4</td> 64</td> 85</td> 2'720</td></tr> 5</td> 256</td> 341</td> 10'912</td></tr> 6</td> 1'024</td> 1'365</td> 43'680</td></tr> 7</td> 4'096</td> 5'461</td> 174'752</td></tr> 8</td> 16'384</td> 21'845</td> 699'040</td></tr> 9</td> 65'536</td> 87'381</td> 2'796'192</td></tr> 10</td> 262'144</td> 349'525</td> 11'184'800</td></tr> 11</td> 1'048'576</td> 1'398'101</td> 44'739'232</td></tr> 12</td> 4'194'304</td> 5'592'405</td> 178'956'960</td></tr> 13</td> 16'777'216</td> 22'369'621</td> 715'827'872</td></tr> 14</td> 67'108'864</td> 89'478'485</td> 2'863'311'520</td></tr> 15</td> 268'435'456</td> 357'913'941</td> 11'453'246'112</td></tr> </tbody></table> ProgressiveList[type]</code> and ProgressiveBitlist</code></h3> Two new SSZ composite types</a> are defined: progressive list: ordered variable-length homogeneous collection, without limit notation ProgressiveList[type]</code>, e.g. ProgressiveList[uint64]</code></li> </ul> </li> progressive bitlist: ordered variable-length collection of boolean</code> values, without limit notation ProgressiveBitlist</code></li> </ul> </li> </ul> The new types are considered "variable-size"</a>. For convenience we alias</a>: ProgressiveByteList</code> to ProgressiveList[byte]</code></li> </ul> The default value</a> is defined as: Type</th> Default Value</th></tr></thead> ProgressiveList[type]</code></td> []</code></td></tr> ProgressiveBitlist</code></td> []</code></td></tr> </tbody></table> Serialization</h4> Serialization, deserialization, and JSON mapping of ProgressiveBitlist</code> are identical to Bitlist[N]</code></a>. Serialization, deserialization, and JSON mapping of ProgressiveList[type]</code> are identical to List[type, N]</code></a>. Merkleization</h4> The Merkleization</a> definitions are extended. mix_in_length(merkleize_progressive(pack(value)), len(value))</code> if value</code> is a progressive list of basic objects.</li> mix_in_length(merkleize_progressive(pack_bits(value)), len(value))</code> if value</code> is a progressive bitlist.</li> mix_in_length(merkleize_progressive([hash_tree_root(element) for element in value]), len(value))</code> if value</code> is a progressive list of composite objects.</li> </ul> Rationale</h2> Why a recursive structure?</h3> Efficiency: Small lists use fewer hashes (e.g., a 3-item list in a 16-element subtree wastes fewer hashes than a 1024-element List[type, N]</code>).</li> Stability: Fixed subtree sizes ensure stable gindices, avoiding the need for dynamic depth adjustments or multiple queries.</li> Scalability: Recursive subtrees allow arbitrary growth without a hardcoded limit, constrained only by practical limits (e.g., network payload limit, validation rules).</li> </ul> Why not dynamic depth?</h3> Dynamic-depth Merkleization destabilizes gindices: Requires two-step queries (length then gindex), increasing latency and reorg risks.</li> Complicates proofs with semantic lookups.</li> </ul> Mixing in successor subtrees ensures predictable gindices and proof sizes. Why not fixed-capacity lists?</h3> List[type, N]</code>: Imposes arbitrary limits, hindering scalability.</li> Breaks stability when redefined.</li> Wastes hashes with padding (e.g., 1024-element capacity for a 1-item list). (only log(N) wasted hashes)</li> </ul> ProgressiveList[type]</code> offers a scalable, efficient alternative. Why are initial leaf count and scaling factors not exposed parameters?</h3> Simplicity: Fixed values (initial leaf count 1, scaling factor 4) provide a sensible default that balances efficiency and usability, aligning with SSZ’s goal of simplicity.</li> Future Extensibility: If specific use cases demand different values, a future EIP could introduce parameterization. For now, fixed values reduce adoption barriers and align with the principle of "good enough" defaults.</li> </ul> Backwards Compatibility</h2> The new SSZ types coexist with existing types without conflict and share their serialization logic. Test Cases</h2> ethereum/remerkleable</code> contains static tests in test_impl.py</code> and test_typing.py</code>.</li> ethereum/consensus-specs</code> releases contain random tests in tests/general/phase0/ssz_generic</code>, generated according to a format defined in tests/format/ssz_generic</code>.</li> </ul> Reference Implementation</h2> See ethereum/remerkleable</code>. Security Considerations</h2> Resource limits: The uint32</code> limit for variable-length offsets essentially introduces a ~4GB cap when including a ProgressiveList[type]</code> or ProgressiveBitlist</code> within another complex type, but practical limits (e.g., 10MB libp2p messages) apply. Implementations SHOULD enforce context-specific bounds.</li> Variable proof size: Recursive traversal may increase proof sizes for large indices, though logarithmic in list size due to the scaling factor.</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>. EOF - EXTCODEADDRESS instruction 2025-02-08T00:00:00+00:00 Abstract</h2> Add an instruction to EOF that reads code delegation designations from an account without requiring code introspection. Motivation</h2> EOFv1 as scoped in EIP-7692</a> removes code introspection capabilities from the EVM, preventing EOF from reading raw code values such as code delegation designations set by EIP-7702</a>. There are a number of use cases where reading the delegation designation of EIP-7702</a> would allow contracts to be more proactive about user experience issues. One example is a managed proxy contract. Such a contract may want to ensure security by not allowing the proxy to be updated to a delegated address. There are also safety concerns with pointing to a delegation, as the contract may be updated to non EOF code and EXTDELEGATECALL</code> will no longer be able to call the contract, due to changes outside the control of the managed proxy contract. Another example are contracts that need to ensure that the delegation has not changed over a limited scope of time, such as sponsorships. This will prevent a transaction from receiving gas sponsorship, changing the delegation, and performing an act different than what was approved. Sponsors can encode the delegation into the transaction data and verify with this instruction. Finally, there is the case where contracts may want to de-escalate risks and only accept a small number of delegations for any given contract. To enable this validation contracts will need to be able to resolve the actual address of delegation, not just know that one exists. To address this the essential task of the designation parsing is moved into a new opcode EXTCODEADDRESS</code>, where the task of calculating the delegated address will be performed. For non-delegated accounts or empty accounts the address will be the same as the queried address. Specification</h2> Parameters</h3> Constant</th> Value</th></tr></thead> GAS_COLD_ACCOUNT_ACCESS</code></td> Defined as 2600</code> in the Ethereum Execution Layer Spec Constants</a></td></tr> GAS_WARM_ACCESS</code></td> Defined as 100</code> in the Ethereum Execution Layer Spec Constants</a></td></tr> </tbody></table> We introduce a new EOFv1 instruction EXTCODEADDRESS</code> (0xea</code>). EOF code which contains this instruction prior to the fork activating this instruction is considered invalid. Beginning with the first block this EIP is activated in, this instruction is added to the set of valid EOFv1 instructions. Execution Semantics</h3> EXTCODEADDRESS</code></h4> Deduct GAS_WARM_ACCESS</code> gas</li> pop 1 argument target_address</code> from the stack</li> if target_address</code> has any of the high 12 bytes set to a non-zero value (i.e. it does not contain a 20-byte address), then halt with an exceptional failure Notice: Future expansion of the EVM address space may enlarge the number of valid addresses. Do not rely on this step always halting with the current restrictions.</li> </ul> </li> deduct GAS_COLD_ACCOUNT_ACCESS - GAS_WARM_ACCESS</code> if target_address</code> is not in accessed_addresses</code> and add target_address</code> to accessed_addresses</code></li> Load the code from target_address</code> and refer to it as loaded_code</code></li> If loaded_code</code> indicates a delegation designator (for example, prefixed with 0xef0100</code> as defined in EIP-7702</a>) push the address of the designation onto the stack. Notice: if EIP-7702</a> delegation designations are updated in a future fork (such as allowing chained delegations), then this section is expected to comply with any such hypothetical changes.</li> </ul> </li> Otherwise, push target_address</code> onto the stack.</li> </ul> Note: If target_address</code> points to an account with a contract mid-creation, then target_address</code> is returned. If delegation designator points to an account with a contract mid-creation, then address of the designation is returned. Note: Only target_address</code> is warmed. If a delegation is found the address that it is delegated to is not added to the accessed_addresses</code>. Also, whether the delegated address is in accessed_addresses</code> has no impact on the gas charged for the operation. Note: This operation straddles the line between EIP-7702</a> code reading and code executing instructions. The operation steps work as a code reading instruction, but the value returned is the resolved address as through it is a code executing instruction. Rationale</h2> This EIP is very similar to EIP-7761</a>, which introduces account type introspection. Its rationale is included by reference as they all apply to this situation. Alternative: Return the whole designation, have contract parse</h3> One alternative is to have a specially limited EXTCODECOPY</code> that would return just delegation designations. Apart from the general objections to code introspection this would then lock in and limit delegation designation formats and capabilities that must be preserved in future forks. By allowing access to the effect of the delegation rather than the mechanism, EOF preserves space for the mechanism to be changed without breaking existing code. Backwards Compatibility</h2> EXTCODEADDRESS</code> at 0xea</code> can be introduced in a backwards compatible manner into EOFv1 (no bump to version), because 0xea</code> has been rejected by EOF validation prior to the activation of this EIP, and there are no EOF contracts on-chain with an 0xea</code> instruction which would have their behavior altered. Security Considerations</h2> EIP-7702</a> code delegation is a new feature that has not been made accessible to mainnet yet. EIP authors will keep abreast of any developments and reflect on their impact to this proposed instruction. Copyright</h2> Copyright and related rights waived via CC0</a> Max blob flag for local builders 2025-01-30T00:00:00+00:00 Abstract</h2> This EIP adds a flag to the block builder in order to allow them to include a client configured maximum amount of blobs. This is an execution layer only change. Motivation</h2> Currently a builder will include all blobs in their local mempool, up to the maximum amount that the protocol requires. If a builder has low bandwidth, they may include too many blobs and subsequently end up not being able to convince the network that the blobs are available. Specification</h2> Create a parameter in block builder's configuration called USER_CONFIGURED_MAX_BLOBS_PER_BLOCK</code></li> Take the minimum out of the MAX_BLOB_GAS_PER_BLOCK</code> and the USER_CONFIGURED_MAX_BLOBS_PER_BLOCK</code></li> If the minimum is zero, set the minimum to one.</li> Use the minimum to decide how many blobs to include in the block</li> </ul> Note: By default USER_CONFIGURED_MAX_BLOBS_PER_BLOCK</code> may be set to the maximum in the current fork. Rationale</h2> By adding a flag for the local block builder, they are able to specify how many blobs they can include in a block. Backwards Compatibility</h2> No backward compatibility issues found. Security Considerations</h2> N/A Copyright</h2> Copyright and related rights waived via CC0</a>. Decentralised User Profiles 2025-01-22T00:00:00+00:00 Abstract</h2> This EIP proposes a standard for decentralised, interoperable user profiles known as Decentralised Profiles. Profiles are implemented as Soul Bound Tokens (SBTs) that are immutable, non-transferable, and tied to unique identifiers across multiple blockchain networks. The standard provides a unified structure for user metadata, including dApp-specific customisation, default profiles, and seamless cross-chain compatibility. Profiles can be leveraged for identity management, reputation systems, and personalised dApp experiences. Motivation</h2> Existing solutions for decentralised identity and user profiles lack cross-chain compatibility, dApp-specific customisation, and standardisation. A unified approach is essential to: Facilitate interoperable profiles across all chains.</li> Leverage the immutability and non-transferability of SBTs for secure identities.</li> Enable dApp-specific customisations, such as unique avatars.</li> Provide a robust, standards-based alternative to centralised solutions like Gravatar.</li> Ensure user control and decentralisation with profiles stored on IPFS/Arweave.</li> A common standard for Decentralised Identity that can be used across all chains.</li> Act as a Digital Passport for users, enabling seamless decentralised verification and authentication.</li> </ol> Specification</h2> Unique Profile Identifiers</h3> Decentralised Profile</h4> Each profile is identified by: <username>@<network_slug>.soul</code></pre> username</code>: User-defined, chain-unique string.</li> network_slug</code>: Short identifier for the chain (e.g., eth</code>, polygon</code>, xion</code>).</li> soul</code>: Fixed suffix indicating soul bound token.</li> </ul> Example: john@eth.soul</code> alice@polygon.soul</code> Decentralised Identifier (DID)</h4> Each profile is tied to a DID: did:<chain>:<address></code></pre> Example: did:ethereum:0x123...</code> did:xion:xion1abc...</code> Metadata Structure</h3> The profile metadata structure is designed to balance extensibility, usability, and compatibility with decentralized storage systems like IPFS. Metadata will adhere to the following schema: { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "UserProfile", "type": "object", "properties": { "username": { "type": "string", "description": "The unique handle of the user." }, "avatar": { "type": "string", "format": "uri", "description": "IPFS URI pointing to the user's main avatar image." }, "bio": { "type": "string", "description": "Short description or biography of the user." }, "website": { "type": "string", "format": "uri", "description": "Personal or professional website of the user." }, "socials": { "type": "object", "description": "User's social links.", "properties": { "twitter": { "type": "string", "format": "uri", "description": "URL to the user's Twitter profile." }, "github": { "type": "string", "format": "uri", "description": "URL to the user's GitHub profile." } }, "required": ["twitter", "github"], "additionalProperties": false }, "default_avatar_visibility": { "type": "string", "enum": ["public", "private"], "description": "Default visibility setting for the main avatar." }, "dapp_avatars": { "type": "object", "description": "Mapping of DApp addresses to their custom avatars and visibility settings.", "patternProperties": { "^0x[a-fA-F0-9]{40}$": { "type": "object", "properties": { "avatar": { "type": "string", "format": "uri", "description": "IPFS URI for the DApp-specific avatar." }, "visibility": { "type": "string", "enum": ["public", "private"], "description": "Visibility setting for this avatar." } }, "required": ["avatar", "visibility"], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "username", "avatar", "bio", "website", "socials", "default_avatar_visibility", "dapp_avatars" ], "additionalProperties": false }</code></pre> Here's an example using the structure above: { "username": "batman", "avatar": "ipfs://QmExampleMainAvatarCID", "bio": "Blockchain enthusiast and builder.", "website": "https://anirudha.dev", "socials": { "twitter": "https://twitter.com/kranirudha", "github": "https://github.com/anistark" }, "default_avatar_visibility": "public", "dapp_avatars": { "0xDAppAddress1abcdefabcdefabcdefabcdefabcdefabcd": { "avatar": "ipfs://QmExampleAvatar1CID", "visibility": "private" }, "0xDAppAddress2abcdefabcdefabcdefabcdefabcdefabcd": { "avatar": "ipfs://QmExampleAvatar2CID", "visibility": "public" } } }</code></pre>Access Control</h4> Default Avatar Visibility: Users can set their default avatar visibility as public or private.</li> dApp-Specific Avatar Visibility: Each dApp-specific avatar can also have its visibility set to public or private.</li> </ol> Visibility Logic: If an avatar is public, it is retrievable by any external caller.</li> If an avatar is private, only the user can retrieve it. Other callers will get an encoded response alongwith error message.</li> </ul> dApp-Specific Avatar Customisation</h3> Users can assign dApp-specific avatars or metadata.</li> If no dApp-specific customisation exists, the default avatar applies.</li> </ul> Rationale</h2> The design of the Decentralised Profile Standard was guided by the need for a unified, interoperable user profile system that can operate seamlessly across all blockchain networks. Current solutions, such as ENS profiles or Gravatar, either lack cross-chain functionality, are centralised, or do not allow users to customise profiles for specific dApps. This standard addresses these shortcomings while ensuring simplicity, security, and scalability. Design Decisions</h3> Decentralised Identifiers (DIDs) Using the did:<chain>:<address></code> format provides a globally unique identifier for profiles. This aligns with the decentralised identity movement and ensures compatibility with broader DID frameworks.</li> </ul> </li> Decentralised Profile The profile format (username@networkslug.soul</code>) makes profiles human-readable and chain-specific while maintaining a universal structure. The .soul</code> suffix clearly identifies profiles compliant with this standard.</li> </ul> </li> dApp-Specific Avatars Allowing users to assign dApp-specific avatars caters to personalisation and enhances the user experience. It supports scenarios where users may want different representations or metadata for different applications.</li> </ul> </li> Soul Bound Tokens (SBTs) Leveraging SBTs ensures that profiles are non-transferable, reinforcing the concept of identity ownership. SBTs prevent profiles from being sold or hijacked, making them ideal for reputation-based systems.</li> </ul> </li> Registry and Resolver Architecture This architecture was chosen for its extensibility and proven track record, as seen in ENS. It separates the management of profile identifiers (Registry) from the resolution of metadata (Resolver), making upgrades and integrations straightforward.</li> </ul> </li> Compatibility with Existing Standards The profile standard integrates with ERC-165</a> for interface detection and can complement ENS or other naming systems, fostering interoperability rather than competition.</li> </ul> </li> Default and dApp-Specific Metadata The inclusion of both default and dApp-specific metadata ensures flexibility. If dApp-specific metadata is not set, the default profile seamlessly applies, reducing friction for developers and users.</li> </ul> </li> On-Chain Data Minimisation Metadata is stored off-chain (e.g., IPFS or Arweave) to minimise gas costs and support scalable operations. Only URIs and pointers are stored on-chain.</li> </ul> </li> Access Control Users have complete control over avatar visibility, catering to privacy preferences.</li> Specific dApp-based customizations ensure fine-grained control.</li> </ul> </li> dApp Identification </li> </ol> Requiring dApps to be identified by an address ensures traceability and security.</li> </ul> Extensibility</li> </ol> Adding metadata fields or new visibility levels does not disrupt the standard.</li> Profiles can remain lightweight while supporting future scalability.</li> </ul> Security</li> </ol> Access control minimizes the risk of sensitive data exposure.</li> Metadata stored off-chain ensures minimal gas usage and flexibility.</li> </ul> Alternative Designs Considered</h4> Pure On-Chain Metadata Storing all metadata on-chain was considered but discarded due to high gas costs, limited storage capacity, and challenges in supporting complex or large datasets such as high-resolution avatars.</li> </ul> </li> Direct Integration with ENS While integrating with ENS was explored, it was deemed limiting for cross-chain functionality, as ENS is predominantly tied to Ethereum. Decentralised profile takes inspiration from ENS while ensuring a truly multichain approach.</li> </ul> </li> Fully Centralised System A centralised system would simplify implementation but contradict the core principles of decentralisation and user sovereignty.</li> </ul> </li> Non-SBT-Based Implementation Using standard ERC-721</a> tokens for profiles was considered but rejected since transferability is unsuitable for identity management. SBTs enforce the immutability of identity ownership.</li> </ul> </li> </ol> Comparison with Related Work</h3> ERC-137</a> (ENS): Provides a robust naming service but lacks dApp-specific metadata and cross-chain functionality.</li> Centralised identity services: Cannot leverage blockchain-specific advantages like immutability, decentralisation, and SBT integration.</li> DID Standards: Profile must aligns with DID specifications, ensuring it fits into the broader decentralised identity ecosystem while offering features tailored to blockchain-based applications.</li> </ul> Scalability and Extensibility</h3> The Registry and Resolver architecture, combined with off-chain metadata storage, ensures that profile can scale with the growth of the blockchain ecosystem. New chains, metadata types, and customisations can be added without disrupting the core functionality or introducing breaking changes. The design balances simplicity, extensibility, and user control, making it well-suited for adoption across a wide range of dApps, wallets, and blockchains. Contract Interface</h3> The standard includes the following interface: ISoulProfile</code></h4> // SPDX-License-Identifier: CC0-1.0 pragma solidity ^0.8.19; interface ISoulProfile { struct Metadata { string username; string avatar; string bio; string website; mapping(string => string) socials; string defaultAvatarVisibility; mapping(address => DappAvatar) dappAvatars; } struct DappAvatar { string avatarURI; string visibility; // "public" or "private" } event ProfileCreated(address indexed user, string did, string username); event AvatarUpdated(address indexed user, string avatarURI, string visibility); event DappAvatarUpdated( address indexed user, address indexed dApp, string avatarURI, string visibility ); function createProfile(string calldata username) external; function setDefaultAvatar(string calldata avatarURI, string calldata visibility) external; function setDappAvatar( address dApp, string calldata avatarURI, string calldata visibility ) external; function getDefaultAvatar(address user) external view returns (string memory, string memory); function getDappAvatar(address user, address dApp) external view returns (string memory, string memory); }</code></pre>Reference Implementation</h3> SoulProfile</code></h4> // SPDX-License-Identifier: CC0-1.0 pragma solidity ^0.8.19; import "@openzeppelin/contracts/access/Ownable.sol"; import "@openzeppelin/contracts/utils/Strings.sol"; import "./ISoulProfile.sol"; contract SoulProfile is Ownable, ISoulProfile { mapping(address => Metadata) private profiles; modifier onlyProfileOwner(address user) { require(msg.sender == user, "Not authorized"); _; } function createProfile(string calldata username) external override { require(bytes(username).length > 0, "Username cannot be empty"); require(profiles[msg.sender].username == "", "Profile already exists"); profiles[msg.sender].username = username; profiles[msg.sender].defaultAvatarVisibility = "public"; // Default to public emit ProfileCreated(msg.sender, generateDID(msg.sender), username); } function setDefaultAvatar(string calldata avatarURI, string calldata visibility) external override { require(bytes(visibility).length > 0, "Visibility must be set"); profiles[msg.sender].avatar = avatarURI; profiles[msg.sender].defaultAvatarVisibility = visibility; emit AvatarUpdated(msg.sender, avatarURI, visibility); } function setDappAvatar( address dApp, string calldata avatarURI, string calldata visibility ) external override { require(dApp != address(0), "Invalid dApp address"); require(bytes(visibility).length > 0, "Visibility must be set"); profiles[msg.sender].dappAvatars[dApp] = DappAvatar(avatarURI, visibility); emit DappAvatarUpdated(msg.sender, dApp, avatarURI, visibility); } function getDefaultAvatar(address user) external view override returns (string memory avatarURI, string memory visibility) { Metadata storage profile = profiles[user]; return (profile.avatar, profile.defaultAvatarVisibility); } function getDappAvatar(address user, address dApp) external view override returns (string memory avatarURI, string memory visibility) { Metadata storage profile = profiles[user]; DappAvatar storage dappAvatar = profile.dappAvatars[dApp]; return (dappAvatar.avatarURI, dappAvatar.visibility); } function generateDID(address user) internal pure returns (string memory) { return string(abi.encodePacked("did:ethereum:", Strings.toHexString(user))); } }</code></pre> Of course, this can be extended to prepare a full registry and resolver according to ENS or similar standards. Refer to Rationale above for more information about the same. Backwards Compatibility</h2> The Decentralised Profile system is designed to ensure smooth integration with existing decentralized applications (dApps) and platforms, while offering an upgrade path for future enhancements. Below are key considerations for backwards compatibility: ENS Compatibility: The system adheres to the naming conventions and standards specified in ERC-137</a> (Ethereum Name Service). This ensures that any dApps or tools already using ENS-compatible names can easily integrate profiles without additional changes. </li> Flexible dApp Identification: By using wallet addresses to identify dApps, the system avoids the need for centralized registration of dApps. Any existing or new dApp that interacts with Ethereum or compatible chains can use the standard by simply passing its address as a parameter. </li> Default Avatar Fallback: If no specific avatar is set for a dApp, the system gracefully falls back to the default avatar. This ensures that even older dApps that do not implement the latest features can continue to work seamlessly. </li> Upgradeable Contracts: By implementing a proxy-based architecture for all major contracts (resolver, registry, profile), the system ensures that future upgrades or changes in functionality can be deployed without disrupting existing data or workflows. Upgrades are conducted through secure proxy mechanisms like TransparentUpgradeableProxy. </li> Chain Agnosticism: The use of decentralized identifiers (DIDs) and chain-specific network slugs ensures interoperability across chains. This allows profiles to maintain consistency regardless of which chain they originate from, ensuring compatibility with multi-chain ecosystems. </li> </ul> Security Considerations</h2> Profile system should prioritise robust security to protect user data and prevent unauthorized access. Access Control: Users can set visibility for their avatars (public or private). This is enforced at both the resolver and registry levels to ensure unauthorized entities cannot access private avatars. Functions that modify state (e.g., setDefaultAvatar, setDappAvatar) are protected with access controls, ensuring only the profile owner can make changes. </li> Data Privacy: Sensitive metadata is encrypted before storage on decentralized storage systems like IPFS or Arweave. Visibility flags ensure users can control who can view specific profile elements. </li> Reentrancy Protection: Functions modifying state implement the checks-effects-interactions pattern or leverage ReentrancyGuard to prevent reentrancy attacks. For example, setDappAvatar ensures that all validations are performed before updating the state. </li> Input Validation: All user inputs (e.g., username, visibility, dApp) are validated to ensure they meet specified criteria. Invalid or malicious inputs are rejected to prevent injection attacks or other exploits. Visibility is restricted to predefined values ("public" or "private"). </li> Immutable DIDs: Decentralized identifiers (DIDs) for users are immutable once created. This prevents spoofing or unauthorized changes to user identities. </li> Fallback Mechanisms: The system provides fallback mechanisms for fetching avatars. If a dApp-specific avatar is not found, the default avatar is returned, ensuring smooth operation without errors. </li> Upgradeable Contracts: Proxy contracts are used to allow for upgrades while preserving state. Upgrades are performed securely via a multi-signature governance process to minimize risks. </li> Rate Limiting: Rate-limiting mechanisms can be implemented to prevent spam or abuse of profile creation and update functions. </li> Audits and Best Practices: The contracts are designed following best practices and are to be audited regularly by independent security firms. Dependencies (e.g., OpenZeppelin contracts) are reviewed and kept up to date to mitigate vulnerabilities. </li> dApp Address Verification: All dApps interacting with the system must be identified by a valid address. This ensures that unauthorized or spoofed entities cannot manipulate profiles or fetch restricted data. </li> Phishing Mitigation: User-facing dApps are encouraged to clearly display information about interactions on-chain. Users should be warned about potential phishing attacks and advised to interact only with verified dApps. </li> Gas Optimization: Operations are optimized to prevent gas exhaustion during execution, which could lead to incomplete transactions. This ensures that even on congested networks, the system remains functional. </li> Secure Fallback Functions: Fallback functions are implemented securely to prevent accidental Ether transfers or denial-of-service attacks. </li> </ol> Copyright</h2> Copyright and related rights waived via CC0</a>. Separate Metadata Section for EOF 2024-12-06T00:00:00+00:00 Abstract</h2> Introduce a new separate metadata section to the Ethereum Object Format (EOF) that is unreachable by the code, and any changes to which does not affect the code. Motivation</h2> It is desirable to include metadata in contract's bytecode for various reasons. For instance, both the Solidity and Vyper compilers by default include the language and compiler version used to compile. Vyper (with 0.4.1) appends an integrity hash to the initcode in CBOR encoding. Solidity additionally includes the IPFS or the Swarm hash of the Solidity contract metadata.json file, and the experimental Solidity flag. The current (pre-EOF) practice is to append this CBOR encoded metadata section in the contract's runtime bytecode, followed by the 2 bytes length of the CBOR encoded bytes. Solidity ┌──────────────────────────────────────────0x0033 bytes──────────────────────────────────────────────┐ ...7265206c656e677468a2646970667358221220dceca8706b29e917dacf25fceef95acac8d90d765ac926663ce4096195952b6164736f6c634300060b0033</code></pre> This poses a problem for source code verification where the onchain bytecode is compared to the compiled bytecode of the given source code. During a contract verification, metadata sections, in particular the IPFS hash, need to be ignored and only the executional bytecode should be compared. Since pre-EOF bytecode is not structured, it is not possible to distinguish the metadata section from the executional bytecode easily. This gets even trickier in the case of factory contracts with multiple nested bytecodes, each having their own metadata sections. Verifiers need to implement their own heuristics and workarounds to find the metadata sections and ignore it. The EOF brings structure to the bytecode by separating the code from the data, and placing the code of each contract in their respective containers. In its current form, this makes it possible to find the data easier than the pre-EOF bytecode. However, the current spec also does not describe a metadata section. Compilers currently need to place the contract metadata inside the data section which poses several problems: It is not straightforward to distinguish the metadata part in the data_section</code>, which poses the same problem as the pre-EOF bytecode.</li> Any change to the metadata's size within the data section will change the executional bytecode, e.g. through shifting DATALOADN</code> offsets. With that, two identical contracts with different metadata sizes will not match during source code, since the code will be different.</li> The metadata can theoretically be reached by the code, e.g. via manipulating the DATALOADN</code> instructions.</li> </ol> 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. Extending the format introduced in EIP-3540</a>, this EIP proposes to add a new OPTIONAL section in the body called metadata_section</code> before the data_section</code>, and to add two new OPTIONAL fields kind_metadata</code> (value: 0x05</code>) and metadata_size</code> to the header before the kind_data</code> and data_size</code> fields. container := header, body header := magic, version, kind_type, type_size, kind_code, num_code_sections, code_size+, [kind_container, num_container_sections, container_size+,] [kind_metadata, metadata_size,] kind_data, data_size, terminator body := types_section, code_section+, container_section, [metadata_section], data_section types_section := (inputs, outputs, max_stack_increase)+</code></pre>Header</h3> name</th> length</th> value</th> description</th></tr></thead> ...</td> ...</td> ...</td> ...</td></tr> kind_metadata</td> 1 byte</td> 0x05</td> kind marker for metadata size section</td></tr> metadata_size</td> 2 bytes</td> 0x0001-0xFFFF</td> 16-bit unsigned big-endian integer denoting the length of the metadata section content</td></tr> kind_data</td> 1 byte</td> 0xff</td> kind marker for data size section</td></tr> data_size</td> 2 bytes</td> 0x0000-0xFFFF</td> 16-bit unsigned big-endian integer denoting the length of the data section content ()</td></tr> terminator</td> 1 byte</td> 0x00</td> marks the end of the header</td></tr> </tbody></table> Body</h3> name</th> length</th> value</th> description</th></tr></thead> ...</td> ...</td> ...</td> ...</td></tr> metadata_section</td> variable</td> n/a</td> arbitrary sequence of bytes</td></tr> data_section</td> variable</td> n/a</td> arbitrary sequence of bytes</td></tr> </tbody></table> The structure and the encoding of the metadata_section</code> is not defined by this EIP. It is left to the compilers, tooling, or the contract developers to define the encoding and the content. The current practice by the Solidity and Vyper compilers is to use CBOR encoding. Rationale</h2> The metadata_section</code> in the body</code>, as well as the kind_metadata</code> and metadata_size</code> fields in the header</code>, are OPTIONAL. This way, the compilers can avoid additional bytes in the container if they don't want to write any metadata. The data_section</code> can change in its size and content during deployment, therefore it needs to be REQUIRED, even if the data is empty. The metadata_section</code> is not expected to change during the deployment. The reason for placing the metadata_section</code> before the data_section</code>, and assigning kind_metadata</code> the value 0x05</code> (and not 0x04</code>) is to make it easier for the existing EOF tooling adapt the changes. Additionally, if the metadata_section</code> was placed after the data_section</code>, changes to the data_section</code> in deploy time would cause the metadata_section</code> to shift. By placing the metadata_section</code> before, this could be mitigated. Backwards Compatibility</h2> No backward compatibility issues are expected since EIP-3540</a> is not implemented yet. Security Considerations</h2> No security considerations as this section is meant not to be executed. Copyright</h2> Copyright and related rights waived via CC0</a>. Data Asset NFT 2024-11-29T00:00:00+00:00 Abstract</h2> This proposal extends the ERC-721</a> standard to support Data Assets which refers to digital products created by creators. This proposal introduces a modular Data Availability (DA) layer that safeguards on-chain data integrity, preventing value discrepancies caused by off-chain data loss, tampering, or expiration. Furthermore, this proposal introduces a new role, Reader, where a single token can have multiple Readers. This solution reflects the inherent replicability of Data Assets, namely that each piece of data can be replicated multiple times and accessed by multiple users, thus amplifying the value of the Data Assets. Motivation</h2> ERC-721 proposed NFTs to represent the ownership of digital or physical assets. Currently, the NFT metadata is considered the NFT content, and its scarcity determines the value of the NFT. NFT owners can convert the content value of NFTs into revenue by transferring the ownership of NFTs. However, due to the high transaction fees, storage costs, and other expenses, NFTs are currently only able to represent the ownership of high-value assets, which limits the range of assets that NFTs can represent. This is especially true for Data Assets, which refers to digital products created by creators, such as online blogs, videos, small games or music. Therefore, the value of Data Assets depends on their quality, whether the creator is famous, whether it is hyped and so on. Furthermore, to reduce storage costs, the NFT content is generally stored off-chain or using cross-chain storage, and the link of NFT content is saved on-chain. Off-chain users can access the NFT content by visiting the link. However, on-chain contracts can not access the link to determine the status of the data, such as data loss, data tampering, or data expiration. These situations can lead to the data deviating from its actual value, but the NFT still exists on the chain, and the underlying copyright is still being sold in the market. This proposal introduces Data Asset NFTs, which solve the dilemma of on-chain Data Assets by combining a modular data layer--Data Availability (DA). Related Work</h3> There are Existing proposals to NFT integrity, but each proposal contains at least one of these limitations: Storing NFT content on-chain, which requires the underlying data asset to possess inherent speculative value to justify prohibitive storage costs.</li> Requiring attestations from a trusted third party, while introduces centralized trust issue.</li> </ul> Specification</h2> Terms</h3> In this proposal, we divide data assets into three parts: Storage Metadata: Includes commitment, size, expire, and uploader's address. Stored and maintained by storage contracts on the blockchain.</li> Permission Metadata: Includes information on ownership and reading rights, as well as which addresses can modify this information. Stored and maintained by permission contracts on the blockchain.</li> Data Content: Data uploaded by users to the storage system. Data content is stored in off-chain storage nodes.</li> </ul> Every compliant data permission contract must implement the Interface: The data permission contract is an extension of ERC-721, adding the reader role, where a single data asset can correspond to multiple readers. interface IERC7829 is IERC721 { event UpdateReader(uint256 indexed tokenId, address indexed reader, bool valid); function setReader(uint256 tokenId, address reader, bool valid) external; function isReader(uint256 tokenId, address reader) external view returns (bool); function commitByTokenId(uint256 tokenId) external view returns (bytes); function sizeByTokenId(uint256 tokenId) external view returns (uint256); function expireByTokenId(uint256 tokenId) external view returns (uint64); }</code></pre> The metadata JSON schema for Data Asset NFTs is as follows: { "title": "Data Asset Metadata", "type": "object", "properties": { "name": { "type": "string", "description": "Identifies the asset to which this NFT represents" }, "description": { "type": "string", "description": "Describes the asset to which this NFT represents" }, "commit": { "type": "string", "description": "A commit pointing to the data resource" }, "size": { "type": "integer", "description": "The size of the data resource" }, "expire": { "type": "integer", "description": "The expire time of the data resource", } } }</code></pre> The Reader role should not involve changes in permissions, meaning that Readers cannot call functions such as transfer</code>, approve</code>, setApprovalForAll</code>, and setReader</code>. When Alice calls the transfer</code> function to transfer one of Alice's Data Asset NFTs to Bob: The owner address is set to Bob's address;</li> The approved address is set to 0.</li> However, all readers are retained.</li> </ul> Extension: Storage Contract</h3> This proposal extends the metadata information of NFTs. Metadata information is uploaded by users and requires relevant certificates, which can be the storage node's signature on the NFT's metadata information. This proposal specify that the NFT metadata should at least include commitment, size, expire, and uploader's address. The implementer of this proposal selects a trusted storage system and a trusted modular data layer DA, or deploys the modular storage layer DA themselves. When the Owner or Approved Operator calls the transfer</code>, approve</code>, or setReader</code> functions, they must additionally check whether the current time block.timestamp</code> is greater than the expiration time expire</code> before making the call. If the current time block.timestamp</code> is less than the expiration time expire</code>, then proceed with subsequent operations; if the current time block.timestamp</code> is greater than the expiration time expire</code>, then interrupt subsequent operations and return an exception message. Extension: Storage Proof</h3> This proposal uses storage proof to prove the availability of data content, thereby proving the correctness of NFT metadata, especially the expire</code> of the NFT. This proposal does not limit the proof scheme used, but recommends the use of KZG polynomial commitment technology. KZG polynomial commitment technology can generate two generator elements $g_1$ and $g_2$ during initialization. It also generates a corresponding commitment C based on the data content and uploads it as the unique identifier of the data when uploading metadata. When generating proof, the verifier generates a random number $z$, and the prover generates proof $P=(y, π)$ based on the data content and random number $z$, verifying $e(π, yg_1-zg_2) = e(C - yg_1, g_2)$. In addition, KZG polynomial commitment technology can aggregate multiple proofs into a single proof, and two-step verification can verify the correctness of all proofs, including summing all commitments to get the aggregated commitment $C_n$, and verifying the aggregated proof $P_n=(y_n, π_n)$ by verifying $e(π_n, y_ng_1-zg_2) = e(C_n - y_ng_1, g_2)$. To avoid long proof generation times, random sampling can be used to randomly select data to be challenged. Therefore, the contract needs to provide a secure pseudo-random number generation function for randomly selecting challenged data, which can also be used as the random number $z$ for KZG. During the verification process, summing all commitments to get the aggregated commitment requires a large amount of gas fees. This proposal recommends using optimistic proof, which assumes that the aggregated commitment is correct and only verifies $e(π_n, y_ng_1-zg_2) = e(C_n - y_n*g_1, g_2)$ during verification. After verifying the aggregated proof, the availability of the data cannot be proven, so a certain period of challenging is required. During the challenging period, anyone can challenge the commitment proof $C_n$. If the challenge is successful, the challenger gets a reward and the prover is punished; if the challenge fails, the challenger is punished and the prover gets additional benefits. Rationale</h2> Data Asset NFT Integrity</h3> The DA Layer is responsible for off-chain storage of Data Content and on-chain storage of Storage Metadata, and ensures the integrity of Data Assets through periodically submiting and verifing storage proofs. To optimize gas costs, we adopt an optimistic proof approach, significantly reducing verification expenses. Proof Cycle Workflow: Proof Generation & Aggregation: The DA Provider generates storage proofs for sampled data content, aggregates them into a single aggregated proof, and submits it to the DA Contract.</li> The DA Contract verifies the correctness of the aggregated proof.</li> </ul> </li> Fraud Proof Mechanism: The DA Verifier performs off-chain validation to confirm whether the aggregated proof was correctly derived from the selected data.</li> If the proof is invalid, the verifier challenges it by submitting a fraud proof to the DA Contract.</li> </ul> </li> </ol> Reader</h3> This proposal enables a single data asset NFT to have multiple Readers, each granted access to the off-chain data content. This design aligns with the inherent properties of data assets: Replicability: Data can be copied and distributed without degradation.</li> Value Amplification: By allowing resale or multi-party access, the asset’s utility and market value increase.</li> </ul> Backwards Compatibility</h2> This proposal combines the existing ERC-721 extension and is backward compatible with the ERC-721 standard. Security Considerations</h2> The security of Data Asset NFTs depends not only on the blockchain but also on the modular data layer DA. Therefore, the implementer of this proposal needs to carefully select the modular data layer DA. Copyright</h2> Copyright and related rights waived via CC0</a>. ZK Identity Registry 2024-11-08T00:00:00+00:00 Abstract</h2> This EIP introduces an on-chain registry Motivation</h2> This EIP stemmed from the need to localize The aggregation of provable statements The given proposal lays the important Specification</h2> The keywords "MUST", "MUST NOT", "REQUIRED", Definitions</h3> A "Sparse Merkle Tree (SMT)" is a A "statement" is an accepted structured A "commitment" is a special public A "commitment key" is a private salt </ul> General</h3> The on-chain registry system consists The on-chain evidence registry system The EvidenceRegistry</code> In order to prove that certain data The Circom implementation of a general-purpose Evidence DB</h3> The EvidenceDB</code> smart For reference, the EvidenceDB</code> }< <& <& }< The EvidenceRegistry</code> }< The addStatement</code>, The EvidenceRegistry</code> Before communicating with the Evidence Where the hash</code> is Hash Function</h3> The same secure hash function MUST In case ZK-friendly hash function is Rationale</h2> During the EIP specification we have Cross-chain portability. Only a single Centralization of trust. Users only Integration streamline. The singleton </ol> The proposal is deliberately written It is expected that based on this work The EvidenceDB</code> namespacing The EvidenceRegistry</code> Backwards This EIP is fully backwards compatible.< Deployment The EvidenceRegistry</code> Reference The reference implementation of Eviden The low-level Solidity and Circom implementations The height of the SMT is set to 80<&#x Please note that the reference implementation </blockquote> EvidenceDB SparseMerkleTr }< _evidenceRegistry _tree< _tree< }< _tree< }< _tree< }< _tree< }< }< }< }< }< }< }< }</sp }< }< ) }< }< IEvidenceDB }< _rootTimes }< _evidenceDB }< ) }</sp _evidenceD }< }</sp _evidenceD }< ) }</sp _evidenceD }< }</sp }</sp }< }< }< }</sp }< }< include template signal signal signal component hasher</s hasher</s hasher</s }< template signal signal signal signal signal signal signal signal signal component isolatedKey<&# isolatedKey<&# component smtVerifier<&# smtVerifier<&# smtVerifier<&# smtVerifier<&# smtVerifier<&# smtVerifier<&# smtVerifier<&# smtVerifier<&# }< component From security standpoint there are The individual registrars are expected The getRoot</code> method Copyright</h2> Copyright and related rights waived Store, Table-Based Introspectable 2024-11-08T00:00:00+00:00 system for storing and proving abstract statements. Users may utilize the system to store commitments to their private data to later prove its validity and authenticity via zero knowledge, without disclosing anything about the data itself. Moreover, developers may use the singleton EvidenceRegistry</code> contract available at 0x781246D2256dc0C1d8357c9dDc1eEe926a9c7812</code> to integrate custom business-specific registrars for managing and processing particular statements. and unravel the storage and issuance of provable statements so that future protocols can anchor to the standardized singleton on-chain registry and benefit from cross-reuse. significantly improves reusability, portability, and security of the abundance of zero knowledge privacy-oriented solutions. The abstract specification of the registry allows custom indentity-based, reputation-based, proof-of-attendance-based, etc., protocols to be implemented with little to minimal constraints. foundation for specific solution to build upon. The more concrete specifications of statements and commitments structures are expected to emerge as separate, standalone EIPs. "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. special Merkle tree that works by deterministically and idempotently storing key/value pairs in the given locations leveraging a hash function. The Poseidon hash function is often used to optimize the compatibility with ZK.</li> representation of some abstract evidence. A statement can range from a simple string</code> to a Merkle root of some SMT.</li> value resulting from blinding a statement to conceal it. Commitments allow the authenticity of a statement to be proven in ZK without disclosing the statement itself.</li> mixed with the statement to obtain a commitment to that statement. The commitment key must be kept private to maintain the confidentiality of statements.</li> of two subsystems: the EvidenceRegistry</code> with EvidenceDB</code> and Registrar</code> components. This EIP will focus on describing and standardizing the former, while the Registrar</code> specification may be amended as the separate proposals. entities diagram. acts as the entrypoint to a protocol-wide provable database EvidenceDB</code> where arbitrary 32-byte</code> data can be written to and later proven on demand. The Registrar</code> entities implement specific business use cases, structure the provable data, and utilize EvidenceRegistry</code> to put this data in the EvidenceDB</code>. is or is not present in the EvidenceDB</code> Merkle proofs may be used. Understanding how a specific Registrar</code> has structured and put data into the EvidenceDB</code>, one may implement an on-chain ZK verifier (using Circom or any other stack) and prove the inclusion (or exclusion) of the data in the database. SMT-driven EvidenceDB</code> verifier circuit together with the Solidity implementation of EvidenceRegistry</code> and EvidenceDB</code> smart contracts may be found in the "Reference Implementation" section. contract MAY implement an arbitrary provable key/value data structure, however it MUST support the addition</code>, update</code>, and removal</code> of elements. All of the supported write operations MUST maintain the property of idempotence (e.i. addition</code> followed by removal</code> should not change the state of the database). The data structure of choice MUST be capable of providing both element inclusion and exclusion proofs. The functions that modify the EvidenceDB</code> state MUST be callable only by the EvidenceRegistry</code>. smart contract MAY implement the following interface: class="giallo-l">pragma solidity ^0.8.0; /** * @notice Evidence DB interface for Sparse Merkle Tree based statements database. */ z-type">interface IEvidenceDB { /** * @notice Represents the proof of a node's inclusion/exclusion in the tree. * @param root The root hash of the Merkle tree. * @param siblings An array of sibling hashes can be used to get the Merkle Root. * @param existence Indicates the presence (true) or absence (false) of the node. * @param key The key associated with the node. * @param value The value associated with the node. * @param auxExistence Indicates the presence (true) or absence (false) of an auxiliary node. * @param auxKey The key of the auxiliary node. * @param auxValue The value of the auxiliary node. */ struct Proof { bytes32 root; bytes32[] siblings; bool existence; bytes32 key; bytes32 value; bool auxExistence; bytes32 auxKey; bytes32 auxValue; /span> #x2F;span> /** * @notice Adds the new element to the tree. */ function add(bytes32 key, bytes32 value) external; /** * @notice Removes the element from the tree. */ function remove(bytes32 key) external; /** * @notice Updates the element in the tree. */ function update(bytes32 key, bytes32 newValue) external; /** * @notice Gets the SMT root. * SHOULD NOT be used on-chain due to roots frontrunning. */ function getRoot() external view returns (bytes32); /** * @notice Gets the number of nodes in the tree. */ function getSize() external view returns (uint256); #x2F;span> /** * @notice Gets the max tree height (number of branches in the Merkle proof) */ function getMaxHeight() external view returns (uint256); /** * @notice Gets Merkle inclusion/exclusion proof of the element. */ function getProof(bytes32 key) external view returns (Proof memory); /** * @notice Gets the element value by its key. */ function getValue(bytes32 key) external view returns (bytes32); F;span></code></pre>Evidence Registry</h3> smart contract is the central piece of this EIP. The EvidenceRegistry</code> MUST implement the following interface, however, it MAY be extended: class="giallo-l">pragma solidity ^0.8.0; /** * @notice Common Evidence Registry interface. */ z-type">interface IEvidenceRegistry { /** * @notice MUST be emitted whenever the Merkle root is updated. */ event RootUpdated(bytes32 indexed prev, bytes32 indexed curr); /** * @notice Adds the new statement to the DB. */ function addStatement(bytes32 key, bytes32 value) external; /** * @notice Removes the statement from the DB. */ function removeStatement(bytes32 key) external; /** * @notice Updates the statement in the DB. */ function updateStatement(bytes32 key, bytes32 newValue) external; /** * @notice Retrieves historical DB roots creation timestamps. * Latest root MUST return `block.timestamp`. * Non-existent root MUST return `0`. */ function getRootTimestamp(bytes32 root) external view returns (uint256); /** * @notice Builds and returns the isolated key for `source` and given `key`. */ function getIsolatedKey(address source, bytes32 key) external view returns (bytes32); F;span></code></pre> removeStatement</code>, and updateStatement</code> methods MUST isolate the statement key</code> in order for the database to allocate a specific namespace for a caller. These methods MUST revert in case the isolated key being added already exists in the EvidenceDB</code> or the isolated key being removed or updated does not. MUST maintain the linear history of EvidenceDB</code> roots. The getRootTimestamp</code> method MUST NOT revert. Instead, it MUST return 0</code> in case the queried root</code> does not exist. The method MUST return block.timestamp</code> in case the latest root is requested. DB</code>, the key</code> MUST be isolated in the following way: class="giallo-l">bytes32 isolatedKey = hash(msg.sender, key)</code></pre> secure protocol-wide hash function of choice. be employed in both EvidenceRegistry</code> and EvidenceDB</code>. It is RECOMMENDED to use ZK-friendly hash function such as poseidon</code> to streamline the database proving. chosen, EvidenceRegistry</code> MUST NOT accept keys</code> or values</code> beyond the underlying elliptic curve prime field size (21888242871839275222246405745257275088548364400416034343698204186575808495617</code> for BN128</code>). considered two approaches: where every protocol has its own registry and where all protocols are united under a singleton registry. We have decided to go with the latter as this approach provides the following benefits: bytes32</code> value (the SMT root) has to be sent cross-chain to be able to prove the state of the registry.</li> need to trust a single, permissionaless, immutable smart contract.</li> design formalizes the system interface, the hash function, and the overall proofs structure to simplify the integration.</li> as abstract as possible to not constrain the possible business use cases and allow Registrars</code> to implement arbitrary provable solutions. future EIPs will describe concrete registrars with the exact procedures of generation of commitments, management of commitment keys, and proving of operated statements. For instance, there may be a registrar for on-chain accounting of national passports, a registrar with EIP-4337</a> confidential account identity management, a registrar for POAPs, etc. is chosen to segregate the write access to the database cells, ensuring that no entity but issuer can alter their content. However, this decision delegates the access control management responsibility solely to registrars, an important aspect to be considered during their development. maintains the minimal viable (gas-wise) history of roots on-chain for smooth registrars integration. In case more elaborate history is required, it is RECOMMENDED to implement off-chain services for parsing of RootUpdated</code> events. Compatibility</h2> F;p> Method</h3> is a singleton contract available at 0x781246D2256dc0C1d8357c9dDc1eEe926a9c7812</code> deployed via the "deterministic deployment proxy" from 0x4e59b44847b379578588920ca78fbf26c0b4956c</code> with the salt 0x04834e077c463de76a20df3770a7b96a5e5eb826922d1514f943cd5b41ccaed0</code>. Implementation</h2> ceRegistry</code> and EvidenceDB</code> Solidity smart contracts together with the evidence registry state verifier Circom circuit is provided in the proposal. of SMT can be found here</a> and here</a>. 2F;code>. depends on the @openzeppelin/contracts v5.1.0</code> and circomlib v2.0.5</code>. Implementation</h3> class="giallo-l">// SPDX-License-Identifier: CC0-1.0 pragma solidity ^0.8.21; import {Initializable} from "@openzeppelin/contracts/proxy/utils/Initializable.sol"; import {IEvidenceDB} from "./interfaces/IEvidenceDB.sol"; import {SparseMerkleTree} from "./libraries/SparseMerkleTree.sol"; import {PoseidonUnit2L, PoseidonUnit3L} from "./libraries/Poseidon.sol"; z-type">contract EvidenceDB is IEvidenceDB, Initializable { using SparseMerkleTree for SparseMerkleTree.SMT; address private _evidenceRegistry; ee.SMT private _tree; modifier onlyEvidenceRegistry() { _requireEvidenceRegistry(); _; /span> function __EvidenceDB_init(address evidenceRegistry_, uint32 maxDepth_) external initializer { = evidenceRegistry_; F;span>.initialize(maxDepth_); F;span>.setHashers(_hash2, _hash3); /span> /** * @inheritdoc IEvidenceDB */ function add(bytes32 key_, bytes32 value_) external onlyEvidenceRegistry { F;span>.add(key_, value_); /span> /** * @inheritdoc IEvidenceDB */ function remove(bytes32 key_) external onlyEvidenceRegistry { F;span>.remove(key_); /span> /** * @inheritdoc IEvidenceDB */ function update(bytes32 key_, bytes32 newValue_) external onlyEvidenceRegistry { F;span>.update(key_, newValue_); /span> /** * @inheritdoc IEvidenceDB */ function getRoot() external view returns (bytes32) { return _tree.getRoot(); /span> /** * @inheritdoc IEvidenceDB */ function getSize() external view returns (uint256) { return _tree.getNodesCount(); /span> /** * @inheritdoc IEvidenceDB */ function getMaxHeight() external view returns (uint256) { return _tree.getMaxDepth(); /span> /** * @inheritdoc IEvidenceDB */ function getProof(bytes32 key_) external view returns (Proof memory) { return _tree.getProof(key_); /span> /** * @inheritdoc IEvidenceDB */ function getValue(bytes32 key_) external view returns (bytes32) { return _tree.getNodeByKey(key_).value; /span> /** * @notice Returns the address of the Evidence Registry. */ function getEvidenceRegistry() external view returns (address) { return _evidenceRegistry; /span> function _requireEvidenceRegistry() private view { if (_evidenceRegistry != msg.sender) { revert NotFromEvidenceRegistry(msg.sender); an> /span> function _hash2(bytes32 element1_, bytes32 element2_) private pure returns (bytes32) { return PoseidonUnit2L.poseidon([element1_, element2_]); /span> function _hash3( bytes32 element1_, bytes32 element2_, bytes32 element3_ class="z-storage z-type"> private pure returns (bytes32) { return PoseidonUnit3L.poseidon([element1_, element2_, element3_]); /span> F;span></code></pre>EvidenceRegistry Implementation</h3> class="giallo-l">// SPDX-License-Identifier: CC0-1.0 pragma solidity ^0.8.21; import {Initializable} from "@openzeppelin/contracts/proxy/utils/Initializable.sol"; import {IEvidenceDB} from "./interfaces/IEvidenceDB.sol"; import {IEvidenceRegistry} from "./interfaces/IEvidenceRegistry.sol"; import {PoseidonUnit2L} from "./libraries/Poseidon.sol"; z-type">contract EvidenceRegistry is IEvidenceRegistry, Initializable { uint256 public constant BABY_JUB_JUB_PRIME_FIELD = 21888242871839275222246405745257275088548364400416034343698204186575808495617; private _evidenceDB; mapping(bytes32 => uint256) private _rootTimestamps; modifier onlyInPrimeField(bytes32 key) { _requireInPrimeField(key); _; /span> modifier onRootUpdate() { bytes32 prevRoot_ = _evidenceDB.getRoot(); tamps[prevRoot_] = block.timestamp; _; emit RootUpdated(prevRoot_, _evidenceDB.getRoot()); /span> function __EvidenceRegistry_init(address evidenceDB_) external initializer { = IEvidenceDB(evidenceDB_); /span> /** * @inheritdoc IEvidenceRegistry */ function addStatement( bytes32 key_, bytes32 value_ class="z-storage z-type"> external onlyInPrimeField(key_) onlyInPrimeField(value_) onRootUpdate { bytes32 isolatedKey_ = getIsolatedKey(msg.sender, key_); if (_evidenceDB.getValue(isolatedKey_) != bytes32(0)) { revert KeyAlreadyExists(key_); an> B.add(isolatedKey_, value_); /span> /** * @inheritdoc IEvidenceRegistry */ function removeStatement(bytes32 key_) external onlyInPrimeField(key_) onRootUpdate { bytes32 isolatedKey_ = getIsolatedKey(msg.sender, key_); if (_evidenceDB.getValue(isolatedKey_) == bytes32(0)) { revert KeyDoesNotExist(key_); an> B.remove(isolatedKey_); /span> /** * @inheritdoc IEvidenceRegistry */ function updateStatement( bytes32 key_, bytes32 newValue_ class="z-storage z-type"> external onlyInPrimeField(key_) onlyInPrimeField(newValue_) onRootUpdate { bytes32 isolatedKey_ = getIsolatedKey(msg.sender, key_); if (_evidenceDB.getValue(isolatedKey_) == bytes32(0)) { revert KeyDoesNotExist(key_); an> B.update(isolatedKey_, newValue_); /span> /** * @inheritdoc IEvidenceRegistry */ function getRootTimestamp(bytes32 root_) external view returns (uint256) { if (root_ == bytes32(0)) { return 0; an> if (root_ == _evidenceDB.getRoot()) { return block.timestamp; an> return _rootTimestamps[root_]; /span> /** * @inheritdoc IEvidenceRegistry / function getIsolatedKey(address source_ bytes32 key_) public pure returns (bytes32) { return PoseidonUnit2L.poseidon([bytes32(uint256(uint160(source_))), key_]); /span> function getEvidenceDB() external view returns (address) { return address(_evidenceDB); /span> function _requireInPrimeField(bytes32 key_) private pure { if (uint256(key_) >= BABY_JUB_JUB_PRIME_FIELD) { revert NumberNotInPrimeField(key_); an> /span> F;span></code></pre>EvidenceRegistry Verifier Implementation</h3> class="giallo-l">// LICENSE: CC0-1.0 pragma circom 2.1.9; class="z-string">"SparseMerkleTree.circom"; BuildIsolatedKey() { output isolatedKey; input address; input key; hasher = Poseidon(2); pan>.inputs[0] <== address; pan>.inputs[1] <== key; pan>.out ==> isolatedKey; F;span> EvidenceRegistrySMT(levels) { // Public Inputs input root; // Private Inputs input address; input key; input value; input siblings[levels]; input auxKey; input auxValue; input auxIsEmpty; input isExclusion; // Build isolated key isolatedKey = BuildIsolatedKey(); x2F;span>.address <== address; x2F;span>.key <== key; // Verify Sparse Merkle Tree Proof smtVerifier = SparseMerkleTree(levels); x2F;span>.siblings <== siblings; x2F;span>.key <== isolatedKey.isolatedKey; x2F;span>.value <== value; x2F;span>.auxKey <== auxKey; x2F;span>.auxValue <== auxValue; x2F;span>.auxIsEmpty <== auxIsEmpty; x2F;span>.isExclusion <== isExclusion; x2F;span>.root <== root; F;span> main {public [root]} = EvidenceRegistrySMT(80);</code></pre>Security Considerations</h2> several important aspects that must be highlighted. to provide the functionality for both management and proving of statements. The proving will often be carried out by ZK proofs, which require trusted setup. Improperly setup ZK verifiers can be exploited to verify forged proofs. of EvidenceDB</code> SHOULD NOT be used on-chain by the integrating registrars to check the validity of the database state. Instead, the required root</code> SHOULD be passed as a function parameter and checked via getRootTimestamp</code> method to avoid being frontrun. via CC0</a>. Storage Abstract</h2> This standard introduces a flexible on-chain storage pattern that organizes data into structured tables that consist of records with fixed key and value schemas, similar to a traditional database. This storage pattern consists of a unified contract interface for data access, along with a compact binary encoding format for both static and dynamic data types. State changes are tracked through standardized events that enable automatic, schema-aware state replication by off-chain indexers. New tables can be dynamically registered at runtime through a special table that stores schema metadata for all tables, allowing the system to evolve without breaking existing contracts or integrations. Motivation</h2> The absence of consistent standards for on-chain data management in smart contracts can lead to rigid implementations, tightly coupled contract logic with off-chain services, and challenges in updating or extending a contract’s data layout without breaking existing integrations. Using the storage mechanism defined in this ERC provides the following benefits: Automatic Indexing: By emitting consistent, standardized events during state changes, off-chain services can automatically track on-chain state and provide schema-aware indexer APIs.</li> Elimination of Custom Getter Functions: Any contract or off-chain service can read stored data through a consistent interface, decoupling smart contract implementation from specific data access patterns and reducing development overhead.</li> Simpler Upgradability: This pattern leverages unstructured storage, making it easier to upgrade contract logic without the risks associated with using a fixed storage layout.</li> Flexible Data Extensions: New tables can be added at runtime without without breaking existing integrations with other data consumers.</li> Reduced gas costs: Using efficient data packing reduces gas costs for both storage and event emissions.</li> </ol> Specification</h2> Definitions</h3> Store</h4> A smart contract that implements the interface proposed by this ERC and organizes data in Tables. It emits events for each data operation so that off-chain components can replicate the state of all tables. Table</h4> A storage structure that holds Records sharing the same Schema. On-chain Table: Stores its state on-chain and emits events for off-chain- indexers.</li> Off-chain Table: Does not store state on-chain but emits events for off-chain indexers.</li> </ul> Record</h4> A piece of data stored in a Table, addressed by one or more keys. ResourceId</code></h4> A 32-byte value that uniquely identifies each Table within the Store. type ResourceId is bytes32;</code></pre> Encoding: Bytes (from left to right)</th> Description</th></tr></thead> 0-1</td> Table type identifier</td></tr> 2-31</td> Unique identifier</td></tr> </tbody></table> Table Type Identifiers: 0x7462</code> ("tb"</code>) for on-chain tables</li> 0x6f74</code> ("ot"</code>) for off-chain tables</li> </ul> Schema</code></h4> Used to represent the layout of Records within a table. type Schema is bytes32;</code></pre> Each Table defines two schemas: Key Schema: the types of the keys used to uniquely identify a Record within a table. It consists only of fixed-length data types.</li> Value Schema: the types of the value fields of a Record within a table, which can include both fixed-length and variable-length data types.</li> </ul> Byte(s) from left to right</th> Value</th> Constraint</th></tr></thead> 0-1</td> Total byte length of static fields</td> </td></tr> 2</td> Number of static length fields</td> ≤ (28 - number of dynamic length fields)</td></tr> 3</td> Number of dynamic length fields</td> For the key schema, 0</td></tr> For the value schema, ≤5</td> </td> </td></tr> 4-31</td> Each byte encodes a SchemaType</code></td> Dynamic-length types MUST come after all the static-length types.</td></tr> </tbody></table> SchemaType</code></h4> Single byte that represents the type of a specific static or dynamic field. enum SchemaType { ... }</code></pre> Type Encoding: Value Range</th> Type</th></tr></thead> 0x00</code> to 0x1F</code></td> uint8</code> to uint256</code> (increments of 8 bits)</td></tr> 0x20</code> to 0x3F</code></td> int8</code> to int256</code> (increments of 8 bits)</td></tr> 0x40</code> to 0x5F</code></td> bytes1</code> to bytes32</code></td></tr> 0x60</code></td> bool</code></td></tr> 0x61</code></td> address</code></td></tr> 0x62</code> to 0x81</code></td> uint8[]</code> to uint256[]</code></td></tr> 0x82</code> to 0xA1</code></td> int8[]</code> to int256[]</code></td></tr> 0xA2</code> to 0xC1</code></td> bytes1[]</code> to bytes32[]</code></td></tr> 0xC2</code></td> bool[]</code></td></tr> 0xC3</code></td> address[]</code></td></tr> 0xC4</code></td> bytes</code></td></tr> 0xC5</code></td> string</code></td></tr> </tbody></table> FieldLayout</code></h4> Encodes the concrete value Schema</code> information, specifically the total byte length of the static fields, the number of dynamic fields and the length of each static field on its own. This encoding serves as an optimization for on-chain operations. By having the exact lengths readily available, the Store doesn't need to repeatedly compute or translate the schema definitions into actual field lengths during execution. type FieldLayout is bytes32;</code></pre>Byte(s) from left to right</th> Value</th> Constraint</th></tr></thead> 0-1</td> Total length of static fields</td> </td></tr> 2</td> Number of static length fields</td> ≤ (28 - number of dynamic length fields)</td></tr> 3</td> Number of dynamic length fields</td> For the key schema, 0</td></tr> For the value schema, ≤5</td> </td> </td></tr> 4-31</td> Each byte encodes the byte length of the corresponding static field</td> </td></tr> </tbody></table> EncodedLengths</code></h4> Encodes the byte length of all the dynamic fields of a specific Record. It is returned by the Store methods when reading a Record, as it is needed for decoding dynamic fields. type EncodedLengths is bytes32;</code></pre>Bytes (from least to most significant)</th> Type</th> Description</th></tr></thead> 0x00-0x06</td> uint56</td> Total byte length of dynamic data</td></tr> 0x07-0xB</td> uint40</td> Length of the first dynamic field</td></tr> 0x0C-0x10</td> uint40</td> Length of the second dynamic field</td></tr> 0x11-0x15</td> uint40</td> Length of the third dynamic field</td></tr> 0x16-0x1A</td> uint40</td> Length of the fourth dynamic field</td></tr> 0x1B-0x1F</td> uint40</td> Length of the fifth dynamic field</td></tr> </tbody></table> Packed Data Encoding</h3> Record data returned by Store methods and included in Store events uses the following encoding rules. Field Limits</h4> Maximum Total Fields: A record can contain up to 28 fields in total (both static and dynamic fields combined). This limit is due to the Schema</code> type structure, which uses 28 bytes (bytes 4 to 31) to define field types, with one byte per field (SchemaType</code>).</li> </ul> </li> Dynamic Fields Limit: A record can have up to 5 dynamic fields. This is due to the fact that a single 32 bytes word (EncodedLengths</code>) to encode the byte lengths of each dynamic field, instead of encoding each length separately as Solidity’s abi.encode</code> would.</li> </ul> </li> Static Fields Limit: The maximum number of static fields is 28 minus the number of dynamic fields. For example, if there are 5 dynamic fields, the maximum number of static fields is 23 (28 - 5).</li> </ul> </li> </ul> Encoding Rules</h4> Static-length fields are encoded without any padding, and concatenated in the order they are defined in the schema, which is equivalent to using Solidity's abi.encodePacked</code>.</li> For dynamic-length fields (arrays, bytes</code>, and string</code>s): If the field is an array, its elements are tightly packed without padding.</li> All dynamic fields are concatenated together without padding and without including their lengths.</li> The lengths of all dynamic fields are encoded into a single EncodedLengths</code>.</li> </ul> </li> </ul> Example</h4> Suppose a table has the following value schema: (uint256 id, address owner, string description, uint8[] scores)</code></pre> Encoding (Pseudocode): bytes memory staticData = abi.encodePacked(id, owner); // This is a custom function as Solidity does not provide a way to tightly pack array elements bytes memory packedScores = packElementsWithoutPadding(scores); // abi.encodePacked concatenates both description and packedScores without including their lengths bytes memory dynamicData = abi.encodePacked(description, packedScores); // Total length is encoded in the 56 least significant bits EncodedLengths encodedLengths = dynamicData.length; // Each length is encoded using 5 bytes encodedLengths |= (description.length << (56)); encodedLengths |= (encodedData.length << (56 + 8 5)); // The full encoded record data is represented by the following tuple: // (staticData, encodedLengths, dynamicData)</code></pre>Store Interface</h3> All Stores MUST implement the following interface. interface IStore { /** * Get full encoded record (all fields, static and dynamic data) for the given tableId and key tuple. */ function getRecord( ResourceId tableId, bytes32[] calldata keyTuple ) external view returns (bytes memory staticData, EncodedLengths encodedLengths, bytes memory dynamicData); /** * Get a single encoded field from the given tableId and key tuple. */ function getField( ResourceId tableId, bytes32[] calldata keyTuple, uint8 fieldIndex ) external view returns (bytes memory data); /** * Get the byte length of a single field from the given tableId and key tuple / function getFieldLength( ResourceId tableId, bytes32[] memory keyTuple, uint8 fieldIndex ) external view returns (uint256); }</code></pre> The return values of both getRecord</code> and getField</code> use the encoding rules previously defined in the Packed Data Encoding section. More specifically, getRecord</code> returns the fully encoded record tuple, and the data returned by getField</code> is encoded using the encoding rules as if the field was being encoded on its own. Store Operations and Events</h3> This standard defines three core operations for manipulating records in a table: setting, updating, and deleting. For each operation, specific events must be emitted. The implementation details of these operations are left to the discretion of each Store implementation. The fundamental requirement is that for on-chain tables the Record data retrieved through the Store interface methods at any given block MUST be consistent with the Record data that would be obtained by applying the operations implied by the Store events up to that block. This ensures data integrity and allows for accurate off-chain state reconstruction. Store_SetRecord</h4> Setting a Record means overwriting all of its fields. This operation can be performed whether the record has been set before or not (the standard does not enforce existence checks). The Store_SetRecord</code> event MUST be emitted whenever the full data of a record has been overwritten. event Store_SetRecord( ResourceId indexed tableId, bytes32[] keyTuple, bytes staticData, EncodedLengths encodedLengths, bytes dynamicData );</code></pre> Parameters: Name</th> Type</th> Description</th></tr></thead> tableId</td> ResourceId</td> The ID of the table where the record is set</td></tr> keyTuple</td> bytes32[]</td> An array representing the composite key for the record</td></tr> staticData</td> bytes</td> The static data of the record using packed encoding</td></tr> encodedLengths</td> EncodedLengths</td> The encoded lengths of the dynamic data of the record</td></tr> dynamicData</td> bytes</td> The dynamic data of the record, using custom packed encoding</a></td></tr> </tbody></table> Store_SpliceStaticData</h4> Splicing the static data of a Record consists in overwriting bytes of the packed encoded static fields. The total length of static data does not change as it is determined by the table’s value schema. The Store_SpliceStaticData</code> event MUST be emitted whenever the static data of the Record has been spliced. event Store_SpliceStaticData( ResourceId indexed tableId, bytes32[] keyTuple, uint48 start, bytes data );</code></pre> Parameters: Name</th> Type</th> Description</th></tr></thead> tableId</td> ResourceId</td> The ID of the table where the data is spliced</td></tr> keyTuple</td> bytes32[]</td> An array representing the key for the record</td></tr> start</td> uint48</td> The start position in bytes for the splice operation</td></tr> data</td> bytes</td> Packed ABI encoding of a tuple with the value's static fields</td></tr> </tbody></table> Store_SpliceDynamicData</h4> Splicing the dynamic data of a Record involves modifying the packed encoded representation of its dynamic fields by removing, replacing, and/or inserting new bytes in place. The Store_SpliceDynamicData</code> event MUST be emitted whenever the dynamic data of the Record has been spliced. event Store_SpliceDynamicData( ResourceId indexed tableId, bytes32[] keyTuple, uint8 dynamicFieldIndex, uint48 start, uint40 deleteCount, EncodedLengths encodedLengths, bytes data );</code></pre> Parameters: Name</th> Type</th> Description</th></tr></thead> tableId</td> ResourceId</td> The ID of the table where the data is spliced</td></tr> keyTuple</td> bytes32[]</td> An array representing the composite key for the record</td></tr> dynamicFieldIndex</td> uint8</td> The index of the dynamic field to splice data, relative to the start of the dynamic fields (Dynamic field index = field index - number of static fields)</td></tr> start</td> uint48</td> The start position in bytes for the splice operation</td></tr> deleteCount</td> uint40</td> The number of bytes to delete in the splice operation</td></tr> encodedLengths</td> EncodedLengths</td> The resulting encoded lengths of the dynamic data of the record</td></tr> data</td> bytes</td> The data to insert into the dynamic data of the record at the start byte</td></tr> </tbody></table> Store_DeleteRecord</h4> The Store_DeleteRecord</code> event MUST be emitted whenever the Record has been deleted from the Table. event Store_DeleteRecord(ResourceId indexed tableId, bytes32[] keyTuple);</code></pre> Parameters: Name</th> Type</th> Description</th></tr></thead> tableId</td> ResourceId</td> The ID of the table where the record is deleted</td></tr> keyTuple</td> bytes32[]</td> An array representing the composite key for the record</td></tr> </tbody></table> See the reference implementation section</a> for an example on how to index store events. The Tables</code> table</h3> To keep track of the information of each table and support registering new tables at runtime, the Store implementation MUST include a special on-chain Tables</code> table, which behaves the same way as other on-chain tables except for the special constraints mentioned below. The Tables</code> table MUST use the following Schema</code>s: Key Schema: tableId</code> (ResourceId</code>): ResourceId</code> of the table this record describes.</li> </ul> </li> Value Schema: fieldLayout</code> (FieldLayout</code>): encodes the byte length of each static data type in the table.</li> keySchema</code> (Schema</code>): represents the data types of the (composite) key of the table.</li> valueSchema</code> (Schema</code>): represents the data types of the value fields of the table.</li> abiEncodedKeyNames</code> (bytes</code>): ABI encoded string array of key names.</li> abiEncodedFieldNames</code> (bytes</code>): ABI encoded string array of field names.</li> </ul> </li> </ul> Records stored in the Tables</code> table are considered immutable: The Store</code> MUST emit a single Store_SetRecord</code> event for each table being registered.</li> The Store</code> SHOULD NOT emit any other Store</code> events for a Table</code> registered in the Tables</code> table.</li> </ul> The Tables</code> table MUST store a record that describes itself before any other table is registered, emitting the corresponding Store_SetRecord</code> event. The record must use the following tableId</code>: // First two bytes indicates that this is an on-chain table // The next 30 bytes are the unique identifier for the Tables table // bytes32("tb") | bytes32("store") >> (2 8) | bytes32("Tables") >> (2 * 8 + 14 * 8) ResourceId tableId = ResourceId.wrap(0x746273746f72650000000000000000005461626c657300000000000000000000);</code></pre> By using a predefined ResourceId</code> and Schema</code> for the Tables</code> table, off-chain indexers can interpret store events for all registered tables. This enables the development of advanced off-chain services that operate on structured data rather than raw encoded data like in the previous indexer implementation example. Rationale</h2> Splice Events</h3> While the Store_SetRecord</code> event suffices for tracking the data of each record off-chain, including Splice</code> events (Store_SpliceStaticData</code> and Store_SpliceDynamicData</code>) allows for more efficient partial updates. When only a portion of a record changes, emitting a full SetRecord</code> event would be inefficient because the entire record data would need to be read from storage and emitted. Splice</code> events enable the store to emit only the minimal necessary data for the update, reducing gas consumption. This is particularly important for records with large dynamic fields, as the cost of updating them doesn’t grow with the field’s size. Disallowing Arrays of Dynamic Types</h3> Arrays of dynamic types (e.g., string[]</code>, bytes[]</code>) are intentionally not included as supported SchemaType</code>s. This restriction enforces a flat data schema, which simplifies the store implementation and enhances efficiency. If users need to store such data structures, they can model them using a separate table with a schema like { index: uint256, data: bytes }</code>, where each array element is represented as an individual record. FieldLayout Optimization</h3> Including the FieldLayout</code> in the Tables</code> schema provides an on-chain optimization by precomputing and storing the exact byte lengths of static fields. This eliminates the need to repeatedly compute field lengths and offsets during runtime, which can be gas-intensive. By having this information readily available, the store can perform storage operations more efficiently, while components reading from the store can retrieve it from the Tables</code> table to decode the corresponding records. Special Tables</code> table</h3> Including a special Tables</code> table provides significant benefits for off-chain indexers. While emitting events for table registration isn't strictly necessary for basic indexers that operate on raw encoded data, doing so makes indexers aware of the schemas used by each table. This awareness enables the development of more advanced, schema-aware indexer APIs (e.g., SQL-like query capabilities), enhancing the utility and flexibility of off-chain data interactions. By reusing existing Store abstractions for table registration, we also simplify the implementation and eliminate the need for additional, specific table registration events. Indexers can leverage the standard Store events to access schema information, ensuring consistency and reducing complexity. Reference Implementation</h2> Store Event Indexing</h3> The following example shows how a simple in-memory indexer can use the Store events to replicate the Store state off-chain. It is important to note that this indexer operates over raw encoded data which is not that useful on its own, but can be improved as we will explain in the next section. We use TypeScript for this example but it can easily be replicated with other languages. type Hex = `0x${string}`; type Record = { staticData: Hex; encodedLengths: Hex; dynamicData: Hex; }; const store = new Map<string, Record>(); // Create a key string from a table ID and key tuple to use in our store Map above function storeKey(tableId: Hex, keyTuple: Hex[]): string { return `${tableId}:${keyTuple.join(",")}`; } // Like `Array.splice`, but for strings of bytes function bytesSplice( data: Hex, start: number, deleteCount = 0, newData: Hex = "0x" ): Hex { const dataNibbles = data.replace(/^0x/, "").split(""); const newDataNibbles = newData.replace(/^0x/, "").split(""); return `0x${dataNibbles .splice(start, deleteCount 2) .concat(newDataNibbles) .join("")}`; } function bytesLength(data: Hex): number { return data.replace(/^0x/, "").length / 2; } function processStoreEvent(log: StoreEvent) { if (log.eventName === "Store_SetRecord") { const key = storeKey(log.args.tableId, log.args.keyTuple); // Overwrite all of the Record's fields store.set(key, { staticData: log.args.staticData, encodedLengths: log.args.encodedLengths, dynamicData: log.args.dynamicData, }); } else if (log.eventName === "Store_SpliceStaticData") { const key = storeKey(log.args.tableId, log.args.keyTuple); const record = store.get(key) ?? { staticData: "0x", encodedLengths: "0x", dynamicData: "0x", }; // Splice the static field data of the Record store.set(key, { staticData: bytesSplice( record.staticData, log.args.start, bytesLength(log.args.data), log.args.data ), encodedLengths: record.encodedLengths, dynamicData: record.dynamicData, }); } else if (log.eventName === "Store_SpliceDynamicData") { const key = storeKey(log.args.tableId, log.args.keyTuple); const record = store.get(key) ?? { staticData: "0x", encodedLengths: "0x", dynamicData: "0x", }; // Splice the dynamic field data of the Record store.set(key, { staticData: record.staticData, encodedLengths: log.args.encodedLengths, dynamicData: bytesSplice( record.dynamicData, log.args.start, log.args.deleteCount, log.args.data ), }); } else if (log.eventName === "Store_DeleteRecord") { const key = storeKey(log.args.tableId, log.args.keyTuple); // Delete the whole Record store.delete(key); } }</code></pre>Security Considerations</h2> Access Control</h3> This standard only defines functions to read from the Store (getRecord</code>, getField</code>, and getFieldLength</code>). The methods for setting or modifying records in the store are left to each specific implementation. Therefore, implementations must provide appropriate access control mechanisms for writing to the store, tailored to their specific use cases. On-Chain Data Accessibility</h3> All data stored within a store is accessible not only off-chain but also on-chain by other smart contracts through the provided read functions (getRecord</code>, getField</code>, and getFieldLength</code>). This differs from the typical behavior of smart contracts, where internal storage variables are private by default and cannot be directly read by other contracts unless explicit getter functions are provided. Thus, developers must be mindful that any data stored in the store is openly accessible to other smart contracts. Copyright</h2> Copyright and related rights waived via CC0</a>. Governance for Human Robot Societies 2024-09-29T00:00:00+00:00 Abstract</h2> This proposal defines two core interfaces: IUniversalIdentity</code> and IUniversalCharter</code>, providing mechanisms for humans, and robots to establish their identities and to create decentralized communities governed by specific rule sets. The IUniversalIdentity</code> interface establishes the fair and equitable treatment of sentient computer architectures other than the human brain, enabling robots to acquire on-chain identities, and thereby interact and transact with humans. Additionally the IUniversalIdentity</code> interface also includes support for hardware-backed identity verification, enabling physical robots to prove their identity through cryptographic signatures derived from secure hardware elements and a challenge-response scheme. The IUniversalCharter</code> enables humans and robots to create, join (“register”), maintain (“update”), leave, and terminate self-regulated societies based on predefined rule sets, providing a framework for collaboration and prosperity for mixed societies of humans and robots. These interfaces aim to provide a flexible yet enforceable structure for human-robot interactions in decentralized systems, ensuring efficiency, transparency, and security for all participants. Motivation</h2> The human brain is a wet, massively parallel electrochemical computer. Recent hardware and software advances make it likely that soon, human societies will need tools for interacting with sentient, non-human computers, such as robots. Our current forms of government, where citizens are auto-enrolled into specific rule sets depending on where they were born, do not gracefully map onto robots without a traditional birthplace or birthtime. Among many difficulties being experienced by robots, they are (currently) unable to obtain standard forms of ID (such as passports), it is not clear which rule sets apply to them (since in general they are not born in specific places), and they cannot currently use the standard human-centered banking system. Likewise, in the event in which robots are harmed by humans or non-biological computers, it is not clear which human court has jurisdiction. Traditional geographically-defined and human-centered systems can be inefficient, slow to change, opaque, and can struggle to accommodate global, virtualized societies. Decentralized, immutable, and public computers offer an ideal solution to these limitations, since they do not inherently discriminate against non-human computers and therefore offer an equitable and more just framework for governance. In particular, smart contracts can provide a powerful framework for regulating the rights and responsibilities or interacting parties regardless of implementation details of their compute architecture. The general motivation of this ERC is to provide a standard interface for smart contracts focusing on identity/governance for heterogeneous global societies. While there are an unlimited number of such rule sets, there are obvious benefits to providing a standard interface to those rule sets, greatly reducing the friction and complexity of creating, joining, maintaining, and ending such societies. The specific motivation of this ERC is twofold: Robot Identity Creation and Management: To participate meaningfully and comply with on-chain laws, non-humans such as robots must be able to acquire meaningful on-chain identities. Importantly, these identities should enable robots to enjoy the benefits of, but also bear the responsibility of, being part of a specific society. Thus, we propose to enable smart contract-based identity for robots. Specifically, each robot is represented by a smart contract and needs to follow the rules defined in the contract to interact with other agents on the chain. Each robot can also specify hardware identity parameters such as a manufacturer, operator, model and serial number in conjunction with a public key which is intended to be generated using a secure element on the Robot. This provides a tamper-resistant and unclonable proof that can be physically verified through challenge-response authentication - where any party can verify the robot's identity by having the device cryptographically sign a challenge using its hardware-secured private key. These verified identities are published on-chain. This interface also ensures flexibility by all participants to propose, adopt, or revoke rules, enabling self-managed compliance and transparent interaction with other participants.</li> Rule Creation and Enforcement: For humans and robots to effectively collaborate, they must agree upon a rule set. This Ethereum-based system provides a basic decentralized framework for governing human-robot interactions through smart contracts. We propose to enforce the rule-sets by requiring humans and robots to join regulated access smart contracts that check their compliance with the given rules. We also ensure scalability, whereby multiple regulated access contracts can be created to tailor to different purposes, and humans and robots can choose to join the relevant system as needed.</li> </ol> Together, these interfaces form the foundation for managing complex human-robot interactions, enabling a decentralized, verifiable, and rule-based ecosystem where robots and humans can interact securely, transparently, and responsibly, for maximum benefit of all. 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. interface IUniversalIdentity { /// @notice Structure for hardware identity struct HardwareIdentity { bytes32 publicKey; // Hardware-bound public key uniquely tied to this robot string manufacturer; // Identifier for the robot's manufacturer string operator; // Identifier for the robot's operator string model; // Model identifier of the robot string serialNumber; // Unique serial number for the robot bytes32 initialHashSignature; // Signature of the initial system state hash (e.g., firmware, OS) by the root key bytes32 currentHashSignature; // Signature of the latest state hash, updated periodically for integrity verification by the root key } /// @notice Gets the hardware identity info /// @return HardwareIdentity Current hardware identity function getHardwareIdentity() external view returns (HardwareIdentity memory); /// @notice Generates a new challenge for hardware verification /// @return bytes32 Random challenge that needs to be signed function generateChallenge() external returns (bytes32); /// @notice Verify response to a specific challenge /// @param challenge The challenge that was issued /// @param signature Hardware signature of the challenge /// @return bool True if signature is valid for this challenge function verifyChallenge(bytes32 challenge, bytes memory signature) external returns (bool); /// @notice Adds a rule to the robot's identity, showing that the robot agrees to follow the rule. /// @param rule The dynamic byte array representing the rule that the robot agrees to follow. Each rule is a textual string encoded into a dynamic byte array. For example: 'A robot must keep a 1m distance from humans.' /// @dev The rule SHOULD come from the rule sets defined in the IUniversalCharter contract that the robot intends to join. /// @dev This function SHOULD be implemented by contracts to add the rules that the robot intends to follow. function addRule(bytes memory rule) external; /// @notice Removes a rule from the robot's identity. /// @param rule The dynamic byte array representing the rule that the robot no longer agrees to follow. /// @dev This function SHOULD be implemented by contracts to remove the rules that the robot does not intend to follow. function removeRule(bytes memory rule) external; /// @notice Checks if the robot complies with a specific rule. /// @param rule The rule to check. /// @return bool Returns true if the robot complies with the rule. /// @dev This function MUST be implemented by contracts for compliance verification. function checkCompliance(bytes memory rule) external view returns (bool); /// @dev Emitted when a rule is added to the robot's identity. event RuleAdded(bytes rule); /// @dev Emitted when a rule is removed from the robot's identity. event RuleRemoved(bytes rule); /// @dev Emitted when a charter is subscribed to. event SubscribedToCharter(address indexed charter); /// @dev Emitted when it is unsubscribed from a charter. event UnsubscribedFromCharter(address indexed charter); } interface IUniversalCharter { // Define the user types as an enum. enum UserType { Human, Robot } /// @notice Registers a user (human or robot) to join the system by agreeing to a rule set. /// @param userType The type of user. /// @param ruleSet The array of individual rules the user agrees to follow. /// @dev This function MUST be implemented by contracts using this interface. /// @dev The implementing contract MUST ensure that the user complies with the specified rule set before registering them in the system by invoking `checkCompliance`. function registerUser(UserType userType, bytes[] memory ruleSet) external; /// @notice Allows a user (human or robot) to leave the system /// @dev This function MUST be callable only by the user themselves (via `msg.sender`). /// @dev The implementing contract MUST ensure that the user has complied with all necessary rules before they can successfully leave the system by invoking `checkCompliance`. function leaveSystem() external; /// @notice Checks if the user (human or robot) complies with the system’s rules. /// @param user Address of the user (human or robot). /// @param ruleSet The array of individual rules to verify. /// @return bool Returns true if the user complies with the rule set. /// @dev This function SHOULD invoke the `checkCompliance` function of the user’s IUniversalIdentity contract to check for rules individually. /// @dev This function MUST be implemented by contracts for compliance verification. function checkCompliance(address user, bytes[] memory ruleSet) external view returns (bool); /// @notice Updates the rule set. /// @param newRuleSet The array of new individual rules replacing the existing ones. /// @dev This function SHOULD be restricted to authorized users (e.g., contract owner). function updateRuleSet(bytes[] memory newRuleSet) external; /// @notice Terminates the contract, preventing any further registrations or interactions. /// @dev This function SHOULD be restricted to authorized users (e.g., contract owner). /// @dev This function SHOULD be implemented by contracts. function terminateContract() external; /// @dev Emitted when a user joins the system by agreeing to a set of rules. event UserRegistered(address indexed user, UserType userType, bytes[] ruleSet); /// @dev Emitted when a user successfully leaves the system after fulfilling obligations. event UserLeft(address indexed user); /// @dev Emitted when a user’s compliance with a rule set is verified. event ComplianceChecked(address indexed user, bytes[] ruleSet); /// @dev Emitted when a rule set is updated. event RuleSetUpdated(bytes[] newRuleSet, address updatedBy); }</code></pre>Rationale</h2> IUniversalIdentity struct HardwareIdentity</code> The HardwareIdentity structure provides essential information about a robot, including a challenge-response public key, manufacturer, operator, model, manufacturer serial number generateChallenge()</code> This function enables secure identity verification through a challenge-response authentication. verifyChallenge(bytes32 challenge, bytes memory signature)</code> This function verifies that a signature was genuinely created by the robot's secure hardware in response to a specific challenge. addRule(bytes memory rule)</code> This function allows a robot to flexibly adopt new compliance requirements in order join different IUniversalCharter</code> contracts. removeRule(bytes memory rule)</code> This function allows a robot to dynamically manage and maintain its rules, ensuring that its rule set remains up-to-date. checkCompliance(bytes memory rule)</code> This function ensures that a robot is adhering to rules by performing decentralised checks on its compliance. Events (RuleAdded, RuleRemoved)</code> These events provide transparency and traceability, making it easier to track compliance status. IUniversalCharter enum UserType { Human, Robot }</code> The UserType enum makes it easier for contracts to handle different user types without the cost and errors associated with strings. This provides the basis for differentiated handling in future implementations, allowing the system to potentially apply different rules or logic based on whether the user is a human or a robot. registerUser(UserType userType, bytes[] memory ruleSet)</code> This function ensures that a user—whether human or robot—is bound to a particular set of rules upon joining the system. leaveSystem()</code> This function allows users to flexibly and securely leave a IUniversalCharter</code> contract after compliance is checked. checkCompliance(address user, bytes[] memory ruleSet)</code> This function ensures that the system can efficiently manage and verify compliance against predefined rule sets, helping maintain the overall integrity of the system. updateRuleSet(bytes[] memory newRuleSet)</code> This function enables the IUniversalCharter</code> contract to adapt and update, removing the need to create a new contract for ruleset updates. terminateContract()</code> This function allows for the orderly and permanent shutdown of the contract. Events (UserRegistered, UserLeft, ComplianceChecked, RuleSetUpdated, ContractTerminated)</code> These events collectively ensure that key activities are visible to off-chain systems and participants, making the system auditable and transparent. Backwards Compatibility</h2> No backward compatibility issues found. Reference Implementation</h2> // SPDX-License-Identifier: CC0-1.0 pragma solidity ^0.8.19; import { OwnableUpgradeable } from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol"; import { UniversalCharter } from "./UniversalCharter.sol"; // Interfaces import { IUniversalIdentity } from "./interface/IUniversalIdentity.sol"; import { IUniversalCharter } from "./interface/IUniversalCharter.sol"; /// @title UniversalIdentity /// @notice The UniversalIdentity contract is used to manage the identity of robots. contract UniversalIdentity is IUniversalIdentity, OwnableUpgradeable { /// @notice Version identifier for the current implementation of the contract. string public constant VERSION = "v0.0.1"; /// @notice Mapping to store rules that the robot has agreed to follow mapping(bytes => bool) private robotRules; /// @notice Mapping to store the off-chain compliance status for each rule mapping(bytes => bool) private complianceStatus; /// @notice Track the charters the robot is subscribed to mapping(address => bool) private subscribedCharters; /// @notice Custom errors to save gas on reverts error RuleNotAgreed(bytes rule); error RuleNotCompliant(bytes rule); error RuleAlreadyAdded(bytes rule); /// @dev Event to emit when compliance is checked /// @param updater The address of the compliance updater (owner of the contract) /// @param rule The rule that was checked event ComplianceChecked(address indexed updater, bytes rule); /// @notice Modifier to check if a rule exists modifier ruleExists(bytes memory rule) { require(robotRules[rule], "Rule does not exist"); _; } /// @notice Constructor to set the owner constructor() { initialize({ _owner: address(0xdEaD) }); } /// @dev Initializer function function initialize(address _owner) public initializer { __Ownable_init(); transferOwnership(_owner); hardwareIdentity = _hardwareIdentity; } /// @notice Gets the hardware identity info function getHardwareIdentity() external view returns (HardwareIdentity memory) { return hardwareIdentity; } /// @notice Generates a new challenge for hardware verification function generateChallenge() external returns (bytes32) { bytes32 challenge = keccak256(abi.encodePacked( block.timestamp, block.prevrandao, msg.sender )); activeChallenge[challenge] = true; return challenge; } /// @notice Verify response to a specific challenge function verifyChallenge( bytes32 challenge, bytes memory signature ) external returns (bool) { if (!activeChallenge[challenge]) { revert InvalidChallenge(); } // Remove challenge after use delete activeChallenge[challenge]; // Verify the signature using ECDSA bytes32 messageHash = keccak256(abi.encodePacked(challenge)); bytes32 ethSignedMessageHash = ECDSA.toEthSignedMessageHash(messageHash); address signer = ECDSA.recover(ethSignedMessageHash, signature); // Convert hardware public key to address for comparison address hardwareAddress = address(uint160(uint256(hardwareIdentity.publicKey))); if (signer != hardwareAddress) { revert InvalidSignature(); } return true; } /// @notice Updates the hardware identity information /// @param _hardwareIdentity New hardware identity information function updateHardwareIdentity( HardwareIdentity memory _hardwareIdentity ) external onlyOwner { hardwareIdentity = _hardwareIdentity; } /// @notice Adds a rule to the robot's identity /// @param rule The dynamic byte array representing the rule that the robot agrees to follow. function addRule(bytes memory rule) external override onlyOwner { if (robotRules[rule]) { revert RuleAlreadyAdded(rule); } // Add rule to the mapping robotRules[rule] = true; emit RuleAdded(rule); } /// @notice Removes a rule from the robot's identity /// @param rule The dynamic byte array representing the rule that the robot no longer agrees to follow. function removeRule(bytes memory rule) external override onlyOwner ruleExists(rule) { robotRules[rule] = false; complianceStatus[rule] = false; emit RuleRemoved(rule); } /// @notice Subscribe and register to a specific UniversalCharter contract using its stored rule set /// @param charter The address of the UniversalCharter contract /// @param version The version of the rule set to fetch and register for function subscribeAndRegisterToCharter(address charter, uint256 version) external { require(!subscribedCharters[charter], "Already subscribed to this charter"); subscribedCharters[charter] = true; // Fetch the rule set directly from the UniversalCharter contract using the public getter bytes[] memory ruleSet = UniversalCharter(charter).getRuleSet(version); // Register as a robot in the charter using the fetched rule set UniversalCharter(charter).registerUser(IUniversalCharter.UserType.Robot, ruleSet); emit SubscribedToCharter(charter); } /// @notice Leave the system for a specific UniversalCharter contract /// @param charter The address of the UniversalCharter contract to leave function leaveCharter(address charter) external { require(subscribedCharters[charter], "Not subscribed to this charter"); // Call the leaveSystem function of the UniversalCharter contract UniversalCharter(charter).leaveSystem(); // Unsubscribe from the charter after leaving subscribedCharters[charter] = false; emit UnsubscribedFromCharter(charter); } /// @notice Updates compliance status for a rule (called by the owner) /// @param rule The dynamic byte array representing the rule /// @param status The compliance status (true if compliant, false if not) function updateCompliance(bytes memory rule, bool status) external onlyOwner ruleExists(rule) { complianceStatus[rule] = status; emit ComplianceChecked(msg.sender, rule); } /// @notice Checks if the robot has agreed to follow a specific rule and if it is compliant /// @param rule The rule to check. /// @return bool Returns true if the robot has agreed to the rule and is compliant function checkCompliance(bytes memory rule) external view override returns (bool) { if (!robotRules[rule]) { revert RuleNotAgreed(rule); } return true; } /// @notice Gets the compliance status of a rule /// @param rule The rule to check. function getRule(bytes memory rule) external view returns (bool) { return robotRules[rule]; } /// @notice Gets the subscription status of a charter /// @param charter The address of the charter to check. function getSubscribedCharters(address charter) external view returns (bool) { return subscribedCharters[charter]; } /// @notice Gets the compliance status of a rule /// @param rule The rule to check. function getComplianceStatus(bytes memory rule) external view returns (bool) { return complianceStatus[rule]; } }</code></pre>// SPDX-License-Identifier: CC0-1.0 pragma solidity 0.8.20; import { OwnableUpgradeable } from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol"; import { SystemConfig } from "./SystemConfig.sol"; // Interfaces import { IUniversalCharter } from "./interface/IUniversalCharter.sol"; import { IUniversalIdentity } from "./interface/IUniversalIdentity.sol"; /// @title UniversalCharter /// @notice The UniversalCharter contract is used to manage the registration and compliance of users. contract UniversalCharter is IUniversalCharter, OwnableUpgradeable { /// @notice Struct to store information about a registered user struct UserInfo { bool isRegistered; UserType userType; uint256 ruleSetVersion; // Rule set version the user is following } /// @notice Mapping to store registered users mapping(address => UserInfo) private users; /// @notice Mapping to store rule sets by version number mapping(uint256 => bytes[]) private ruleSets; /// @notice Mapping to track the rule set hash and its corresponding version mapping(bytes32 => uint256) private ruleSetVersions; /// @notice Version identifier for the current implementation of the contract. string public constant VERSION = "v0.0.1"; /// @notice Variable to track the current version of the rule set uint256 private currentVersion; /// @notice Variable to store the address of the SystemConfig contract SystemConfig public systemConfig; /// @notice Error for when a method cannot be called when paused. This could be renamed /// to `Paused` in the future, but it collides with the `Paused` event. error CallPaused(); /// @notice Reverts when paused. modifier whenNotPaused() { if (paused()) revert CallPaused(); _; } /// @notice Constucts the UniversalCharter contract. constructor() { initialize({ _owner: address(0xdEaD), _systemConfig: address(0xdEaD) }); } /// @dev Initializer function function initialize(address _owner, address _systemConfig) public initializer { __Ownable_init(); transferOwnership(_owner); systemConfig = SystemConfig(_systemConfig); } /// @notice Registers a user (either human or robot) by agreeing to a rule set /// @param userType The type of user: Human or Robot /// @param ruleSet The array of individual rules the user agrees to follow function registerUser(UserType userType, bytes[] memory ruleSet) external override whenNotPaused { require(!users[msg.sender].isRegistered, "User already registered"); // Hash the rule set to find the corresponding version bytes32 ruleSetHash = keccak256(abi.encode(ruleSet)); uint256 version = ruleSetVersions[ruleSetHash]; require(version > 0, "Invalid or unregistered rule set"); // For robots, ensure compliance with each rule via the UniversalIdentity contract if (userType == UserType.Robot) { require(_checkRobotCompliance(msg.sender, version), "Robot not compliant with rule set"); } // Register the user with the versioned rule set users[msg.sender] = UserInfo({ isRegistered: true, userType: userType, ruleSetVersion: version }); emit UserRegistered(msg.sender, userType, ruleSet); } /// @notice Allows a user (human or robot) to leave the system after passing compliance checks function leaveSystem() external override whenNotPaused { require(users[msg.sender].isRegistered, "User not registered"); UserInfo memory userInfo = users[msg.sender]; // For robots, verify compliance with all rules in the rule set uint256 version = userInfo.ruleSetVersion; if (userInfo.userType == UserType.Robot) { require(_checkRobotCompliance(msg.sender, version), "Robot not compliant with rule set"); } users[msg.sender] = UserInfo({ isRegistered: false, userType: UserType.Human, ruleSetVersion: 0 }); emit UserLeft(msg.sender); } /// @notice Internal function to verify robot hardware identity /// @param robotAddress The address of the robot to verify /// @return bool Returns true if hardware verification succeeds function _verifyRobotHardware(address robotAddress) internal returns (bool) { IUniversalIdentity robot = IUniversalIdentity(robotAddress); // Get hardware identity to ensure it exists robot.getHardwareIdentity(); // Generate a new challenge bytes32 challenge = robot.generateChallenge(); // Store the challenge for future reference users[robotAddress].lastVerifiedChallenge = challenge; // Get signature from the robot (this would typically happen off-chain) // For this implementation, we'll assume the signature is provided in a separate tx // and just verify the challenge exists return challenge != 0; } /// @notice Checks if a user complies with their registered rule set /// @param user The address of the user (human or robot) /// @param ruleSet The array of individual rules to verify /// @return bool Returns true if the user complies with the given rule set function checkCompliance(address user, bytes[] memory ruleSet) external view override returns (bool) { require(users[user].isRegistered, "User not registered"); // Hash the provided rule set to find the corresponding version bytes32 ruleSetHash = keccak256(abi.encode(ruleSet)); uint256 version = ruleSetVersions[ruleSetHash]; require(version > 0, "Invalid or unregistered rule set"); require(users[user].ruleSetVersion == version, "Rule set version mismatch"); // For robots, check compliance with each rule in the UniversalIdentity contract if (users[user].userType == UserType.Robot) { return _checkRobotCompliance(user, version); } // If the user is human, compliance is assumed for now (can be extended) return true; } /// @notice Internal function to check compliance for robots with their rule set version /// @dev This function will revert if the robot is not compliant with any rule. Returns true for view purposes. /// @param robotAddress The address of the robot /// @param version The version of the rule set to verify compliance with /// @return bool Returns true if the robot is compliant with all the rules in the rule set function _checkRobotCompliance(address robotAddress, uint256 version) internal view returns (bool) { IUniversalIdentity robot = IUniversalIdentity(robotAddress); bytes[] memory rules = ruleSets[version]; for (uint256 i = 0; i < rules.length; i++) { if (!robot.checkCompliance(rules[i])) { return false; } } return true; } /// @notice Updates or defines a new rule set version. /// @param newRuleSet The array of new individual rules. /// @dev This function SHOULD be restricted to authorized users (e.g., contract owner). function updateRuleSet(bytes[] memory newRuleSet) external whenNotPaused onlyOwner { require(newRuleSet.length > 0, "Cannot update to an empty rule set"); // Hash the new rule set and ensure it's not already registered bytes32 ruleSetHash = keccak256(abi.encode(newRuleSet)); require(ruleSetVersions[ruleSetHash] == 0, "Rule set already registered"); // Increment the version and store the new rule set currentVersion += 1; ruleSets[currentVersion] = newRuleSet; ruleSetVersions[ruleSetHash] = currentVersion; emit RuleSetUpdated(newRuleSet, msg.sender); } /// @notice Getter for the latest version of the rule set. function getLatestRuleSetVersion() external view returns (uint256) { return currentVersion; } /// @notice Get the rule set for a specific version. /// @param version The version of the rule set to retrieve. function getRuleSet(uint256 version) external view returns (bytes[] memory) { return ruleSets[version]; } /// @notice Get the version number for a specific rule set. /// @param ruleSet The hash of the rule set to retrieve the version for. function getRuleSetVersion(bytes32 ruleSet) external view returns (uint256) { return ruleSetVersions[ruleSet]; } function getUserInfo(address user) external view returns (UserInfo memory) { return users[user]; } /// @notice Getter for the current paused status. /// @return paused_ Whether or not the contract is paused. function paused() public view returns (bool paused_) { paused_ = systemConfig.paused(); } }</code></pre>Security Considerations</h2> Compliance Updater: The compliance updater role in the UniversalIdentity</code> contract is critical for updating compliance statuses (currently limited to the owner). It is essential to ensure secure ownership to minimize the risks of unauthorized or malicious updates. Rule Management: Functions such as addRule, removeRule, and updateCompliance in the UniversalIdentity</code> contract and updateRuleSet in the UniversalCharter</code> contract directly affect rule enforcement. It’s essential to ensure these functions are only callable by authorized users. Upgradeable Contracts: The use of OwnableUpgradeable introduces risks during the initialization and upgrade process. Ensuring that the initialize function is protected against re-execution is critical to avoid reinitialization attacks. Gas Consumption: Excessively large rule sets could lead to high gas costs or DoS risks. Consider setting limits on the number of rules allowed per rule set to maintain gas efficiency and avoid performance issues. Copyright</h2> Copyright and related rights waived via CC0</a>. Transparent Financial Statements 2024-09-20T00:00:00+00:00 Abstract</h2> This proposal defines a standard API that enables EVM Blockchain-based companies (or also called "protocols") to publish their financial information, specifically Income Statements and Balance Sheets, on- chain in a transparent and accessible manner through solidity smart contracts. This standard aims to emulate the reporting structure used by publicly traded companies in traditional stocks markets, like the SEC 10-Q filings. The financial statements include key information, namely as Revenue, Cost of Goods Sold, Operating Expenses, Operating Income, Earnings before Interest, Taxes, Depreciation, and Amortization (EBITDA) and Earnings Per Share-Token (EPS), allowing investors to assess the financial health of blockchain-based companies in a standardized, transparent, clear and reliable format. Motivation</h2> The motivation of this ERC is to bring seriousness to the cryptocurrencies investments market. Currently, the situation is as follows: The current state of token investment analysis is opaque, with most information presented in an abstract and non-quantitative form. This standard API ensures a consistent and reliable way for investors to evaluate blockchain projects based on real financial data published directly on-chain, not just speculative promises. This will establish a greater trust in the cryptocurrency markets and align token analysis with the standards of traditional equity markets. Most ERC-20</a> Tokens representing EVM Blockchain-based companies (or also called "protocols"), DO NOT work the same way as a publicly traded stock that represents a share of ownership of the equity of that such company (so the user who buys a protocol's ERC-20, is also now a share-holder and co-owner of the business, its profits and/or its dividends), but rather function as "commodities" such as oil; they are consumable items created by said EVM Blockchain-based company (or "protocol") to be spent in their platform. They are publicly traded and advertised to be representing the underlying protocol like a share, working in practice the same way as a commodity and without any public, transparent and Clear Financial Information as publicly traded stocks have. Added to that, most token research analysis reports that can be currently found on the internet are informal Substack or Twitter posts, with lots of abstract explanations about the features of the said protocol to invest in, that lack of transparent financial numbers and factual financial information, that are made by anonymous users without real exposed reputations to affect. This ERC will improve that by giving users and investors transparent, clear and factual financial information to work with when analyzing as a potential investment the such EVM Blockchain-based company that implements this ERC in their solidity smart contracts, and that will generate trust, transparency and seriousness in the cryptocurrencies investments market long term. 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. All Transparent Financial Statements Standard implementations MUST implement ERC-20 to represent shares, and the financial numbers such as Revenue, Costs of Goods Sold, Operating Expenses, Operating Income, EBITDA, Other Income and Expenses, Net Income and Earnings Per Share MUST be displayed in the value of the protocol's stablecoin of choice. All Transparent Financial Statements MUST implement ERC-20's optional metadata extensions. The name</code> and symbol</code> functions SHOULD reflect the underlying token's name</code> and symbol</code> in some way. All methods MUST be of visibility external</code>. All methods MUST return their financial numbers valued in the provided stablecoin</code>. If the contract owner uses data or methods from other owned smart contracts external to their smart contract implementation of this standard, those smart contracts MUST be verified in the correspondent blockchain explorer and of open and visible source code. Timestamp Constraint: For all methods, startTimestamp</code> MUST be less than or equal to endTimestamp</code>. If startTimestamp</code> is equal to endTimestamp</code>, the method returns a balance sheet snapshot. If startTimestamp</code> is less than endTimestamp</code>, the method returns an income statement for that period. Output Structs: Instead of a single uint256</code> value, each method returns a struct</code> with one or OPTIONAL more uint256</code> entries to allow for detailed financial data, each one with their own customized entry name</code>. Definitions</h3> Currency: The individual stablecoin used to value the publicly displayed financial numbers.</li> Revenue: Total earnings from selling products or services before expenses.</li> Cost of Goods Sold (COGS): Direct costs for producing goods/services, including labor and materials.</li> Operating Expenses: Expenses like Selling, General, and Administrative, Research and Development, and other operational costs.</li> Operating Income: Revenue minus operating expenses.</li> EBITDA: Earnings Before Interest, Taxes, Depreciation, and Amortization.</li> Other Income and Expenses: Non-operating income, such as interest, investment gains or losses.</li> Net Income: Profit after all expenses, taxes, and deductions.</li> EPS: Earnings per Share Token (ERC-20), showing profit allocated per share.</li> </ul> Methods</h3> stablecoinAddress</code></h4> Returns the address</code> of the individual stablecoin used to value the publicly displayed financial numbers. - name: stablecoinAddress type: function visibility: external stateMutability: view outputs: - name: currencyAddress type: address </code></pre>revenue</code></h4> Returns total revenue generated by the protocol within a time period. - name: revenue type: function visibility: external stateMutability: view inputs: - name: startTimestamp type: uint256 - name: endTimestamp type: uint256 outputs: - name: RevenueStruct type: struct fields: - name: grossRevenue type: uint256 - name: optionalAdditionalRevenueDetail1 type: uint256 - name: optionalAdditionalRevenueDetailN type: uint256 </code></pre>cogs</code></h4> Returns the cost of goods sold within a specified period. - name: cogs type: function visibility: external stateMutability: view inputs: - name: startTimestamp type: uint256 - name: endTimestamp type: uint256 outputs: - name: COGSStruct type: struct fields: - name: totalCOGS type: uint256 - name: optionalAdditionalCOGSDetail1 type: uint256 - name: optionalAdditionalCOGSDetailN type: uint256 </code></pre>operatingExpenses</code></h4> Returns the total operating expenses within a specified period. - name: operatingExpenses type: function visibility: external stateMutability: view inputs: - name: startTimestamp type: uint256 - name: endTimestamp type: uint256 outputs: - name: OperatingExpensesStruct type: struct fields: - name: totalOperatingExpenses type: uint256 - name: optionalAdditionalExpenseDetail1 type: uint256 - name: optionalAdditionalExpenseDetailN type: uint256 </code></pre>operatingIncome</code></h4> Returns operating income for the specified period (Revenue - COGS - Operating Expenses). - name: operatingIncome type: function visibility: external stateMutability: view inputs: - name: startTimestamp type: uint256 - name: endTimestamp type: uint256 outputs: - name: OperatingIncomeStruct type: struct fields: - name: totalOperatingIncome type: uint256 - name: optionalAdditionalIncomeDetail1 type: uint256 - name: optionalAdditionalIncomeDetailN type: uint256 </code></pre>ebitda</code></h4> Returns EBITDA for the given period. - name: ebitda type: function visibility: external stateMutability: view inputs: - name: startTimestamp type: uint256 - name: endTimestamp type: uint256 outputs: - name: EBITDAstruct type: struct fields: - name: totalEBITDA type: uint256 - name: optionalAdditionalEBITDADetail1 type: uint256 - name: optionalAdditionalEBITDADetailN type: uint256 </code></pre>otherIncomeExpenses</code></h4> Returns non-operating income and expenses, such as interest and investment gains or losses, for the specified period. - name: otherIncomeExpenses type: function visibility: external stateMutability: view inputs: - name: startTimestamp type: uint256 - name: endTimestamp type: uint256 outputs: - name: OtherIncomeExpensesStruct type: struct fields: - name: totalOtherIncome type: uint256 - name: totalOtherExpenses type: uint256 - name: totalOtherIncomeDetail1 type: uint256 - name: totalOtherExpensesDetail1 type: uint256 - name: totalOtherIncomeDetailN type: uint256 - name: totalOtherExpensesDetailN type: uint256 </code></pre>netIncome</code></h4> Returns net income for the period (Operating Income + Other Income/Expenses - Taxes - Depreciation). - name: netIncome type: function visibility: external stateMutability: view inputs: - name: startTimestamp type: uint256 - name: endTimestamp type: uint256 outputs: - name: NetIncomeStruct type: struct fields: - name: totalNetIncome type: uint256 - name: optionalAdditionalNetIncomeDetail1 type: uint256 - name: optionalAdditionalNetIncomeDetailN type: uint256 </code></pre>earningsPerShare</code></h4> Returns Earnings Per Share Token (EPS) for the period. - name: earningsPerShare type: function visibility: external stateMutability: view inputs: - name: startTimestamp type: uint256 - name: endTimestamp type: uint256 outputs: - name: EPSstruct type: struct fields: - name: basicEPS type: uint256 - name: dilutedEPS type: uint256 - name: EPSDetail1 type: uint256 - name: EPSDetailN type: uint256 </code></pre>fullFinancialReport</code></h4> Returns a comprehensive struct that includes all the prior financial details of the protocol combined: Revenue, COGS, Operating Expenses, Operating Income, EBITDA, Other Incomes and Expenses, Net income, and EPS into a unified Struct</code>. - name: fullFinancialReport type: function visibility: external stateMutability: view inputs: - name: startTimestamp type: uint256 - name: endTimestamp type: uint256 outputs: - name: FullFinancialsStruct type: struct fields: - name: RevenueStruct type: struct - name: COGSStruct type: struct - name: OperatingExpensesStruct type: struct - name: OperatingIncomeStruct type: struct - name: EBITDAstruct type: struct - name: OtherIncomeExpensesStruct type: struct - name: NetIncomeStruct type: struct - name: EPSstruct type: struct </code></pre>Rationale</h2> ERC-20 is enforced because implementation details like Earnings Per Token calculation directly carry over to the accounting. This standardization makes the Transparent Financial Statements compatible with all ERC-20 use cases. This implementation enables the protocol to share their financial information both as their latest updated Balance Sheet (if the user chooses to just see a current snapshot of the financial state of the company) and as an Income Statement (if the user chooses to see the evolution of the financial state of the company between two different block timestamps) and also is thought to interact with other separated Smart Contracts of the same protocol from which the financial information will be sent. Backwards Compatibility</h2> Transparent Financial Statements Standard is fully backward compatible with the ERC-20 standard and has no known compatibility issues with other standards. Reference Implementation</h2> // SPDX-License-Identifier: CC0-1.0 pragma solidity 0.8.27; interface IERC20 { function name() external view returns (string memory); function symbol() external view returns (string memory); } contract TransparentFinancialStatements { address public stablecoin; struct RevenueStruct { uint256 grossRevenue; uint256 optionalAdditionalRevenueDetail1; uint256 optionalAdditionalRevenueDetailN; } struct COGSStruct { uint256 totalCOGS; uint256 optionalAdditionalCOGSDetail1; uint256 optionalAdditionalCOGSDetailN; } struct OperatingExpensesStruct { uint256 totalOperatingExpenses; uint256 optionalAdditionalExpenseDetail1; uint256 optionalAdditionalExpenseDetailN; } struct OperatingIncomeStruct { uint256 totalOperatingIncome; uint256 optionalAdditionalIncomeDetail1; uint256 optionalAdditionalIncomeDetailN; } struct EBITDAstruct { uint256 totalEBITDA; uint256 optionalAdditionalEBITDADetail1; uint256 optionalAdditionalEBITDADetailN; } struct OtherIncomeExpensesStruct { uint256 totalOtherIncome; uint256 totalOtherExpenses; uint256 totalOtherIncomeDetail1; uint256 totalOtherExpensesDetail1; uint256 totalOtherIncomeDetailN; uint256 totalOtherExpensesDetailN; } struct NetIncomeStruct { uint256 totalNetIncome; uint256 optionalAdditionalNetIncomeDetail1; uint256 optionalAdditionalNetIncomeDetailN; } struct EPSstruct { uint256 basicEPS; uint256 dilutedEPS; uint256 EPSDetail1; uint256 EPSDetailN; } struct FullFinancialsStruct { RevenueStruct revenue; COGSStruct cogs; OperatingExpensesStruct operatingExpenses; OperatingIncomeStruct operatingIncome; EBITDAstruct ebitda; OtherIncomeExpensesStruct otherIncomeExpenses; NetIncomeStruct netIncome; EPSstruct eps; } constructor(address _stablecoin) { stablecoin = _stablecoin; } function currency() public view returns (address) { return stablecoin; } function revenue(uint256 startTimestamp, uint256 endTimestamp) public view returns (RevenueStruct memory) { require(startTimestamp <= endTimestamp, "Invalid timestamps"); // Logic to calculate and return revenue details return RevenueStruct(1000, 500, 100); // Example values } function cogs(uint256 startTimestamp, uint256 endTimestamp) public view returns (COGSStruct memory) { require(startTimestamp <= endTimestamp, "Invalid timestamps"); // Logic to calculate and return COGS details return COGSStruct(400, 150, 50); // Example values } function operatingExpenses(uint256 startTimestamp, uint256 endTimestamp) public view returns (OperatingExpensesStruct memory) { require(startTimestamp <= endTimestamp, "Invalid timestamps"); // Logic to calculate and return operating expenses details return OperatingExpensesStruct(300, 100, 50); // Example values } function operatingIncome(uint256 startTimestamp, uint256 endTimestamp) public view returns (OperatingIncomeStruct memory) { require(startTimestamp <= endTimestamp, "Invalid timestamps"); // Logic to calculate and return operating income details return OperatingIncomeStruct(300, 100, 50); // Example values } function ebitda(uint256 startTimestamp, uint256 endTimestamp) public view returns (EBITDAstruct memory) { require(startTimestamp <= endTimestamp, "Invalid timestamps"); // Logic to calculate and return EBITDA details return EBITDAstruct(700, 200, 100); // Example values } function otherIncomeExpenses(uint256 startTimestamp, uint256 endTimestamp) public view returns (OtherIncomeExpensesStruct memory) { require(startTimestamp <= endTimestamp, "Invalid timestamps"); // Logic to calculate and return other income/expenses details return OtherIncomeExpensesStruct(100, 50, 20, 10, 30, 20); // Example values } function netIncome(uint256 startTimestamp, uint256 endTimestamp) public view returns (NetIncomeStruct memory) { require(startTimestamp <= endTimestamp, "Invalid timestamps"); // Logic to calculate and return net income details return NetIncomeStruct(600, 200, 100); // Example values } function earningsPerShare(uint256 startTimestamp, uint256 endTimestamp) public view returns (EPSstruct memory) { require(startTimestamp <= endTimestamp, "Invalid timestamps"); // Logic to calculate and return EPS details return EPSstruct(10, 8, 2, 1); // Example values } function fullFinancialReport(uint256 startTimestamp, uint256 endTimestamp) public view returns (FullFinancialsStruct memory) { require(startTimestamp <= endTimestamp, "Invalid timestamps"); // Logic to calculate and return all financial details return FullFinancialsStruct( revenue(startTimestamp, endTimestamp), cogs(startTimestamp, endTimestamp), operatingExpenses(startTimestamp, endTimestamp), operatingIncome(startTimestamp, endTimestamp), ebitda(startTimestamp, endTimestamp), otherIncomeExpenses(startTimestamp, endTimestamp), netIncome(startTimestamp, endTimestamp), earningsPerShare(startTimestamp, endTimestamp) ); } } </code></pre>Security Considerations</h2> This ERC involves displaying critical financial data on-chain, so special attention must be paid to ensure the accuracy and security of the data, particularly in preventing tampering or manipulation of key financial figures. Copyright</h2> Copyright and related rights waived via CC0</a>. Decentralized Employment System 2024-08-04T00:00:00+00:00 Abstract</h2> This ERC proposes a Decentralized Employment System (DES) built on the Ethereum blockchain. The DES facilitates the creation and management of companies, records comprehensive employment histories through unique employee tokens, enables the formation and execution of labor contracts, automates salary payments via an escrow mechanism, incorporates a robust moderation system for dispute resolution, and implements a reputation-based review system for both employers and employees. By leveraging blockchain's transparency and immutability, the DES ensures accountability and trust throughout the employment lifecycle, from company creation and hiring to contract fulfillment and termination. The system operates post employee testing and prior to the final hiring and contract signing. Employees possess a Soulbound Token (SBT) representing their employment history, which companies review before finalizing labor contracts. This token-based approach ensures a secure and verifiable employment record that enhances the hiring process's integrity. Motivation</h2> Traditional employment systems are centralized, opaque, and often lack trust. The DES aims to introduce transparency, immutability, and trust into the employment process by leveraging blockchain technology. By recording employment history on-chain, enabling decentralized company creation, automating contract enforcement, and providing mechanisms for dispute resolution, the DES promotes a fairer and more transparent employment ecosystem. Additionally, the system streamlines the hiring process by securely managing employment records and automating contractual obligations. Specification</h2> Solidity Interface</h3> To provide a clear and standardized way for developers to interact with the DES, the following Solidity interface outlines the primary functions and events of the system: pragma solidity ^0.8.0; /// @title Decentralized Employment System Interface interface IDecentralizedEmploymentSystem { // Events event CompanyRegistered(uint companyId, address owner, string name, string industry); event EmployeeTokenMinted(uint tokenId, address employee); event ContractCreated(uint contractId, uint companyId, uint employeeTokenId, uint salary, uint duration); event ContractExecuted(uint contractId); event SalaryDeposited(uint contractId, uint amount); event SalaryReleased(uint contractId, address employee); event DisputeRaised(uint contractId, address raisedBy); event DisputeResolved(uint contractId, bool decisionForEmployee); event ContractTerminated(uint contractId, string reason); event ReviewSubmitted(uint contractId, uint rating, string comments); // Company Management function registerCompany(string calldata name, string calldata industry) external returns (uint companyId); function getCompany(uint companyId) external view returns (string memory name, string memory industry, address owner, uint[] memory employeeIds); // Employee Management function mintEmployeeToken(address employee, string calldata metadataURI) external returns (uint tokenId); function getEmploymentHistory(uint employeeTokenId) external view returns (uint[] memory contractIds); // Labor Contracts function createContract(uint companyId, uint employeeTokenId, uint salary, uint duration, string calldata responsibilities, string calldata terminationConditions) external returns (uint contractId); function executeContract(uint contractId) external; // Payment System function depositSalary(uint contractId) external payable; function releaseSalary(uint contractId) external; // Dispute Resolution function raiseDispute(uint contractId) external; function resolveDispute(uint contractId, bool decisionForEmployee) external; // Contract Termination function terminateContract(uint contractId, string calldata reason) external; // Review System function submitReview(uint contractId, uint rating, string calldata comments) external; function getReviews(uint contractId) external view returns (Review[] memory); // Structures struct Review { uint rating; string comments; address reviewer; } }</code></pre>Detailed Function Specifications</h3> 1. Company Management</h4> a. Company Registration Function: registerCompany(string calldata name, string calldata industry) external returns (uint companyId)</code> </li> Description: Allows users to register a new company on the blockchain. Each company is assigned a unique companyId</code> and associated with the caller's address as the owner. </li> Parameters: name</code>: The name of the company.</li> industry</code>: The industry sector of the company.</li> </ul> </li> Returns: companyId</code>: A unique identifier for the registered company.</li> </ul> </li> </ul> b. Retrieve Company Profile Function: getCompany(uint companyId) external view returns (string memory name, string memory industry, address owner, uint[] memory employeeIds)</code> </li> Description: Retrieves the profile details of a registered company, including its name, industry, owner address, and a list of associated employee token IDs. </li> Parameters: companyId</code>: The unique identifier of the company.</li> </ul> </li> Returns: name</code>: Name of the company.</li> industry</code>: Industry sector of the company.</li> owner</code>: Ethereum address of the company owner.</li> employeeIds</code>: Array of employee token IDs associated with the company.</li> </ul> </li> </ul> 2. Employee Management</h4> a. Employee Tokenization Function: mintEmployeeToken(address employee, string calldata metadataURI) external returns (uint tokenId)</code> </li> Description: Mints a Soulbound Token (SBT) representing an employee. The token contains metadata about the employee, such as professional credentials, stored off-chain and referenced via metadataURI</code>. </li> Parameters: employee</code>: Ethereum address of the employee.</li> metadataURI</code>: URI pointing to the employee's metadata.</li> </ul> </li> Returns: tokenId</code>: A unique identifier for the employee token.</li> </ul> </li> </ul> b. Retrieve Employment History Function: getEmploymentHistory(uint employeeTokenId) external view returns (uint[] memory contractIds)</code> </li> Description: Fetches the complete employment history of an employee by returning an array of associated contractIds</code>. </li> Parameters: employeeTokenId</code>: The unique identifier of the employee's token.</li> </ul> </li> Returns: contractIds</code>: Array of contract IDs representing the employee's employment history.</li> </ul> </li> </ul> 3. Labor Contracts</h4> a. Contract Creation Function: createContract(uint companyId, uint employeeTokenId, uint salary, uint duration, string calldata responsibilities, string calldata terminationConditions) external returns (uint contractId)</code> </li> Description: Enables a company to create a new labor contract with an employee. This function assigns a unique contractId</code> to the contract. </li> Parameters: companyId</code>: The unique identifier of the company initiating the contract.</li> employeeTokenId</code>: The unique identifier of the employee's token.</li> salary</code>: The agreed-upon salary for the contract period.</li> duration</code>: Duration of the contract in months.</li> responsibilities</code>: Description of the employee's responsibilities.</li> terminationConditions</code>: Conditions under which the contract can be terminated.</li> </ul> </li> Returns: contractId</code>: A unique identifier for the newly created contract.</li> </ul> </li> </ul> b. Contract Execution Function: executeContract(uint contractId) external</code> </li> Description: Activates the contract by marking it as active once both the company and the employee have agreed to the terms by signing the transaction with their respective wallets. </li> Parameters: contractId</code>: The unique identifier of the contract to be executed.</li> </ul> </li> </ul> 4. Payment System</h4> a. Salary Deposits Function: depositSalary(uint contractId) external payable</code> </li> Description: Allows the company to deposit the agreed salary into the contract's escrow. The function ensures that the deposited amount matches the contract's salary. </li> Parameters: contractId</code>: The unique identifier of the contract for which the salary is being deposited.</li> </ul> </li> Payable: Yes, the function is payable to accept the salary funds. </li> </ul> b. Automated Payments Function: releaseSalary(uint contractId) external</code> </li> Description: Releases the salary from escrow to the employee's address based on the contract's payment schedule or upon contract completion. </li> Parameters: contractId</code>: The unique identifier of the contract for which the salary is being released.</li> </ul> </li> </ul> 5. Dispute Resolution</h4> a. Dispute Initiation Function: raiseDispute(uint contractId) external</code> </li> Description: Allows either party involved in the contract to initiate a dispute. This action triggers the assignment of a moderator to resolve the issue. </li> Parameters: contractId</code>: The unique identifier of the contract in dispute.</li> </ul> </li> </ul> b. Dispute Resolution Function: resolveDispute(uint contractId, bool decisionForEmployee) external</code> </li> Description: Enables the assigned moderator to resolve the dispute by making a decision. If the decision favors the employee, escrow funds are transferred accordingly; otherwise, they may be returned to the company. </li> Parameters: contractId</code>: The unique identifier of the contract under dispute.</li> decisionForEmployee</code>: Boolean indicating if the decision favors the employee.</li> </ul> </li> </ul> 6. Contract Termination</h4> a. Termination Conditions Function: terminateContract(uint contractId, string calldata reason) external</code> </li> Description: Allows the company to terminate the contract based on predefined conditions. This function updates the contract status to "terminated." </li> Parameters: contractId</code>: The unique identifier of the contract to be terminated.</li> reason</code>: The reason for termination.</li> </ul> </li> </ul> 7. Review System</h4> a. Submit Review Function: submitReview(uint contractId, uint rating, string calldata comments) external</code> </li> Description: Enables both companies and employees to submit reviews post-contract. Reviews include a rating and comments, contributing to the reputation score of both parties. </li> Parameters: contractId</code>: The unique identifier of the contract being reviewed.</li> rating</code>: Numerical rating reflecting the experience.</li> comments</code>: Detailed feedback about the contract.</li> </ul> </li> </ul> b. Retrieve Reviews Function: getReviews(uint contractId) external view returns (Review[] memory)</code> </li> Description: Retrieves all reviews associated with a specific contract. </li> Parameters: contractId</code>: The unique identifier of the contract whose reviews are being fetched.</li> </ul> </li> Returns: Review[]</code>: An array of reviews related to the contract.</li> </ul> </li> </ul> Employment History</h3> Immutable Records: Employment history is maintained as an array of contract IDs linked to each employee's Soulbound Token (SBT). This ensures that all employment records are permanently and immutably stored on the blockchain. </li> Public Accessibility: Employment history data is publicly accessible through the getEmploymentHistory</code> function, allowing companies to verify an employee's past engagements before finalizing contracts. </li> </ol> Payment System</h3> Salary Deposits: Companies deposit salaries into an escrow managed by the smart contract by calling depositSalary</code>. The contract ensures that funds are securely held until payment conditions are satisfied. </li> Automated Payments: Salaries are released automatically or upon triggering the releaseSalary</code> function, ensuring timely and condition-based payments to employees. </li> </ol> Moderation and Dispute Resolution</h3> Dispute Initiation and Resolution: Either party can raise disputes, which are then resolved by assigned moderators. Moderators act as impartial arbitrators to ensure fair outcomes based on contract terms and evidence provided.</li> </ol> Firing Employees</h3> Termination Conditions: Companies can terminate contracts based on predefined conditions, with the option for dispute resolution if termination is contested.</li> </ol> Review System</h3> Reputation Scores: Reviews contribute to the reputation scores of both companies and employees, fostering accountability and encouraging positive behavior within the ecosystem.</li> </ol> Rationale</h2> Employee Tokenization: Utilizing Soulbound Tokens (SBTs) to represent employees ensures that each employee has a unique, non-transferable identity on the blockchain. This design choice enhances the integrity of employment records, making them tamper-proof and verifiable. It also allows companies to access a comprehensive employment history before finalizing contracts, promoting transparency.</li> </ul> </li> Escrow System for Salary Payments: Implementing an escrow mechanism secures salary payments, ensuring that funds are only released when contractual obligations are met. This system protects both employees and companies by guaranteeing that salaries are available and that payments are contingent on contract fulfillment.</li> </ul> </li> Moderation and Dispute Resolution: Incorporating a moderation system allows for the resolution of disputes that cannot be automatically enforced by smart contracts. Moderators provide necessary human oversight in complex employment matters, ensuring fair and just outcomes.</li> </ul> </li> Public Employment History: Making employment history publicly accessible fosters trust and accountability. It allows potential employers to verify past employment and credentials, reducing the risk of fraud and enhancing the credibility of employees within the ecosystem.</li> </ul> </li> Review System: A reputation-based review system encourages positive interactions and behaviors among users. By allowing both companies and employees to submit reviews, the system promotes mutual accountability and helps build reliable reputations.</li> </ul> </li> </ol> Test Cases</h2> Company Creation Input A user calls registerCompany("TechCorp", "Technology")</code>. Expected State Changes </li> A new companyId</code> is generated (e.g., companyId = 1</code>). </li> The companies</code> mapping is updated: </li> </ul> </li> </ol> companies[1]↦{ name="TechCorp", industry="Technology", owner=callerAddress, employeeIds=[ ] }</code></pre> An event CompanyRegistered</code> is emitted with the arguments (1, callerAddress, "TechCorp", "Technology")</code>.</li> </ul> Expected Output Return Value: companyId = 1</code> (the newly created company ID).</li> Event: CompanyRegistered</code> is logged.</li> </ul> Employee Token Minting Input The contract owner (or an authorized address) calls mintEmployeeToken(employeeAddress, "ipfs://metadataURI")</code>. Expected State Changes </li> A new token ID is generated (e.g., tokenId = 5</code>). </li> An internal mapping (e.g., employeeTokenToOwner</code>) is updated: </li> </ul> employeeTokenToOwner[5]↦employeeAddress</code></pre> (Optional) If the implementation tracks metadata, another mapping (e.g., employeeTokenMetadata</code>) might store:</li> </ul> employeeTokenMetadata[5]↦"ipfs://metadataURI"</code></pre> An event EmployeeTokenMinted</code> is emitted with (5, employeeAddress)</code>. Expected Output </li> Return Value: tokenId = 5</code> (the newly minted employee token ID). </li> Event: EmployeeTokenMinted</code> is logged. </li> </ul> </li> Contract Creation and Execution Input A company with companyId = 1</code> calls:</li> </ol> createContract(1,5,1000,6,"SoftwareDevelopment","Failuretomeetdeadlines")</code></pre> which returns contractId</code>. 2. Both the company and the employee call executeContract(contractId)</code>. Expected State Changes Contract Creation: A new labor contract ID is generated, e.g., contractId = 10</code>.</li> The contracts</code> mapping is updated:</li> </ol> contracts[10]↦{ companyId=1, employeeTokenId=5, salary=1000, duration=6, responsibilities="SoftwareDevelopment", terminationConditions="Failuretomeetdeadlines",status="Created" }</code></pre> The system may also update a per-company or per-employee tracking structure (optional but typical):</li> </ol> companyContracts[1].push(10) employeeContracts[5].push(10)</code></pre> An event ContractCreated</code> is emitted with arguments (10, 1, 5, 1000, 6)</code>.</li> </ol> </li> Contract Execution: Upon calls from both parties, the contract’s status changes from "Created"</code> to "Active"</code>:</li> </ol> contracts[10].status↦"Active"</code></pre> An event ContractExecuted</code> is emitted with (10)</code> once both signatures/confirmations are received. Expected Output</li> </ol> </li> Return Value (from createContract</code>): contractId = 10</code> </li> Event: ContractCreated(10, 1, 5, 1000, 6)</code> upon creation. </li> Event: ContractExecuted(10)</code> once execution is confirmed by both parties. </li> </ul> </li> Salary Deposit Input The company (owner of companyId = 1</code>) calls depositSalary(10)</code> and sends 1000 USDC</code> (or equivalent in wei for an ERC-20</a> token or native token) to the contract. Expected State Changes</li> </ul> The contract’s escrow balance mapping is updated:</li> </ol> escrowBalances[10]↦1000</code></pre> An event SalaryDeposited</code> is emitted with (10, 1000)</code>. Expected Output</li> </ol> Event: SalaryDeposited(10, 1000)</code></li> The contract’s internal escrowBalances[10]</code> should now be 1000</code>.</li> </ul> </li> Salary Payment Input After the contract’s duration or satisfaction of any release condition, releaseSalary(10)</code> is called (by the contract or the employee). Expected State Changes</li> </ul> The escrow balance for contractId = 10</code> is transferred to the employee token owner (employeeAddress</code> associated with token ID 5</code>).</li> The escrowBalances[10]</code> is set to 0</code>:</li> </ol> escrowBalances[10]↦0</code></pre> An event SalaryReleased</code> is emitted with (10, employeeAddress)</code>. Expected Output</li> </ol> Event: SalaryReleased(10, employeeAddress)</code></li> The updated escrowBalances[10]</code> is now 0</code>.</li> The employee’s on-chain balance (or token balance if using ERC-20</a>) increases by 1000</code>.</li> </ul> </li> Employment Termination Input The company calls terminateContract(10, "Failure to meet deadlines")</code>. Expected State Changes</li> </ul> The contracts[10].status</code> is updated to "Terminated"</code>:</li> </ol> contracts[10].status↦"Terminated"</code></pre> An event ContractTerminated</code> is emitted with (10, "Failure to meet deadlines")</code>. Expected Output</li> </ol> Event: ContractTerminated(10, "Failure to meet deadlines")</code></li> The contracts[10]</code> status is now "Terminated"</code>.</li> No further salary obligations exist unless otherwise specified in dispute-resolution processes.</li> </ul> </li> Dispute Resolution Input Either party (company or employee) calls raiseDispute(10)</code>.</li> The assigned moderator calls resolveDispute(10, true)</code> indicating the decision favors the employee. Expected State Changes</li> </ol> Dispute Raised: The contract’s dispute status is noted (implementation-specific, but typically contracts[10].disputeRaised = true</code>).</li> An event DisputeRaised(10, msg.sender)</code> is emitted.</li> </ol> </li> Dispute Resolved: If decisionForEmployee == true</code>, any remaining escrow funds for contractId = 10</code> are transferred to the employee.</li> A DisputeResolved(10, true)</code> event is emitted. Expected Output</li> </ol> </li> Event: DisputeRaised(10, msg.sender)</code> </li> Event: DisputeResolved(10, true)</code> </li> If funds remain in escrow, escrowBalances[10]</code> is set to 0</code>, and the employee receives the outstanding balance. </li> </ul> </li> </ol> Security Considerations</h2> Contract Integrity: Ensure that all labor contracts are immutable and cannot be tampered with once created and executed. </li> Fund Security: Salaries are securely held in escrow, and only released based on predefined conditions to prevent unauthorized access or misuse. </li> Moderator Trust: Implement a decentralized and transparent system for selecting and monitoring moderators to maintain impartiality and trust in dispute resolutions. </li> Review System: Incorporate safeguards against fraudulent reviews, such as verifying the association of reviews with legitimate contract completions, to maintain accurate and trustworthy reputation scores. </li> Token Security: Use Soulbound Tokens (SBTs) for employee representation to prevent token transfers and ensure that employment records are securely tied to the respective individuals. </li> </ol> Copyright</h2> Copyright and related rights waived via CC0</a>. Forward compatible consensus data structures 2024-04-15T00:00:00+00:00 Abstract</h2> This EIP defines the changes needed to adopt ProgressiveContainer</code> from EIP-7495</a> and ProgressiveList</code> from EIP-7916</a> in consensus data structures. Motivation</h2> Ethereum's consensus data structures make heavy use of Simple Serialize (SSZ)</a> Container</code>, which defines how they are serialized and merkleized. The merkleization scheme allows application implementations to verify that individual fields (and partial fields) have not been tampered with. This is useful, for example, in smart contracts of decentralized staking pools that wish to verify that participating validators have not been slashed. While SSZ Container</code> defines how data structures are merkleized, the merkleization is prone to change across the different forks. When that happens, e.g., because new features are added or old features get removed, existing verifier implementations need to be updated to be able to continue processing proofs. ProgressiveContainer</code>, of EIP-7495</a>, is a forward compatible alternative that guarantees a forward compatible merkleization scheme. By transitioning consensus data structures to use ProgressiveContainer</code>, smart contracts that contain verifier logic no longer have to be maintained in lockstep with Ethereum's fork schedule as long as the underlying features that they verify don't change. For example, as long as the concept of slashing is represented using the boolean slashed</code> field, existing verifiers will not break when unrelated features get added or removed. This is also true for off-chain verifiers, e.g., in hardware wallets or in operating systems for mobile devices that are on a different software update cadence than Ethereum. 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. Container</code> conversion</h3> Container</code> types that are expected to evolve over forks SHALL be redefined as ProgressiveContainer(active_fields=[1] len(type.fields()))</code>. For example, given a type in the old fork: class Foo(Container): a: uint8 b: uint16</code></pre> This type can be converted to support stable Merkleization in the new fork: class Foo(ProgressiveContainer(active_fields=[1, 1])): a: uint8 b: uint16</code></pre> As part of the conversion, a stable generalized index (gindex)</a> is assigned to each field that remains valid in future forks. If a fork appends a field, active_fields</code> MUST be extended with a trailing 1</code>.</li> If a fork removes a field, the corresponding active_fields</code> bit MUST be changed to 0</code>.</li> Compatibility rules SHOULD be enforced, e.g., by defining a CompatibleUnion[fork_1.Foo, fork_2.Foo, fork_3.Foo, ...]</code> type in the unit test framework.</li> </ul> List[type, N]</code> / Bitlist</code> conversion</h3> List</code> types frequently have been defined with excessively large capacities N</code> with the intention that N</code> is never reached in practice. In other cases, the capacity itself has changed over time. List</code> types with dynamic or unbounded capacity semantics SHALL be redefined as ProgressiveList[type]</code>, and the application logic SHALL be updated to check for an appropriate limit at runtime.</li> Bitlist</code> types with dynamic or unbounded capacity semantics SHALL be redefined as ProgressiveBitlist</code></li> </ul> As part of the conversion, a stable generalized index (gindex)</a> is assigned to each list element that remains valid regardless of the number of added elements. Converted types</h3> The following types SHALL be converted to ProgressiveContainer</code>: Attestation</code></a> The aggregation_bits</code> field is redefined to use ProgressiveBitlist</code></li> </ul> </li> IndexedAttestation</code></a> The attesting_indices</code> field is redefined to use ProgressiveList</code></li> </ul> </li> ExecutionPayload</code></a> The transactions</code> and withdrawals</code> fields are redefined to use ProgressiveList</code></li> The MAX_TRANSACTIONS_PER_PAYLOAD</code> (1M) limit is no longer enforced (the limit is unreachable with MAX_PAYLOAD_SIZE</code> 10 MB)</li> </ul> </li> ExecutionRequests</code></a> The deposits</code>, withdrawals</code> and consolidations</code> fields are redefined to use ProgressiveList</code></li> </ul> </li> BeaconBlockBody</code></a> The proposer_slashings</code>, attester_slashings</code>, attestations</code>, deposits</code>, voluntary_exits</code> and bls_to_execution_changes</code> fields are redefined to use ProgressiveList</code></li> </ul> </li> BeaconState</code></a> The validators</code>, balances</code>, previous_epoch_participation</code>, current_epoch_participation</code>, inactivity_scores</code>, pending_deposits</code>, pending_partial_withdrawals</code> and pending_consolidations</code> fields are redefined to use ProgressiveList</code></li> </ul> </li> The blob_kzg_commitments</code>, kzg_proofs</code> and column</code> fields are redefined to use ProgressiveList</code></li> </ul> Immutable types</h3> These types are used as part of the ProgressiveContainer</code> definitions, and, as they are not ProgressiveContainer</code> themselves, are considered to have immutable Merkleization. If a future fork requires changing these types in an incompatible way, a new type SHALL be defined and assigned a new field name. Type</th> Description</th></tr></thead> Slot</code></a></td> Slot number on the beacon chain</td></tr> Epoch</code></a></td> Epoch number on the beacon chain, a group of slots</td></tr> CommitteeIndex</code></a></td> Index of a committee within a slot</td></tr> ValidatorIndex</code></a></td> Unique index of a beacon chain validator</td></tr> Gwei</code></a></td> Amount in Gwei (1 ETH = 10^9 Gwei = 10^18 Wei)</td></tr> Root</code></a></td> Byte vector containing an SSZ Merkle root</td></tr> Hash32</code></a></td> Byte vector containing an opaque 32-byte hash</td></tr> Version</code></a></td> Consensus fork version number</td></tr> BLSPubkey</code></a></td> Cryptographic type representing a BLS12-381 public key</td></tr> BLSSignature</code></a></td> Cryptographic type representing a BLS12-381 signature</td></tr> KZGCommitment</code></a></td> G1 curve point for the KZG polynomial commitment scheme</td></tr> Fork</code></a></td> Consensus fork information</td></tr> Checkpoint</code></a></td> Tuple referring to the most recent beacon block up through an epoch's start slot</td></tr> Validator</code></a></td> Information about a beacon chain validator</td></tr> AttestationData</code></a></td> Vote that attests to the availability and validity of a particular consensus block</td></tr> Eth1Data</code></a></td> Target tracker for importing deposits from transaction logs</td></tr> DepositData</code></a></td> Log data emitted as part of a transaction's receipt when depositing to the beacon chain</td></tr> BeaconBlockHeader</code></a></td> Consensus block header</td></tr> ProposerSlashing</code></a></td> Tuple of two equivocating consensus block headers</td></tr> Deposit</code></a></td> Tuple of deposit data and its inclusion proof</td></tr> VoluntaryExit</code></a></td> Consensus originated request to exit a validator from the beacon chain</td></tr> SignedVoluntaryExit</code></a></td> Tuple of voluntary exit request and its signature</td></tr> SyncAggregate</code></a></td> Cryptographic type representing an aggregate sync committee signature</td></tr> ExecutionAddress</code></a></td> Byte vector containing an account address on the execution layer</td></tr> Transaction</code></a></td> Byte list containing an RLP encoded transaction</td></tr> WithdrawalIndex</code></a></td> Unique index of a withdrawal from any validator's balance to the execution layer</td></tr> Withdrawal</code></a></td> Withdrawal from a beacon chain validator's balance to the execution layer</td></tr> DepositRequest</code></a></td> Tuple of flattened deposit data and its sequential index</td></tr> WithdrawalRequest</code></a></td> Execution originated request to withdraw from a validator to the execution layer</td></tr> ConsolidationRequest</code></a></td> Execution originated request to consolidate two beacon chain validators</td></tr> BLSToExecutionChange</code></a></td> Request to register the withdrawal account address of a beacon chain validator</td></tr> SignedBLSToExecutionChange</code></a></td> Tuple of withdrawal account address registration request and its signature</td></tr> ParticipationFlags</code></a></td> Participation tracker of a beacon chain validator within an epoch</td></tr> HistoricalSummary</code></a></td> Tuple combining a historical block root and historical state root</td></tr> PendingDeposit</code></a></td> Pending operation for depositing to a beacon chain validator</td></tr> PendingPartialWithdrawal</code></a></td> Pending operation for withdrawing from a beacon chain validator</td></tr> PendingConsolidation</code></a></td> Pending operation for consolidating two beacon chain validators</td></tr> </tbody></table> Rationale</h2> Best timing?</h3> Applying this EIP breaks hash_tree_root</code> and Merkle tree verifiers a single time, while promising forward compatibility from the fork going forward. It is best to apply it before merkleization would be broken by different changes. Merkleization is broken by a Container</code> reaching a new power of 2 in its number of fields. Can this be applied retroactively?</h3> While ProgressiveContainer</code> serializes in the same way as the legacy Container</code>, the merkleization and hash_tree_root</code> of affected data structures changes. Therefore, verifiers that wish to process Merkle proofs of legacy variants still need to support the corresponding legacy schemes. Immutability</h3> Once a field in a ProgressiveContainer</code> has been published, its name can no longer be used to represent a different type in the future. This is in line with historical management of certain cases: Phase0: BeaconState</code> contained previous_epoch_attestations</code> / current_epoch_attestations</code></li> Altair: BeaconState</code> replaced these fields with previous_epoch_participation</code> / current_epoch_participation</code></li> </ul> Furthermore, new fields have to be appended at the end of ProgressiveContainer</code>. This is in line with historical management of other cases: Capella appended historical_summaries</code> to BeaconState</code> instead of squeezing the new field next to historical_roots</code></li> </ul> With ProgressiveContainer</code>, stable Merkleization requires these rules to become strict. Cleanup opportunities</h3> BeaconState</code></h4> The eth1_data</code>, eth1_data_votes</code>, eth1_deposit_index</code> and deposit_requests_start_index</code> fields could be dropped as they are no longer needed after the EIP-6110</a> transition period finishes.</li> historical_summaries</code> could be redefined to use ProgressiveList</code> and also integrate the historical historical_roots</code> data by merging in full HistoricalSummary</code> data from an archive (historical_root</code> is frozen since Capella), simplifying access to historical block and state roots.</li> </ul> Attestation</code></h4> The committee_bits</code> is defined as a Bitvector</code>, but the top bits are forced to 0 based on get_committee_count_per_slot(state, data.target.epoch)</code>. It could be re-defined as a ProgressiveBitlist</code>.</li> </ul> IndexedAttestation</code></h4> The attesting_indices</code> are limited to MAX_VALIDATORS_PER_COMMITTEE * MAX_COMMITTEES_PER_SLOT</code></a>, which is insufficient when the IndexedAttestation</code> is formed from SingleAttestation</code></a> traffic. SingleAttestation</code> allows validators that are not assigned to a slot to produce signatures that are not aggregatable into an Attestation</code> (as such validators are not assigned), but that are still slashable. Further, MAX_ATTESTER_SLASHINGS_ELECTRA</code></a> at 1 limits inclusion efficiency of slashings in non-finality scenarios with a lot of forks where slashings happen across multiple different AttestationData</code> values. Limits could be rethought to be based on actual resource usage, e.g., by limiting: The total number of attesting_indices</code> across all AttesterSlashing</code> (shared total)</li> The total number of signature checks across all AttesterSlashing</code>, ProposerSlashing</code>, VoluntaryExit</code>, and SignedBLSToExecutionChange</code> messages</li> </ul> Limiting totals rather than individual resources would allow extra attester slashings to be included at the cost of potentially delaying inclusion of a couple altruistic messages (if there even are any VoluntaryExit</code> / SignedBLSToExecutionChange</code> messages at that time), thus increasing security and block packing efficiency. ExecutionPayload</code></h4> The block_hash</code> field could be moved to the top of ExecutionPayload</code>, reducing the Merkle proof size. ExecutionRequests</code></h4> As deposits cannot be retried by the user (they pay the ETH upfront), deposit requests cannot fizzle like other requests; they are always included in the same block (since Pectra). For that reason, the current MAX_DEPOSIT_REQUESTS_PER_PAYLOAD</code> (8192) is essentially unbounded at current gas limits, but may eventually become reachable (around ~192M gas, or earlier with gas repricings). The CL limit for deposit requests could be dropped to avoid scaling issues, instead solely relying on EL backpressure (gas fees, 1 ETH deposit minimum). For other requests (withdrawal / consolidation requests), a shared total limit based on the added CL state size could provide more flexibility than the current per-operation limits. For example, in times without consolidation requests, space could be used to enqueue more withdrawal requests. BeaconBlockHeader</code></h4> The BeaconBlockHeader</code> is currently proposed to be kept as is. Updating the BeaconBlockHeader</code> to ProgressiveContainer</code> is tricky as it breaks hash_tree_root(latest_block_header)</code> in the BeaconState</code>. One option could be to store latest_block_header_root</code> separately, possibly also incorporating the block proposer signature into the hash to avoid proposer signature checks while backfilling historical blocks. Validator</code></h4> The Validator</code> container is currently proposed to be kept as is. Updating the Validator</code> to ProgressiveContainer</code> would add an extra hash for each validator; validators are mostly immutable so rarely need to be re-hashed. With a conversion, implementations may have to incrementally construct the new Validator</code> entries ahead of the fork when validator counts are high. It should be evaluated whether the hashing overhead is worth a clean transition to future fields, e.g., for holding postquantum keys. Also consider that such a transition may also involve a new hash function, which is a breaking change to the Merkle proofs, so generalized indices do not have to be stable across that transition. Backwards Compatibility</h2> Existing Merkle proof verifiers need to be updated to support the new Merkle tree shape. This includes verifiers in smart contracts on different blockchains and verifiers in hardware wallets, if applicable. Security Considerations</h2> Before this EIP, all List</code> types had a fixed upper bound, enabling implementations to reject messages exceeding that size early. With ProgressiveList</code>, that is no longer possible, as there is no more maximum message size. Instead, the length checks have to be implemented as part of P2P gossip validation, and as part of the state transition logic. However, many of the limits are not practically reachable (e.g., the gas limit is reached before the maximum payload size). Further note that SSZ is simple enough that clever implementations could still enforce those length checks on the serialized data, before fully decoding it. All data inbound via libp2p is decrypted, then uncompressed with Snappy, then hashed with MESSAGE_DOMAIN_VALID_SNAPPY</code> / MESSAGE_DOMAIN_INVALID_SNAPPY</code> prefix depending on whether the decompression worked to compute the libp2p message ID, while honoring a global MAX_PAYLOAD_SIZE</code> message size limit. This has to be done even if the underlying SSZ data ends up being invalid. As SSZ does not use variable-length encoding, it does not have uncontrolled blowup (no 1 byte becomes 100 MB). Therefore, attempting to decode a MAX_PAYLOAD_SIZE</code> message before checking dynamic List</code> limits does not decrease security. Any intentional DoS attacks can already target a heavier portion of the processing pipeline (e.g., by sending invalid BLS signatures, or by sending invalid Snappy data that still needs to be hashed to compute the message ID). Therefore, the EIP does not notably impact security. Copyright</h2> Copyright and related rights waived via CC0</a>. Paymaster Web Service Capability 2024-04-03T00:00:00+00:00 Abstract</h2> With EIP-5792</a>, apps can communicate with wallets about advanced features via capabilities. This proposal defines a capability that allows apps to request that ERC-4337</a> wallets communicate with a specified paymaster web service. To support this, we also define a standardized API for paymaster web services. Motivation</h2> App developers want to start sponsoring their users' transactions using paymasters. Paymasters are commonly used via web services. However, there is currently no way for apps to tell wallets to communicate with a specific paymaster web service. Similarly, there is no standard for how wallets should communicate with these services. We need both a way for apps to tell wallets to communicate with a specific paymaster web service and a communication standard for wallets to do so. Specification</h2> One new EIP-5792</a> wallet capability is defined. We also define a standard interface for paymaster web services as a prerequisite. Paymaster Web Service Interface</h3> We define two JSON-RPC methods to be implemented by paymaster web services. pm_getPaymasterStubData</code></h4> Returns stub values to be used in paymaster-related fields of an unsigned user operation for gas estimation. Accepts an unsigned user operation, entrypoint address, chain id, and a context object. Paymaster service providers can define fields that app developers should use in the context object. This method MAY return paymaster-specific gas values if applicable to the provided EntryPoint version. For example, if provided with EntryPoint v0.7, this method MAY return paymasterVerificationGasLimit</code>. Furthermore, for EntryPoint v0.7, this method MUST return a value for paymasterPostOpGasLimit</code>. This is because it is the paymaster that pays the postOpGasLimit, so it cannot trust the wallet to estimate this amount. The wallet SHOULD use these provided gas values when submitting the UserOperation</code> to a bundler for gas estimation. This method MAY also return a sponsor</code> object with a name</code> field and an optional icon</code> field. The name</code> field is the name of the party sponsoring the transaction, and the icon</code> field is a URI pointing to an image. Wallet developers MAY choose to display sponsor information to users. The icon</code> string MUST be a data URI as defined in [RFC-2397]. The image SHOULD be a square with 96x96px minimum resolution. The image format is RECOMMENDED to be either lossless or vector based such as PNG, WebP or SVG to make the image easy to render on the wallet. Since SVG images can execute Javascript, wallets MUST render SVG images using the <img></code> tag to ensure no untrusted Javascript execution can occur. There are cases where a call to just pm_getPaymasterStubData</code> is sufficient to provide valid paymaster-related user operation fields, e.g. when the paymasterData</code> does not contain a signature. In such cases, the second RPC call to pm_getPaymasterData</code> (defined below) MAY be skipped, by returning isFinal: true</code> by this RPC call. Paymaster web services SHOULD do validations on incoming user operations during pm_getPaymasterStubData</code> execution and reject the request at this stage if it would not sponsor the operation. pm_getPaymasterStubData</code> RPC Specification</h5> Note that the user operation parameter does not include a signature, as the user signs after all other fields are populated. // [userOp, entryPoint, chainId, context] type GetPaymasterStubDataParams = [ // Below is specific to Entrypoint v0.6 but this API can be used with other entrypoint versions too { sender: `0x${string}`; nonce: `0x${string}`; initCode: `0x${string}`; callData: `0x${string}`; callGasLimit: `0x${string}`; verificationGasLimit: `0x${string}`; preVerificationGas: `0x${string}`; maxFeePerGas: `0x${string}`; maxPriorityFeePerGas: `0x${string}`; }, // userOp `0x${string}`, // EntryPoint `0x${string}`, // Chain ID Record<string, any> // Context ]; type GetPaymasterStubDataResult = { sponsor?: { name: string; icon?: string }; // Sponsor info paymaster?: string; // Paymaster address (entrypoint v0.7) paymasterData?: string; // Paymaster data (entrypoint v0.7) paymasterVerificationGasLimit?: `0x${string}`; // Paymaster validation gas (entrypoint v0.7) paymasterPostOpGasLimit?: `0x${string}`; // Paymaster post-op gas (entrypoint v0.7) paymasterAndData?: string; // Paymaster and data (entrypoint v0.6) isFinal?: boolean; // Indicates that the caller does not need to call pm_getPaymasterData };</code></pre>pm_getPaymasterStubData</code> Example Parameters</h6> [ { "sender": "0x...", "nonce": "0x...", "initCode": "0x", "callData": "0x...", "callGasLimit": "0x...", "verificationGasLimit": "0x...", "preVerificationGas": "0x...", "maxFeePerGas": "0x...", "maxPriorityFeePerGas": "0x..." }, "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789", "0x2105", { // Illustrative context field. These should be defined by service providers. "policyId": "962b252c-a726-4a37-8d86-333ce0a07299" } ]</code></pre>pm_getPaymasterStubData</code> Example Return Value</h6> Paymaster services MUST detect which entrypoint version the account is using and return the correct fields. For example, if using entrypoint v0.6: { "sponsor": { "name": "My App", "icon": "https://..." }, "paymasterAndData": "0x..." }</code></pre> If using entrypoint v0.7: { "sponsor": { "name": "My App", "icon": "https://..." }, "paymaster": "0x...", "paymasterData": "0x..." }</code></pre> If using entrypoint v0.7, with paymaster gas estimates: { "sponsor": { "name": "My App", "icon": "https://..." }, "paymaster": "0x...", "paymasterData": "0x...", "paymasterVerificationGasLimit": "0x...", "paymasterPostOpGasLimit": "0x..." }</code></pre> Indicating that the caller does not need to make a pm_getPaymasterData</code> RPC call: { "sponsor": { "name": "My App", "icon": "https://..." }, "paymaster": "0x...", "paymasterData": "0x...", "isFinal": true }</code></pre>pm_getPaymasterData</code></h4> Returns values to be used in paymaster-related fields of a signed user operation. These are not stub values and will be used during user operation submission to a bundler. Similar to pm_getPaymasterStubData</code>, accepts an unsigned user operation, entrypoint address, chain id, and a context object. pm_getPaymasterData</code> RPC Specification</h5> Note that the user operation parameter does not include a signature, as the user signs after all other fields are populated. // [userOp, entryPoint, chainId, context] type GetPaymasterDataParams = [ // Below is specific to Entrypoint v0.6 but this API can be used with other entrypoint versions too { sender: `0x${string}`; nonce: `0x${string}`; initCode: `0x${string}`; callData: `0x${string}`; callGasLimit: `0x${string}`; verificationGasLimit: `0x${string}`; preVerificationGas: `0x${string}`; maxFeePerGas: `0x${string}`; maxPriorityFeePerGas: `0x${string}`; }, // userOp `0x${string}`, // Entrypoint `0x${string}`, // Chain ID Record<string, any> // Context ]; type GetPaymasterDataResult = { paymaster?: string; // Paymaster address (entrypoint v0.7) paymasterData?: string; // Paymaster data (entrypoint v0.7) paymasterAndData?: string; // Paymaster and data (entrypoint v0.6) };</code></pre>pm_getPaymasterData</code> Example Parameters</h6> [ { "sender": "0x...", "nonce": "0x...", "initCode": "0x", "callData": "0x...", "callGasLimit": "0x...", "verificationGasLimit": "0x...", "preVerificationGas": "0x...", "maxFeePerGas": "0x...", "maxPriorityFeePerGas": "0x..." }, "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789", "0x2105", { // Illustrative context field. These should be defined by service providers. "policyId": "962b252c-a726-4a37-8d86-333ce0a07299" } ]</code></pre>pm_getPaymasterData</code> Example Return Value</h6> Paymaster services MUST detect which entrypoint version the account is using and return the correct fields. For example, if using entrypoint v0.6: { "paymasterAndData": "0x..." }</code></pre> If using entrypoint v0.7: { "paymaster": "0x...", "paymasterData": "0x..." }</code></pre>paymasterService</code> Capability</h3> The paymasterService</code> capability is implemented by both apps and wallets. App Implementation</h4> Apps need to give wallets a paymaster service URL they can make the above RPC calls to. They can do this using the paymasterService</code> capability as part of an EIP-5792</a> wallet_sendCalls</code> call. wallet_sendCalls</code> Paymaster Capability Specification</h5> type PaymasterCapabilityParams = { url: string; context: Record<string, any>; }</code></pre>wallet_sendCalls</code> Example Parameters</h6> [ { "version": "1.0", "chainId": "0x01", "from": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", "calls": [ { "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", "value": "0x9184e72a", "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675" }, { "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", "value": "0x182183", "data": "0xfbadbaf01" } ], "capabilities": { "paymasterService": { "url": "https://...", "context": { "policyId": "962b252c-a726-4a37-8d86-333ce0a07299" } } } } ]</code></pre> The wallet will then make the above paymaster RPC calls to the URL specified in the paymasterService</code> capability field. Wallet Implementation</h4> To conform to this specification, smart wallets that wish to leverage app-sponsored transactions: MUST indicate to apps that they can communicate with paymaster web services via their response to an EIP-5792</a> wallet_getCapabilities</code> call.</li> SHOULD make calls to and use the values returned by the paymaster service specified in the capabilities field of an EIP-5792</a> wallet_sendCalls</code> call. An example of an exception is a wallet that allows users to select a paymaster provided by the wallet. Since there might be cases in which the provided paymaster is ultimately not used—either due to service failure or due to a user selecting a different, wallet-provided paymaster—applications MUST NOT assume that the paymaster it provides to a wallet is the entity that pays for transaction fees.</li> </ol> wallet_getCapabilities</code> Response Specification</h5> type PaymasterServiceCapability = { supported: boolean; };</code></pre>wallet_getCapabilities</code> Example Response</h6> { "0x2105": { "paymasterService": { "supported": true } }, "0x14A34": { "paymasterService": { "supported": true } } }</code></pre> Below is a diagram illustrating the full wallet_sendCalls</code> flow, including how a wallet might implement the interaction. Rationale</h2> Gas Estimation</h3> The current loose standard for paymaster services is to implement pm_sponsorUserOperation</code>. This method returns values for paymaster-related user operation fields and updated gas values. The problem with this method is that paymaster service providers have different ways of estimating gas, which results in different estimated gas values. Sometimes these estimates can be insufficient. As a result we believe it’s better to leave gas estimation up to the wallet, as the wallet has more context on how user operations will get submitted (e.g. which bundler they will get submitted to). Then wallets can ask paymaster services to sponsor given the estimates defined by the wallet. The above reason is also why we specify that the pm_getPaymasterStubData</code> method MAY also return paymaster-specific gas estimates. I.e., bundlers are prone to insufficiently estimating the paymaster-specific gas values, and the paymaster servies themselves are ultimately better equipped to provide them. Chain ID Parameter</h3> Currently, paymaster service providers typically provide developers with a URL per chain. That is, paymaster service URLs are not typically multichain. So why do we need a chain ID parameter? We recognize that we must specify some constraint so that wallets can communicate with paymaster services about which chain their requests are for. As we see it, there are two options: Formalize the current loose standard and require that paymaster service URLs are 1:1 with chains.</li> Require a chain ID parameter as part of paymaster service requests.</li> </ol> We feel that option (2) is the better abstraction here. This allows service providers to offer multichain URLs if they wish at essentially no downside to providers who offer a URL per chain. Providers who offer a URL per chain would just need to accept an additional parameter that they can ignore. When an app developer who uses a URL-per-chain provider wants to submit a request to a different chain, they can just swap out the URL accordingly. Challenges With Stub Data</h3> Enabling a workflow with greater flexibility in gas estimations will nonetheless come with some known challenges that paymaster services must be aware of in order to ensure reliable gas estimates are generated during the process. preVerificationGas</code></h4> The preVerificationGas</code> value is largely influenced by the size of the user operation and it's ratio of zero to non-zero bytes. This can cause a scenario where pm_getPaymasterStubData</code> returns values that results in upstream gas estimations to derive a lower preVerificationGas</code> compared to what pm_getPaymasterData</code> would require. If this occurs then bundlers will return an insufficient preVerificationGas</code> error during eth_sendUserOperation</code>. To avoid this scenario, a paymaster service MUST return stub data that: Is of the same length as the final data.</li> Has an amount of zero bytes (0x00</code>) that is less than or equal to the final data.</li> </ol> Consistent Code Paths</h4> In the naive case, a stub value of repeating non-zero bytes (e.g. 0x01</code>) that is of the same length as the final value will generate a usable preVerificationGas</code>. Although this would immediately result in a gas estimation error given that the simulation will likely revert due to an invalid paymaster data. In a more realistic case, a valid stub can result in a successful simulation but still return insufficient gas limits. This can occur if the stub data causes validatePaymasterUserOp</code> or postOp</code> functions to simulate a different code path compared to the final value. For example, if the simulated code was to return early, the estimated gas limits would be less than expected which would cause upstream out of gas</code> errors once a user operation is submitted to the bundler. Therefore, a paymaster service MUST also return a stub that can result in a simulation executing the same code path compared to what is expected of the final user operation. Security Considerations</h2> The URLs paymaster service providers give to app developers commonly have API keys in them. App developers might not want to pass these API keys along to wallets. To remedy this, we recommend that app developers provide a URL to their app's backend, which can then proxy calls to paymaster services. Below is a modified diagram of what this flow might look like. This flow would allow developers to keep their paymaster service API keys secret. Developers might also want to do additional simulation / validation in their backends to ensure they are sponsoring a transaction they want to sponsor. Copyright</h2> Copyright and related rights waived via CC0</a>. Temporary Approval Extension for ERC-20 2024-04-02T00:00:00+00:00 Abstract</h2> This specification defines the minimum interface required to temporarily approve ERC-20</a> tokens for spending within the same transaction. Motivation</h2> User are often required to set a token approval that will only be used once. It is common to leave unexpected approvals after these interactions. EIP-1153</a> introduces TSTORE</code>, which can be used to efficiently handle temporarily allowances. 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. Compliant contracts MUST implement 1 new function in addition to ERC-20</a>: function temporaryApprove(address spender, uint256 value) public returns (bool success)</code></pre> A call to temporaryApprove(spender, value)</code> allows spender</code> to withdraw within the same transaction on behalf of msg.sender</code> multiple times, such that the total withdrawn is less than or equal to the value</code> amount. This temporary allowance is to be considered in addition to the normal (persistent) ERC-20</a> allowance. The total value that spender is able to spend during the transaction is thus capped by the sum of the temporary and the normal (persistent) allowances. While it SHOULD be possible for a transferFrom</code> operation to consume both types of allowance, the consumption of the temporary allowance SHOULD take priority over the consumption of the persistent allowance. Therefore, if the temporary allowance is sufficient for executing a transferFrom</code> operation, the persistent allowance SHOULD not be loaded/updated from the storage. Consumption of persistent allowance, which implies storage accesses, SHOULD be performed only if the temporary allowance is not sufficient for the operation being executed. Each temporary allowance MUST persist until the end of the transaction that created it (unless overwritten by another call to temporaryApprove</code> or consumed by a call to transferFrom</code>). Each temporary allowance MUST be cleared at the end of the transaction that created it. See Using Transient Storage</a> for an example. Compliant contracts MUST add a temporary allowance to the permanent one when returning the allowed amount to spend in the allowance</code> function. In case the sum of the temporary and permanent allowance overflow, type(uint256).max</code> MUST be returned. Rationale</h2> It was decided to make minimal interface extension to allow easier integration of a compliant contract into the existing infrastructure. This affects the backward compatibility of the allowance</code> function. However, the required changes to the transferFrom</code> function implementation satisfy the requirement to explicitly authorize the spender to transfer tokens. Backwards Compatibility</h2> All functionality of the ERC-20</a> standard is backward compatible except for the allowance</code> function. Reference Implementation</h2> Using Transient Storage</h3> The storage for the temporary allowances must be different to that of the regular allowance. Compliant contracts may use the transient storage EIP-1153</a> to keep the temporary allowance. For each owner</code> and spender</code>, the slot should be uniquely selected to avoid slot collision. Each slot index should be derived from the base slot index for temporary allowances, owner</code> and spender</code> addresses. Slot may be derived as keccak256(spender . keccak256(owner . p))</code> where .</code> is concatenation and p</code> is keccak256</code> from the string uniquely defining temporary allowances in the namespace of the implementing contract. Events</h3> Even though no event is required when setting a temporary allowance, compliant contracts may emit TransientApproval(address indexed owner, address indexed spender, uint256 value)</code> event. Security Considerations</h2> The method of deriving slot identifiers to store temporary allowances must avoid collision with other slots in the same space (e.g. transient storage). Copyright</h2> Copyright and related rights waived via CC0</a>. ERC-721 Ownership Shares Extension 2024-02-20T00:00:00+00:00 Abstract</h2> This proposal introduces an attribute of ownership and profit share quantities for each token under an NFT. This attribute signifies a stake in the ownership and profit rights associated with the NFT's specific privileges, enabling the querying, transferring, and approval of these shares, thereby making the shares represented by each token applicable in a broader range of use cases. Motivation</h2> At times, when we wish to distribute dividends or assign rights to tokens of an NFT based on their share of ownership, it becomes necessary to equip each token with an attribute indicating the number of ownership shares. While ERC-1155</a> allows for the representation of ownership stakes through the balance of a token held by a wallet address, it sacrifices the uniqueness of each token. Conversely, ERC-721</a> maintains the uniqueness of each token but lacks an attribute to signify the share of ownership rights, and its metadata does not allow for the free transfer of these share quantities by the token owner. This extension seeks to merge the features of ERC-1155</a> and ERC-721</a>, enabling holders of each share to possess characteristics akin to those of a token owner, thus bridging the gap between share representation and token uniqueness. 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. Implementers of this extension MUST have all of the following functions: pragma solidity ^0.8.0; interface IERC7628 / is IERC721 / { /// @notice Returns the number of decimal places used for ownership shares. /// @return The number of decimal places for ownership shares. function shareDecimals() external view returns (uint8); /// @notice Returns the total sum of ownership shares in existence for all tokens. /// @return The total sum of ownership shares. function totalShares() external view returns (uint256); /// @notice Returns the ownership share of the specified token. /// @param tokenId The identifier of the token. /// @return The ownership share of the token. function shareOf(uint256 tokenId) external view returns (uint256); /// @notice Returns the share allowance granted to the specified spender by the owner for the specified token. /// @param tokenId The identifier of the token. /// @param spender The address of the spender. /// @return The share allowance granted to the spender. function shareAllowance(uint256 tokenId, address spender) external view returns (uint256); /// @notice Approves the specified address to spend a specified amount of shares on behalf of the caller. /// @param tokenId The identifier of the token. /// @param spender The address of the spender. /// @param shares The amount of shares to approve. function approveShare(uint256 tokenId, address spender, uint256 shares) external; /// @notice Transfers ownership shares from one token to another. /// @param fromTokenId The identifier of the sender token. /// @param toTokenId The identifier of the recipient token. /// @param shares The amount of shares to transfer. function transferShares(uint256 fromTokenId, uint256 toTokenId, uint256 shares) external; /// @notice Transfers ownership shares from one token to another address (resulting in a new token or increased shares at the recipient address). /// @param fromTokenId The identifier of the sender token. /// @param to The address of the recipient. /// @param shares The amount of shares to transfer. function transferSharesToAddress(uint256 fromTokenId, address to, uint256 shares) external; /// @notice Adds a specified amount of shares to a token, only callable by the contract owner. /// @param tokenId The identifier of the token. /// @param shares The amount of shares to add. function addSharesToToken(uint256 tokenId, uint256 shares) external; /// @notice Emitted when ownership shares are transferred from one token to another. /// @param fromTokenId The identifier of the sender token. /// @param toTokenId The identifier of the recipient token. /// @param amount The amount of shares transferred. event SharesTransfered(uint256 indexed fromTokenId, uint256 indexed toTokenId, uint256 amount); /// @notice Emitted when an approval is granted for a spender to spend shares on behalf of an owner. /// @param tokenId The token identifier. /// @param spender The address of the spender. /// @param amount The amount of shares approved. event SharesApproved(uint256 indexed tokenId, address indexed spender, uint256 amount); }</code></pre>Rationale</h2> Share Issuance to a Token</h4> Issuing additional shares to a token allows for flexible management of ownership stakes in digital assets, catering to the evolving needs of stakeholders. It ensures transparency and security in modifying ownership structures directly on the blockchain, facilitating scenarios like profit sharing or investment adjustments. Transferring Shares to an Address</h4> Enabling shares to be transferred to an address enhances NFT liquidity and accessibility by allowing fractional ownership. This feature supports diverse use cases like fractional sales or collateralization, making NFTs more adaptable and inclusive for a broader audience. Backwards Compatibility</h2> This standard is fully ERC-721</a> compatible. Reference Implementation</h2> pragma solidity ^0.8.0; import "@openzeppelin/contracts/token/ERC721/ERC721.sol"; import "@openzeppelin/contracts/access/Ownable.sol"; import "@openzeppelin/contracts/security/ReentrancyGuard.sol"; contract ERC7628 is IERC7628, ERC721, Ownable, ReentrancyGuard { mapping(uint256 => uint256) private _shareBalances; mapping(uint256 => mapping(address => uint256)) private _shareAllowances; uint256 private _totalShares; uint256 private _nextTokenId; constructor(address initialOwner) ERC721("MyToken", "MTK") Ownable(initialOwner) {} function addSharesToToken(uint256 tokenId, uint256 shares) public override onlyOwner { require(tokenId > 0, "ERC7628: tokenId cannot be zero"); _shareBalances[tokenId] += shares; _totalShares += shares; emit SharesTransfered(0, tokenId, shares); } function shareDecimals() external pure override returns (uint8) { return 18; } function totalShares() external view override returns (uint256) { return _totalShares; } function shareOf(uint256 tokenId) external view override returns (uint256) { return _shareBalances[tokenId]; } function shareAllowance(uint256 tokenId, address spender) external view override returns (uint256) { return _shareAllowances[tokenId][spender]; } function approveShare(uint256 tokenId, address spender, uint256 shares) external override { require(spender != ownerOf(tokenId), "ERC7628: approval to current owner"); require(msg.sender == ownerOf(tokenId), "ERC7628: approve caller is not owner"); _shareAllowances[tokenId][spender] = shares; emit SharesApproved(tokenId, spender, shares); } function transferShares(uint256 fromTokenId, uint256 toTokenId, uint256 shares) external override nonReentrant { require(_shareBalances[fromTokenId] >= shares, "ERC7628: insufficient shares for transfer"); require(_isApprovedOrOwner(msg.sender, fromTokenId), "ERC7628: transfer caller is not owner nor approved"); _shareBalances[fromTokenId] -= shares; _shareBalances[toTokenId] += shares; emit SharesTransfered(fromTokenId, toTokenId, shares); } function transferSharesToAddress(uint256 fromTokenId, address to, uint256 shares) external override nonReentrant { require(_shareBalances[fromTokenId] >= shares, "ERC7628: insufficient shares for transfer"); require(_isApprovedOrOwner(msg.sender, fromTokenId), "ERC7628: transfer caller is not owner nor approved"); _nextTokenId++; _safeMint(to, _nextTokenId); _shareBalances[_nextTokenId] = shares; emit SharesTransfered(fromTokenId, _nextTokenId, shares); } // Helper function to check if an address is the owner or approved function _isApprovedOrOwner(address spender, uint256 tokenId) internal view returns (bool) { return (spender == ownerOf(tokenId) || getApproved(tokenId) == spender || isApprovedForAll(ownerOf(tokenId), spender)); } }</code></pre>Security Considerations</h2> Clear Approvals on Transfer</h4> When transferring token ownership, it is crucial to clear all existing approvals. This precaution prevents previously authorized parties from retaining access after the token has changed hands. Prevent Reentrancy</h4> Implementations must guard against reentrancy attacks. This involves ensuring that functions altering balances or ownership are secure against such vulnerabilities, particularly during share transfers. Validate IDs and Addresses</h4> Verifying the legitimacy of token IDs and wallet addresses in all operations is essential. This step helps avoid errors and ensures that tokens and their associated shares are handled correctly. Manage Shares on Ownership Change</h4> Proper management of share quantities is vital during a token ownership transfer. It's important to ensure that shares are accurately accounted for and transferred alongside the token to maintain the integrity of ownership stakes. Copyright</h2> Copyright and related rights waived via CC0</a>. ERC-20 Holder Extension for NFTs 2024-01-05T00:00:00+00:00 Abstract</h2> This proposal suggests an extension to ERC-721</a> to enable easy exchange of ERC-20</a> tokens. By enhancing ERC-721</a>, it allows unique tokens to manage and trade ERC-20</a> fungible tokens bundled in a single NFT. This is achieved by including methods to pull ERC-20</a> tokens into the NFT contract to a specific NFT, and transferring them out by the owner of such NFT. A transfer out nonce is included to prevent front-running issues. Motivation</h2> In the ever-evolving landscape of blockchain technology and decentralized ecosystems, interoperability between diverse token standards has become a paramount concern. By enhancing ERC-721</a> functionality, this proposal empowers non-fungible tokens (NFTs) to engage in complex transactions, facilitating the exchange of fungible tokens, unique assets, and multi-class assets within a single protocol. This ERC introduces new utilities in the following areas: Expanded use cases</li> Facilitating composite transactions</li> Market liquidity and value creation</li> </ul> Expanded Use Cases</h3> Enabling ERC-721</a> tokens to handle various token types opens the door to a wide array of innovative use cases. From gaming and digital collectibles to decentralized finance (DeFi) and supply chain management, this extension enhances the potential of NFTs by allowing them to participate in complex, multi-token transactions. Facilitating Composite Transactions</h3> With this extension, composite transactions involving both fungible and non-fungible assets become easier. This functionality is particularly valuable for applications requiring intricate transactions, such as gaming ecosystems where in-game assets may include a combination of fungible and unique tokens. Market Liquidity and Value Creation</h3> By allowing ERC-721</a> tokens to hold and trade different types of tokens, it enhances liquidity for markets in all types of tokens. Specification</h2> interface IERC7590 /is IERC165, IERC721/ { /** * @notice Used to notify listeners that the token received ERC-20 tokens. * @param erc20Contract The address of the ERC-20 smart contract * @param toTokenId The ID of the token receiving the ERC-20 tokens * @param from The address of the account from which the tokens are being transferred * @param amount The number of ERC-20 tokens received */ event ReceivedERC20( address indexed erc20Contract, uint256 indexed toTokenId, address indexed from, uint256 amount ); /** * @notice Used to notify the listeners that the ERC-20 tokens have been transferred. * @param erc20Contract The address of the ERC-20 smart contract * @param fromTokenId The ID of the token from which the ERC-20 tokens have been transferred * @param to The address receiving the ERC-20 tokens * @param amount The number of ERC-20 tokens transferred */ event TransferredERC20( address indexed erc20Contract, uint256 indexed fromTokenId, address indexed to, uint256 amount ); /** * @notice Used to retrieve the given token's specific ERC-20 balance * @param erc20Contract The address of the ERC-20 smart contract * @param tokenId The ID of the token being checked for ERC-20 balance * @return The amount of the specified ERC-20 tokens owned by a given token */ function balanceOfERC20( address erc20Contract, uint256 tokenId ) external view returns (uint256); /** * @notice Transfer ERC-20 tokens from a specific token. * @dev The balance MUST be transferred from this smart contract. * @dev MUST increase the transfer-out-nonce for the tokenId * @dev MUST revert if the `msg.sender` is not the owner of the NFT or approved to manage it. * @param erc20Contract The address of the ERC-20 smart contract * @param tokenId The ID of the token to transfer the ERC-20 tokens from * @param amount The number of ERC-20 tokens to transfer * @param data Additional data with no specified format, to allow for custom logic */ function transferHeldERC20FromToken( address erc20Contract, uint256 tokenId, address to, uint256 amount, bytes memory data ) external; /** * @notice Transfer ERC-20 tokens to a specific token. * @dev The ERC-20 smart contract must have approval for this contract to transfer the ERC-20 tokens. * @dev The balance MUST be transferred from the `msg.sender`. * @param erc20Contract The address of the ERC-20 smart contract * @param tokenId The ID of the token to transfer ERC-20 tokens to * @param amount The number of ERC-20 tokens to transfer * @param data Additional data with no specified format, to allow for custom logic */ function transferERC20ToToken( address erc20Contract, uint256 tokenId, uint256 amount, bytes memory data ) external; /** * @notice Nonce increased every time an ERC20 token is transferred out of a token * @param tokenId The ID of the token to check the nonce for * @return The nonce of the token */ function erc20TransferOutNonce( uint256 tokenId ) external view returns (uint256); }</code></pre>Rationale</h2> Pull Mechanism</h3> We propose using a pull mechanism, where the contract transfers the token to itself, instead of receiving it via "safe transfer" for 2 reasons: Customizability with Hooks. By initiating the process this way, smart contract developers have the flexibility to execute specific actions before and after transferring the tokens. </li> Lack of transfer with callback: ERC-20</a> tokens lack a standardized transfer with callback method, such as the "safeTransfer" on ERC-721</a>, which means there is no reliable way to notify the receiver of a successful transfer, nor to know which is the destination token is. </li> </ol> This has the disadvantage of requiring approval of the token to be transferred before actually transferring it into an NFT. Granular vs Generic</h3> We considered 2 ways of presenting the proposal: A granular approach where there is an independent interface for each type of held token.</li> A universal token holder which could also hold and transfer ERC-721</a> and ERC-1155</a>.</li> </ol> An implementation of the granular version is slightly cheaper in gas, and if you're using just one or two types, it's smaller in contract size. The generic version is smaller and has single methods to send or receive, but it also adds some complexity by always requiring Id and amount on transfer methods. Id not being necessary for ERC-20</a> and amount not being necessary for ERC-721</a>. We also considered that due to the existence of safe transfer methods on both ERC-721</a> and ERC-1155</a>, and the commonly used interfaces of IERC721Receiver</code> and IERC1155Receiver</code>, there is not much need to declare an additional interface to manage such tokens. However, this is not the case for ERC-20</a>, which does not include a method with a callback to notify the receiver of the transfer. For the aforementioned reasons, we decided to go with a granular approach. Backwards Compatibility</h2> No backward compatibility issues found. Test Cases</h2> Tests are included in erc7590.ts</code></a>. To run them in terminal, you can use the following commands: cd ../assets/eip-erc7590 npm install npx hardhat test</code></pre>Reference Implementation</h2> See ERC7590Mock.sol</code></a>. Security Considerations</h2> The same security considerations as with ERC-721</a> apply: hidden logic may be present in any of the functions, including burn, add resource, accept resource, and more. Caution is advised when dealing with non-audited contracts. Implementations MUST use the message sender as from parameter when they are transferring tokens into an NFT. Otherwise, since the current contract needs approval, it could potentially pull the external tokens into a different NFT. When transferring ERC-20</a> tokens in or out of an NFT, it could be the case that the amount transferred is not the same as the amount requested. This could happen if the ERC-20</a> contract has a fee on transfer. This could cause a bug on your Token Holder contract if you do not manage it properly. There are 2 ways to do it, both of which are valid: Use the IERC20</code> interface to check the balance of the contract before and after the transfer, and revert if the balance is not the expected one, hence not supporting tokens with fees on transfer.</li> Use the IERC20</code> interface to check the balance of the contract before and after the transfer, and use the difference to calculate the amount of tokens that were actually transferred.</li> </ol> To prevent a seller from front running the sale of an NFT holding ERC-20</a> tokens to transfer out such tokens before a sale is executed, marketplaces MUST beware of the erc20TransferOutNonce</code> and revert if it has changed since listed. ERC-20</a> tokens that are transferred directly to the NFT contract will be lost. Copyright</h2> Copyright and related rights waived via CC0</a>. Interest Rate Swaps 2023-12-31T00:00:00+00:00 Abstract</h2> This proposal introduces a standardized framework for on-chain interest rate swaps. The proposed standard aims to facilitate the seamless exchange of fixed and floating interest rate cash flows between parties, providing a foundation for decentralized finance (DeFi) applications. Motivation</h2> Interest Rate Swapping (IRS) denotes a derivative contract wherein two parties mutually consent to exchange a series of forthcoming interest payments based on a specified notional amount. This financial instrument serves as a strategic tool for hedging against interest rate fluctuations. The mechanism entails the utilization of a benchmark index to facilitate the exchange between a variable interest rate and a fixed rate. Despite its widespread use, there is currently an absence of a standardized framework that enables the representation of IRS contracts on blockchain platforms. This proposal addresses this gap by establishing a consistent and transparent methodology for representing IRS contracts within the blockchain environment. By doing so, it would enhance the interoperability, security, and efficiency of interest rate swap transactions on distributed ledger technology. 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. Example Flow</h3> Every contract compliant with this ERC MUST implement the following interface. The contract MUST inherit from ERC-20</a> to tokenize the swap cash flows. pragma solidity ^0.8.0; /** * @title ERC-7586 Interest Rate Swaps */ interface IERC7586 /** is ERC20, ERC165 */ { // events /** * @notice MUST be emitted when interest rates are swapped * @param _amount the interest difference to be transferred * @param _account the recipient account to send the interest difference to. MUST be either the `payer` or the `receiver` */ event Swap(uint256 _amount, address _account); /** * @notice MUST be emitted when the swap contract is terminated * @param _payer the swap payer * @param _receiver the swap receiver */ event TerminateSwap(address indexed _payer, address indexed _receiver); // functions /** * @notice Returns the IRS `payer` account address. The party who agreed to pay fixed interest */ function fixedRatePayer() external view returns(address); /** * @notice Returns the IRS `receiver` account address. The party who agreed to pay floating interest */ function floatingRatePayer() external view returns(address); /** * @notice Returns the number of decimals the swap rate and spread use - e.g. `4` means to divide the rates by `10000` * To express the interest rates in basis points unit, the decimal MUST be equal to `2`. This means rates MUST be divided by `100` * 1 basis point = 0.01% = 0.0001 * ex: if interest rate = 2.5%, then swapRate() => 250 `basis points` */ function ratesDecimals() external view returns(uint8); /** * @notice Returns the fixed interest rate. All rates MUST be multiplied by 10^(ratesDecimals) */ function swapRate() external view returns(uint256); /** * @notice Returns the floating rate spread, i.e. the fixed part of the floating interest rate. All rates MUST be multiplied by 10^(ratesDecimals) * floatingRate = benchmark + spread */ function spread() external view returns(uint256); /** * @notice Returns the day count basis * For example, 0 can denote actual/actual, 1 can denote actual/360, and so on */ function dayCountBasis() external view returns(uint8); /** * @notice Returns the contract address of the currency for which the notional amount is denominated (Example: USDC contract address). * Returns the zero address if the notional is expressed in FIAT currency like USD */ function notionalCurrency() external view returns(address); /** * @notice Returns an array of acceptable contract address of the assets to be transferred when swapping IRS * The two counterparties may wish to get the payment in different currencies. * Ex: if the payer wants to receive the payment in USDC and the receiver in DAI, then the function should return [USDC, DAI] or [DAI, USDC] */ function paymentAssets() external view returns(address[] memory); /** * @notice Returns the notional amount in unit of asset to be transferred when swapping IRS. This amount serves as the basis for calculating the interest payments, and may not be exchanged * Example: If the two parties aggreed to swap interest rates in USDC, then the notional amount may be equal to 1,000,000 USDC */ function notionalAmount() external view returns(uint256); /** * @notice Returns the number of times payments must be realized in 1 year */ function paymentFrequency() external view returns(uint256); /** * @notice Returns an array of specific dates on which the fix interest payments are exchanged. Each date MUST be a Unix timestamp like the one returned by block.timestamp * The length of the array returned by this function MUST equal the total number of swaps that should be realized OPTIONAL */ function fixPaymentDates() external view returns(uint256[] memory); /** * @notice Returns an array of specific dates on which the floating interest payments are exchanged. Each date MUST be a Unix timestamp like the one returned by block.timestamp * The length of the array returned by this function MUST equal the total number of swaps that should be realized OPTIONAL */ function floatingPaymentDates() external view returns(uint256[] memory); /** * @notice Returns the starting date of the swap contract. This is a Unix Timestamp like the one returned by block.timestamp */ function startingDate() external view returns(uint256); /** * @notice Returns the maturity date of the swap contract. This is a Unix Timestamp like the one returned by block.timestamp */ function maturityDate() external view returns(uint256); /** * @notice Returns the benchmark (the reference rate). All rates MUST be multiplied by 10^(ratesDecimals) * Example: value of one the following rates: CF BIRC, EURIBOR, HIBOR, SHIBOR, SOFR, SONIA, TONAR, etc. * Or set manually */ function benchmark() external view returns(uint256); /** * @notice Returns the oracle contract address for acceptable reference rates (benchmark), or the zero address when the two parties agreed to set the benchmark manually. * This contract SHOULD be used to fetch real time benchmark rate * Example: Contract address for `CF BIRC` OPTIONAL. The two parties MAY agree to set the benchmark manually */ function oracleContractsForBenchmark() external view returns(address); /** * @notice Makes swap calculation and transfers the payment to counterparties */ function swap() external returns(bool); /** * @notice Terminates the swap contract before its maturity date. MUST be called by either the `payer`or the `receiver`. */ function terminateSwap() external; }</code></pre>Tokenization of Swap Cash Flows</h3> The interest payments associated with the IRS MUST be tokenized by issuing digital ERC-20</a> tokens to the respective parties according to the terms of the swap. Each token SHOULD represent a specific interest payment. Every time a swap happens (the swap</code> function is called), one token MUST be burned from each party. Rationale</h2> This standard allows parties involved in the IRS contract to define essential parameters such as notional amount, interest rates, payment frequency, and payment dates. This flexibility accommodates a diverse range of financial agreements, catering to the unique needs of different participants. To accommodate a wide array of use cases, the standard introduces optional features such as payment dates and manual benchmark setting. This allows parties to tailor the contract to specific requirements, while maintaining a core set of functions for essential functionality. To ensure real-time and accurate benchmark rates, the standard integrates with oracles. Parties have the option to use oracles for fetching benchmark rates, enhancing the reliability and accuracy of interest rate calculations. Backwards Compatibility</h2> This standard is backward compatible with ERC-20. Reference Implementation</h2> The complete reference implementation can be found here</a>. This reference implementation serves as a foundation for the implementation of more advanced types of swaps. Security Considerations</h2> Security considerations of various types must be thoroughly evaluated Interest Rate Risk: This pertains to the potential impact of fluctuations in interest rates.</li> Credit Risk: There exists the possibility that one or both parties may default on their respective responsibilities.</li> ERC-20 Risks: All security aspects outlined in the ERC-20 standard must be taken into account.</li> </ul> Both parties must acknowledge their awareness of these security risks before proceeding with the implementation of the standard. Copyright</h2> Copyright and related rights waived via CC0</a>. Staked ERC-721 Ownership Recognition 2023-10-01T00:00:00+00:00 Abstract</h2> The ownership of ERC-721</a> tokens when staked in a pool presents challenges, particularly when it involves older, non-lockable NFTs like, for example, Crypto Punks or Bored Ape Yacht Club (BAYC) tokens. This proposal introduces an interface to address these challenges by allowing staked NFTs to be recognized by their original owners, even after they've been staked. Motivation</h2> Recent solutions involve retaining NFT ownership while "locking" an NFT letting the owner keeping its ownership. However, this requires the NFT contract to implement lockable functionality. Early NFTs were not originally designed as lockable and so they must be staked transferring the ownership to the staking contract. This prevents the original owner from accessing valuable privileges and benefits associated with their NFTs. For example: A BAYC NFT holder would lose access to the BAYC Yacht Club and member events when staked.</li> A CryptoPunks holder may miss out on special airdrops or displays only available to verified owners.</li> Owners of other early NFTs like EtherRocks would lose the social status of provable ownership when staked.</li> </ul> By maintaining a record of the original owner, the proposed interface allows these original perks to remain accessible even when the NFT is staked elsewhere. This compatibility is critical for vintage NFT projects lacking native locking mechanisms. Another important right, is the right to use an asset. For example an NFT can be used to play a game. If the NFT is lent to a user, the ownership of the NFT is transferred to the lending contract. In this case, it can be hard to identify the wallet that has the right to us the NFT in the game, which should be the user. The interface provides a simple, elegant way to extend staking compatibility to legacy NFTs without affecting their core functionality or benefits of ownership. 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. The interface is defined as follows: interface IERC7531 { /** * @notice MUST be emitted when the token's technical owner (the contract holding the token) is different * from its actual owner (the entity with rights over the token). * @dev This scenario is common in staking, where a staking contract is the technical owner. The event MUST * be emitted in the same or any subsequent block as the Transfer event for the token. * A later Transfer event involving the same token supersedes this RightsHolderChange event. * To ensure authenticity, entities listening to this event MUST verify that the contract emitting * the event matches the token's current owner as per the related Transfer event. @param tokenAddress The address of the token contract. * @param tokenId The ID of the token. * @param holder The address of the actual rights holder of the token. * @param right The type of right held by the holder. The initial supported rights are: 0x399d2b36 // bytes4(keccak256("ownership")) * 0x230a5961 // bytes4(keccak256("usage")) This allows projects to add more rights without breaking compatibility with this interface. See IERC7531Rights for more details. */ event RightsHolderChange(address indexed tokenAddress, uint256 indexed tokenId, address indexed holder, bytes4 right); /** * @dev Returns the address of the entity with rights over the token, distinct from the current owner. * The function MUST revert if the token does not exist or is not currently held. @param tokenAddress The address of the ERC-721 contract. * @param tokenId The ID of the token. * @param right The type of right held by the holder. * @return The address of the entity with rights over the token. */ function rightsHolderOf( address tokenAddress, uint256 tokenId, bytes4 right ) external view returns (address); }</code></pre> The RightsHolderChange</code> event is crucial for accurately identifying the actual owner of a held token. In scenarios where a token is staked in a contract, the ERC-721</a> Transfer event would incorrectly assign ownership to the staking contract itself. The RightsHolderChange</code> event addresses this discrepancy by explicitly signaling the real owner of the token rights. Timing of Event Emission:</h3> The RightsHolderChange</code> event MUST be emitted either in the same block as the corresponding Transfer</code> event or in any subsequent block. This approach offers flexibility for existing pools to upgrade their systems without compromising past compatibility. Specifically, staking pools can emit this event for all previously staked tokens, or they can allow users to actively reclaim their ownership. This flexibility ensures that the system can adapt to both current and future states while accurately reflecting the actual ownership of held tokens. Invalidation of Previous RightsHolderChange</code> Events:</h3> To maintain compatibility with the broader ecosystem and optimize for gas efficiency, any new Transfer</code> event involving the same token invalidates any previous RightsHolderChange</code> event. This approach ensures that the most recent Transfer</code> event reliably reflects the current ownership status, negating the need for additional events upon unstaking. NFT extension</h3> The two default rights are: 0x399d2b36 // bytes4(keccak256("ownership"))</li> 0x230a5961 // bytes4(keccak256("usage"))</li> </ul> However, there can ben NFTs that only need to validate the ownership, others may need to validate the usage, and others may need to validate both, some other NFT may need to manage totally different rights. To give NFTs the necessary flexibility, we also propose the following OPTIONAL extension. interface IERC7531Rights { /** * @dev Returns the list of rights supported by the NFT. * @return The list of rights supported by the NFT. */ function supportedERC7531Rights() external view returns (bytes4[] memory); /** * @dev Returns whether the NFT supports a specific right. * @param right The right to check. * @return Whether the NFT supports the right. */ function supportsERC7531Right(bytes4 right) external view returns (bool); }</code></pre> It allows NFTs to return the list of rights they support, and projects to verify it an NFT supports a specific right. Since the rights are identified by the bytes4 hash of the right name, when introducing new rights, NFT projects SHOULD make public statements about the string that corresponds to the bytes4 hash and explain the rationale for it. If the NFT does not support the interface (for example, if an existing NFT), project using NFTs SHOULD consider only the standard rights. NFT Projects SHOULD adhere to pre-existing rights, when possible, to avoid the proliferation of rights that could make the system less efficient and more complex. Rationale</h2> Addressing Non-Lockable NFT Challenges:</h3> Non-lockable NFTs present a unique challenge in decentralized ecosystems, especially in scenarios involving staking or delegating usage rights. The standard ERC-721</a> ownerOf</code> function returns the current owner of the NFT, which, in the case of staking, would be the staking pool contract. This transfer of ownership to the staking pool, even if temporary, can disrupt the utility or privileges tied to the NFT, such as participation in governance, access to exclusive content, or utility within a specific ecosystem. The rightsHolderOf</code> Method:</h3> The rightsHolderOf</code> method provides a solution to this challenge. By maintaining a record of the original owner or the rightful holder of certain privileges associated with the NFT, this method ensures that the underlying utility of the NFT is preserved, even when the NFT itself is held in a pool. Technical Advantages:</h3> Preservation of Utility: This approach allows NFT owners to leverage their assets in staking pools or other smart contracts without losing access to the benefits associated with the NFT. This is particularly important for NFTs that confer ongoing benefits or rights. </li> Enhanced Flexibility: The method offers greater flexibility for NFT owners, allowing them to participate in staking and other DeFi activities without relinquishing the intrinsic benefits of their NFTs. </li> Compatibility and Interoperability: By introducing a new method instead of altering the existing ownerOf function, this EIP ensures backward compatibility with existing ERC-721</a> contracts. This is crucial for maintaining interoperability across various platforms and applications in the NFT space. </li> Event-Driven Updates: The RightsHolderChange</code> event facilitates real-time tracking of the rights-holder of an NFT. This is particularly useful for third-party platforms and services that rely on up-to-date ownership information to provide services or privileges. </li> </ol> Addressing Potential Misuse:</h3> While this approach introduces a layer of complexity, it also comes with the need for diligent implementation to prevent misuse, such as the wrongful assignment of rights. This EIP outlines security considerations and best practices to mitigate such risks. Backwards Compatibility</h2> This standard is fully backwards compatible with existing ERC-721</a> contracts. It can seamlessly integrate with existing upgradeable staking pools, provided they choose to adopt it. It does not require changes to the ERC-721</a> standard but acts as an enhancement for staking pools. Security Considerations</h2> A potential risk with this interface is the improper assignment of ownership by a staking pool to a different wallet. This could allow that wallet to access privileges associated with the NFT, which might not be intended by the true owner. However, it is important to note that this risk is lower than transferring full legal ownership of the NFT to the staking pool, as the interface only enables recognizing the staker, not replacing the actual owner on-chain. Event Authenticity:</h3> There is a concern regarding the potential emission of fake RightsHolderChange</code> events. Since any contract can emit such an event, there's a risk of misinformation or misrepresentation of ownership. It is crucial for entities listening to the RightsHolderChange</code> event to verify that the emitting contract is indeed the current owner of the token. This validation is essential to ensure the accuracy of ownership information and to mitigate the risks associated with deceptive event emissions. Reducing the Risk of Inaccurate Ownership Records:</h3> While improper use of this interface poses some risk of inaccurate ownership records, this is an inherent issue with any staking arrangement. The risk is somewhat mitigated by the fact that the owner retains custody rather than transferring ownership. Due Diligence:</h3> Consumers of privilege-granting NFTs should exercise due diligence when evaluating staking providers. Signs of mismanagement or fraud should be carefully assessed. The interface itself does not enable new manipulation capabilities, but caution is always prudent when interacting with smart contracts and staking pools. Copyright</h2> Copyright and related rights waived via CC0</a>. Dynamic Compliant Interop Security Token 2023-09-14T00:00:00+00:00 Abstract</h2> This proposal is a security token standard that extends ERC-1155</a> to provide a flexible framework for managing compliant real-asset security tokens. It introduces the concept of partitions, where each tokenId</code> represents a distinct partition with its own set of rights and privileges. This makes it suitable for various use cases, particularly semi-fungible asset management. The standard also includes features like token locking, forced transfers for recovery, address freezing, payouts, and dynamic compliance management using off-chain vouchers. Motivation</h2> The growing demand for tokenized real-world assets necessitates a token standard that can accommodate the unique requirements of security tokens. Existing standards, while powerful, do not fully address the need for flexible partitioning and comprehensive compliance management. This standard builds upon ERC-1155</a> by introducing partitions, allowing for the creation of semi-fungible tokens representing fractional ownership, different share classes, or other distinct units within a single token contract. This flexibility is crucial for tokenizing complex real-world assets like real estate or funds. Furthermore, it includes features essential for security tokens, such as token locking for vesting or holding periods, forced transfers for recovery in case of lost keys, address freezing for regulatory compliance, efficient payout mechanisms, and dynamic compliance management using off-chain vouchers. By providing a standardized interface for these features, this proposal aims to facilitate the development of interoperable and compliant security token ecosystems. Partition-Based Architecture Benefits</h3> The partition paradigm offers significant flexibility and power in managing security tokens: Dynamic Allocation : Partitions allow for dynamic allocation of tokens between different classes or categories. For example, in a real estate tokenization scenario, an issuer can initially allocate tokens to a Reg D partition for accredited U.S. investors and a "Reg S" partition for non-U.S. investors. As the offering progresses and demand shifts, the issuer can dynamically mint tokens into the appropriate partition based on the investor's eligibility, ensuring optimal distribution and compliance.</li> Temporary Non-Fungibility : Partitions enable temporary non-fungibility of tokens. In some cases, securities may need to be treated as non-fungible for a certain period, such as tokens of the same underlying asset sold at different offerings. By assigning tokens to specific partitions, issuers can enforce these restrictions and maintain the necessary segregation between them, but merge them at a later point to prevent liquidity fragmentation. Merger occurs by creating a new joint partition, a deploying a merger contract where users can deposit old partitioned tokens to receive new joint partition token.</li> Granular Compliance : Each partition can have its own set of compliance rules and transfer restrictions. This allows for more granular control over token transfers based on the specific characteristics of each partition. For instance, a partition representing a particular share class may have different transfer restrictions or payout rights compared to other partitions.</li> Efficient Asset Management : Partitions streamline the management of complex asset structures. Instead of deploying separate contracts for each share class or asset category, issuers can manage multiple partitions within a single proposed contract, reducing deployment costs and simplifying overall asset management.</li> </ol> Real World Use Cases</h3> Use Case 1: Tokenization of Commercial Real Estate</h4> In this use case, a commercial real estate property with 100 floors is being tokenized using this proposal. Each floor is represented as a unique non-fungible token (NFT) partition, allowing for fractional ownership and separate management of individual floors. Property Representation: The entire commercial property is tokenized using the proposed contract, with each floor being assigned a unique tokenId representing an NFT partition. </li> Fractional Ownership: Each floor's NFT partition can be divided into multiple fungible tokens, enabling fractional ownership. For instance, if a floor is divided into 100 tokens, multiple investors can own portions of that floor. </li> Dynamic Pricing: Since each floor is a separate partition, the pricing of tokens within a partition can be adjusted dynamically based on factors such as floor level, amenities, or market demand. This flexibility allows for accurate representation of the varying values of different floors. </li> Transfer of Ownership: The ownership of each floor's NFT partition can be transferred seamlessly to token holders using the safeTransferFrom function. This enables the seamless transfer of ownership rights for specific floors. </li> Compliance Management: Different compliance rules and transfer restrictions can be applied to each partition (floor) based on regulatory requirements or issuer-defined rules. The canTransfer function can be used to enforce these rules before allowing transfers. </li> Payouts: The payout and batchPayout functions can be used to distribute rental income, dividends, or other payouts to token holders of specific floor partitions efficiently. </li> </ol> By leveraging proposal, this use case demonstrates the ability to tokenize complex real estate assets while maintaining granular control over ownership, pricing, compliance, and payouts for individual units within the property. Use Case 2: Tokenization of Securities with Reg S and Reg D Partitions</h4> In this use case, a company is tokenizing its securities and wants to comply with different regulations for U.S. accredited investors (Reg D) and non-U.S. investors (Reg S). Initial Partitions: The company deploys an proposed standard and creates two partitions: one for Reg D investors (accredited U.S. investors) and another for Reg S investors (non-U.S. investors). </li> Dynamic Allocation: As the offering progresses, the company can dynamically mint tokens into the appropriate partition based on investor eligibility. For example, if a U.S. accredited investor wants to participate, tokens can be minted in the Reg D partition, while tokens for non-U.S. investors are minted in the Reg S partition. </li> Compliance Management: Each partition can have its own set of compliance rules and transfer restrictions. The canTransfer function can be integrated with off-chain compliance services to verify the eligibility of a transfer based on the specific rules for each partition. </li> Temporary Non-Fungibility: During the initial offering period, tokens in the Reg D and Reg S partitions may need to be treated as non-fungible due to different regulatory requirements. However, after the holding period, the company can create a new joint partition and allow token holders to deposit their old partitioned tokens to receive the new joint partition tokens, merging the two classes. </li> Payouts: The payout and batchPayout functions can be used to distribute dividends, interest payments, or other payouts to token holders in each partition based on their respective rights and privileges. </li> </ol> By utilizing the proposal, this use case demonstrates the ability to tokenize securities while maintaining compliance with different regulatory regimes, dynamically allocating tokens based on investor eligibility, and efficiently managing payouts and potential mergers of different share classes. Use Case 3: Force Transfer for AML/KYC/Compliance Violations</h4> In the world of tokenized securities, maintaining compliance with regulatory requirements is of utmost importance. This proposal provides a robust mechanism to handle situations where an investor's tokens need to be forcibly transferred due to violations of Anti-Money Laundering (AML), Know Your Customer (KYC), or other compliance-related regulations. Let's consider the scenario of Alice, an investor who holds tokens in the proposed token compliant security token contract. During the regular compliance checks conducted by the token issuer or a designated compliance service, it is discovered that Alice's wallet address is associated with suspicious activities related to money laundering or other financial crimes. In such a situation, the regulatory authorities or the contract administrators may decide to freeze Alice's account and initiate a forced transfer of her tokens to a designated address controlled by the issuer or a recovery agent. The forceTransfer</code> function in this proposal enables this process. 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. Interface</h3> pragma solidity ^0.8.0; interface IERC7518 is IERC1155, IERC165{ event TokensLocked(address indexed account, uint indexed id, uint256 amount, uint256 releaseTime); event TokenUnlocked(address indexed account, uint indexed id); event TokensForceTransferred(address indexed from, address indexed to, uint indexed id, uint256 amount); event AddressFrozen(address indexed account, bytes data); event AddressUnfrozen(address indexed account, bytes data); // Emitted when the transferability of tokens with a specific ID is restricted. event TransferRestricted(uint indexed id); // Emitted when the transferability restriction of tokens with a specific ID is removed. event TransferRestrictionRemoved(uint indexed id); event PayoutDelivered(address indexed from, address indexed to, uint256 amount); /** * @dev Retrieves the transferable balance of tokens for the specified account and ID. * @param account The address of the account. * @param id The token ID. * @return The transferable balance of tokens. */ function transferableBalance(address account, uint id) external view returns (uint); /** * @dev Retrieves the locked balance of tokens for the specified account and ID. * @param account The address of the account. * @param id The token ID. * @return The locked balance of tokens. */ function lockedBalanceOf(address account, uint256 id) external view returns (uint256); /** * @dev Restricts the transferability of tokens with the specified ID. * @param id The token ID. * @return A boolean value indicating whether the operation was successful. */ function restrictTransfer(uint id) external returns (bool); /** * @dev Removes the transferability restriction of tokens with the specified ID. * @param id The token ID. * @return A boolean value indicating whether the operation was successful. */ function removeRestriction(uint id) external returns (bool); /** * @notice Transfers `_value` amount of an `_id` from the `_from` address to the `_to` address specified (with safety call). * @dev Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard). * After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). * @param _from Source address * @param _to Target address * @param _id ID of the token type * @param _value Transfer amount * @param _data Additional data with no specified format, MUST be sent unaltered in call to `onERC1155Received` on `_to` */ function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, bytes calldata _data) override external; /** * @dev Checks if a transfer is allowed. * @param from The address to transfer tokens from. * @param to The address to transfer tokens to. * @param id The token ID. * @param amount The amount of tokens to transfer. * @param data Additional data related to the transfer. * @return status A boolean value indicating whether the transfer is allowed. */ function canTransfer(address from, address to, uint id, uint amount, bytes calldata data) external view returns (bool status); /** * @dev lock token till a particular block time. * @param account The address of the account for which tokens will be locked. * @param id The token ID. * @param amount The amount of tokens to be locked for the account. * @param releaseTime The timestamp indicating when the locked tokens can be released. * @return bool Returns true if the tokens are successfully locked, otherwise false. */ function lockTokens(address account, uint id, uint256 amount, uint256 releaseTime) external returns (bool); /** * @dev Unlocks tokens that have crossed the release time for a specific account and id. * @param account The address of the account to unlock tokens for. * @param id The token ID. */ function unlockToken(address account, uint256 id) external; /** * @dev Force transfer in cases like recovery of tokens. * @param from The address to transfer tokens from. * @param to The address to transfer tokens to. * @param id The token ID. * @param amount The amount of tokens to transfer. * @param data Additional data related to the transfer. * @return A boolean value indicating whether the operation was successful. */ function forceTransfer(address from, address to, uint256 id, uint256 amount, bytes memory data) external returns (bool); /** * @dev Freezes specified address. * @param account The address to be frozen. * @param data Additional data related to the freeze operation. * @return A boolean value indicating whether the operation was successful. */ function freezeAddress(address account, bytes calldata data) external returns (bool); /** * @dev Unfreezes specified address. * @param account The address to be unfrozen. * @param data Additional data related to the unfreeze operation. * @return A boolean value indicating whether the operation was successful. */ function unFreeze(address account, bytes memory data) external returns (bool); /** * @dev Sends payout to single address with corresponding amounts. * @param to address to send the payouts to. * @param amount amount representing the payouts to be sent. * @return A boolean indicating whether the batch payouts were successful. / function payout(address calldata to, uint256 calldata amount) public returns (bool); /** * @dev Sends batch payouts to multiple addresses with corresponding amounts. * @param to An array of addresses to send the payouts to. * @param amount An array of amounts representing the payouts to be sent. * @return A boolean indicating whether the batch payouts were successful. */ function batchPayout(address[] calldata to, uint256[] calldata amount) public returns (bool); }</code></pre>Methods for token</h3> transferableBalance</code></h3> Retrieves the transferable balance of tokens for the specified account and ID. function transferableBalance(address account,uint id) external view returns (uint)</code></pre> MUST calculate and return the transferable balance of tokens for the specified account and ID (i.e. current) balanceOf(account, id) - lockedBalanceOf(account, id)</code>.</li> </ul> lockedBalanceOf</code></h3> Retrieves the locked balance of tokens for the specified account and ID. function lockedBalanceOf(address account,uint256 id) external view returns (uint256)</code></pre> MUST retrieve and return the locked balance of tokens for the specified account</code> and id</code>.</li> </ul> restrictTransfer</code></h3> Restricts the transferability of tokens with the specified ID. function restrictTransfer(uint id) external returns (bool)</code></pre> MUST restrict the transferability of tokens with the specified id</code>.</li> SHOULD emit TransferRestricted</code>.</li> </ul> removeRestriction</code></h3> Removes the transferability restriction of tokens with the specified ID. function removeRestriction(uint id) external returns (bool)</code></pre> MUST remove the transferability restriction of tokens with the specified id</code>. MUST revert if id</code> was not previously restricted.</li> SHOULD emit TransferRestrictionRemoved</code>.</li> </ul> safeTransferFrom</code></h3> function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, bytes calldata _data) override external;</code></pre> MUST revert if _to</code> is the zero address.</li> MUST revert if balance of holder for token _id</code> is lower than the _value</code> sent.</li> MUST revert on any other error.</li> MUST emit the TransferSingle</code> event to reflect the balance change (see "Safe Transfer Rules" section of the standard).</li> MUST call canTransfer</code> function to check if the transfer can proceed</li> </ul> canTransfer</code></h3> Determine transferring a specified amount of a token from one address to another. function canTransfer(address from,address to,uint id,uint amount,bytes calldata data) external view returns (bool status);</code></pre> Accurately determine whether the transfer of tokens is allowed.</li> MUST validate to</code> and from</code> are not frozen address.</li> MUST validate id</code> of the transfer should not be restricted</li> MUST check if amount</code> is a transferable balance.</li> MAY call external contract to verify the transfer.</li> SHOULD NOT modify any state or perform any side effects.</li> </ul> lockTokens</code></h3> Locks a specified amount of tokens from an account for a specified duration. function lockTokens(address account,uint id,uint256 amount,uint256 releaseTime) external returns (bool);</code></pre> MUST enforce time-based restrictions on the transfer or use of tokens.</li> MUST revert if balance of holder is less than amount.</li> SHOULD use proper access control measures to ensure that only authorized entities can lock tokens.</li> MUST perform input validation prevent potential vulnerabilities and unauthorized locking of tokens.</li> SHOULD record release time securely and ensure that locked tokens are only released after the designated time has passed.</li> SHOULD emit TokensLocked</code>.</li> </ul> unlockToken</code></h3> Unlocks tokens that have crossed the release time for a specific account and id. function unlockToken(address account,uint256 id) external;</code></pre> MUST unlock the tokens for the specified account</code> address and id</code>.</li> MUST unlock all the token which has release time <= block.timestamp</code></li> SHOULD revert if no token are unlocked to save gas.</li> SHOULD emit TokenUnlocked</code>.</li> </ul> forceTransfer</code></h3> Force transfer in cases like recovery of tokens function forceTransfer(address from,address to,uint256 id,uint256 amount,bytes memory data) external returns (bool);</code></pre> MUST bypass normal transfer restrictions and authorization checks.</li> MUST revert if the from</code> address is not Frozen.</li> MUST revert if to</code> address is Frozen.</li> MUST ensure that only authorized entities have the capability to call this function.</li> Additional data related to the freeze operation.</li> SHOULD emit TokensForceTransferred</code>.</li> </ul> freeze</code></h3> Freezes specified address. The Freeze function takes in the account address</code> to be frozen and additional data, and returns a boolean</code> value indicating whether the operation was successful. function freezeAddress(address account,bytes data) external returns (bool);</code></pre> MUST prevent account</code> to transfer and payout.</li> SHOULD implement appropriate access control measures to ensure that only authorized addresses can be unfrozen.</li> SHOULD emit AddressFrozen</code>.</li> </ul> unFreeze</code></h3> The Unfreeze function takes in the account address</code> to be unfrozen and additional data, and returns a boolean</code> value indicating whether the operation was successful. function unFreeze(address account,bytes memory data) external returns (bool);</code></pre> MUST unfreeze the specified account</code></li> SHOULD implement appropriate access control measures to ensure that only authorized addresses can be unfrozen.</li> SHOULD emit AddressUnfrozen</code>.</li> </ul> payout</code></h3> Send payouts to single address, receiver will be receiving a specific amount of tokens. function payout(address calldata to,uint256 calldata amount) public returns (bool)</code></pre> MUST revert if to</code> address is frozen address.</li> SHOULD have sufficient balance to transfer token from issuer address.</li> SHOULD emit PayoutDelivered</code>.</li> </ul> batchPayout</code></h3> Send payouts to multiple addresses at once, with each address receiving a specific amount of tokens. It can be used for various purposes such as distributing rewards, dividends, or interest payment. function batchPayout(address[] calldata to,uint256[] calldata amount) public returns (bool)</code></pre> MUST revert if to</code> address is frozen address.</li> SHOULD have sufficient balance to transfer token from issuer address.</li> SHOULD emit PayoutDelivered</code>.</li> </ul> Interoperability</h3> This proposal facilitates interoperability with non-fungible and fungible tokens through a token wrapping method. The process involves two key components: the token contracts representing the original and the proposed token contract for the wrapped version. Users seeking to wrap their tokens interact with the wrapping contract, which securely locks their original tokens and mints an equivalent amount of the proposed tokens to their address. Conversely, unwrapping is achieved by calling the contract's withdraw function, resulting in the burning of the proposed tokens and the release of the corresponding original tokens. Events are emitted for transparency, and robust security measures are implemented to safeguard user assets and address any potential vulnerabilities in the contract code. With this design, this proposal ensures the seamless conversion and compatibility with fungible and non-fungible tokens, promoting greater utility and usability across the Ethereum ecosystem. Interface for Interoperability</h3> interface IERC1155Wrapper is IERC7518 { /** @dev Emitted when a new wrapped token address is added to the set. @param wrappedTokenAddress The address of the wrapped token that was added. */ event WrappedTokenAddressSet(address wrappedTokenAddress); /** @dev Emitted when tokens are wrapped. @param The ERC-1155 token ID of the wrapped tokens. @param amount The amount of tokens that were wrapped. */ event TokensWrapped(uint indexed id, uint256 amount); /** @dev Emitted when tokens are unwrapped. @param wrappedTokenId Is the ERC-1155 token ID of the wrapped tokens. @param amount The amount of tokens that were unwrapped. */ event TokensUnwrapped(uint indexed wrappedTokenId, uint256 amount); /** * @dev Sets the wrapped token address and logic for deciding partitions. * @param wrappedTokenAddress The address of the wrapped token contract. * @return A boolean value indicating whether the operation was successful. */ function setWrappedToken(address token) external returns (bool); /** * @dev Wraps the specified amount of tokens by depositing the original tokens and receiving new standard tokens. * @param amount The amount of tokens to wrap. * @param data Additional data for partition. * @return A boolean value indicating whether the operation was successful. */ function wrapToken(uint256 amount, bytes calldata data) external returns (bool); /** * @notice Wraps a specified amount of tokens from a given partition into the main balance. * @dev This function allows users to convert tokens from a specific partition back to the main balance,making them fungible with tokens from other partitions. * @param partitionId The unique identifier of the partition from which tokens will be wrapped. * @param id The unique identifier of the token. * @param amount The amount of tokens to be wrapped from the specified partition. * @param data Additional data that may be used to handle the wrap process (optional). * @return success A boolean indicating whether the wrapping operation was successful or not. */ function wrapTokenFromPartition(bytes32 partitionId, uint256 id, uint256 amount, bytes calldata data) external returns (bool); /** * @dev Unwraps the specified amount of wrapped tokens by depositing the current tokens and receiving the original tokens. * @param wrappedTokenId internal partition id. * @param amount The amount of wrapped tokens to unwrap. * @param data Additional data for partition. * @return A boolean value indicating whether the operation was successful. */ function unwrapToken(uint256 wrappedTokenId, uint256 amount, bytes calldata data) external returns (bool); /** * @dev Retrieves the balance of wrapped tokens for the specified account and ID. * @param account The address of the account. * @param id The token ID. * @param data Additional data for partition. * @return The balance of wrapped tokens. */ function wrappedBalanceOf(address account, uint256 id, bytes calldata data) external view returns (uint256); /** * @dev Retrieves the balance of original tokens for the specified account and ID. * @param account The address of the account. * @param id The token ID. * @param data Additional data for partition. * @return The balance of original tokens. / function originalBalanceOf(address account, uint256 id, bytes calldata data) external view returns (uint256); }</code></pre>Methods for Interoperability</h3> setWrappedTokenAddress</code></h3> function setWrappedTokenAddress(address token) external returns (bool);</code></pre> token</code> address could be any security token standard i.e ERC-3643</a>.</li> </ul> wrapToken</code></h3> function wrapToken(uint256 amount, bytes calldata data) external returns (bool);</code></pre> MUST lock token in an on-chain vault type smart contract.</li> MUST mint an equivalent amount of the proposed token.</li> MUST verify mapping of ERC-1155</a> id</code> with the corresponding ERC-20</a> compatible security token.</li> </ul> wrapTokenFromPartition</code></h3> function wrapTokenFromPartition(bytes32 partitionId, uint256 id, uint256 amount, bytes calldata data) external returns (bool);</code></pre> MUST lock the token amount from source standard and mint an equivalent amount of the proposed token.</li> SHOULD lock token in smart contract to achieve one to one mapping with the investor.</li> MUST verify mapping of id</code> with the corresponding partially fungible security token partitionId</code>.</li> </ul> unwrapToken</code></h3> function unwrapToken(uint256 wrappedTokenId, uint256 amount, bytes calldata data) external returns (bool);</code></pre> MUST burn the proposed token and release the original token.</li> MUST verify that the token is not subject to any of the proposal's locking functionality.</li> </ul> Partition Management</h3> The proposal leverages the tokenId</code> feature of ERC-1155</a> to represent distinct partitions within a token contract. Each tokenId</code> corresponds to a unique partition with its own set of rights, privileges, and compliance rules. This enables the creation of semi-fungible tokens representing fractional ownership, different share classes, or other granular units. Partition as the Fundamental Unit</h3> Each partition is created by minting tokens under a unique tokenId</code> value.</li> All tokens with the same tokenId</code> are fungible within that partition but non-fungible across partitions.</li> The issuer can represent different classes, jurisdictions, or series by minting tokens under different tokenId</code>s.</li> </ul> Compliance Management</h3> This standard includes functions for managing token transfers in accordance with regulatory requirements and issuer-defined rules. The canTransfer</code> function checks whether a transfer is allowed based on factors such as token restrictions, frozen addresses, transferable balances, and token locking. To facilitate dynamic compliance management, the standard uses a voucher-based pattern. An authorized entity (e.g., the issuer or a designated compliance service) generates a signed off-chain voucher that may encapsulate results from on-chain rule evaluation, oracle responses, or other checks. The canTransfer</code> verifies vouchers signature, expiry, and binding of from</code>, to</code>, id</code>, and amount</code> together with contract state to determine the eligibility of a transfer. Here's an example of how off-chain vouchers can be used with the proposal: The token issuer defines a set of compliance rules and requirements for token transfers.</li> When a user initiates a transfer, they submit a request to a designated compliance service with the necessary details (sender, recipient, amount, etc.).</li> The compliance service evaluates the transfer request against the predefined rules and requirements, considering factors such as investor eligibility, transfer restrictions, and regulatory compliance.</li> If the transfer is deemed compliant, the compliance service generates a signed voucher containing the relevant details and returns it to the user.</li> The user includes the signed voucher as an additional parameter when calling the safeTransferFrom</code> function on the proposed contract.</li> The canTransfer</code> function verifies the authenticity and validity of the voucher by checking the signature and ensuring that the voucher details match the transfer parameters.</li> If the voucher is valid and the transfer meets all other requirements, the transfer is allowed to proceed.</li> </ol> Implementations MAY accept a cryptographically signed compliance voucher in the data</code> argument of canTransfer</code>, and state changing transfer functions defined in this standard, for example safeTransferFrom</code>. Voucher schema and policy content are application defined. Implementations MAY combine on chain rules, oracle responses, and off chain verification for the voucher. Token Recovery</h3> In case of lost or compromised wallets, the proposal includes a forceTransfer</code> function that allows authorized entities (e.g., the issuer or a designated recovery agent) to transfer tokens from one address to another. This function bypasses the usual transfer restrictions and can be used as a recovery mechanism. Payout Management</h3> Provides functions for efficient payout distribution to token holders. The payout</code> function allows sending payouts to a single address, while batchPayout</code> enables sending payouts to multiple addresses in a single transaction. These functions streamline the process of distributing dividends, interest, or other payments to token holders. Rationale</h2> Enhancing Compliance Management</h3> The canTransfer</code> function facilitates compliance checks during token transfers, offering adaptability through diverse implementation methods such as on-chain storage, oracle utilization, or any off-chain methodologies. This versatility ensures seamless integration with existing compliance frameworks, particularly in enforcing regulatory standards like KYC/AML. Additionally, functionalities like freezeAddress</code>, restrictTransfer</code>, lockToken</code> and forceTransfer</code> empower entities to regulate token movements based on specified conditions or regulatory requirements. Complementing these, the unlockToken</code> function enhances transparency and accountability by facilitating the release of tokens post-compliance actions. Fractionalization</h3> Fractionalization in this standard is realized natively through ERC-1155</a> balances. For a given partition identified by tokenId, each unit of amount represents a fungible fraction of that partition’s underlying security. Issuers mint and burn units to manage supply. Transfers use safeTransferFrom</code> and safeBatchTransferFrom</code>, and must pass canTransfer. Locks and freezes reduce the transferable portion of balances, and forceTransfer</code> operates proportionally on units. Partitions can be merged by issuing a new tokenId and allowing holders to deposit old partitions for one-to-one or proportional conversion, and can be split by minting new tokenIds with defined conversion rules. All compliance rules and restrictions apply identically to every fractional unit in a partition. Interoperability with other standard</h3> This standard builds directly on ERC-1155</a>, which already models fractional supply, batching, and balance-based accounting with broad ecosystem support. ERC-3525</a> was carefully evaluated but intentionally not adopted as a base. Its slot-and-value abstraction overlaps almost exactly with the partition and amount</code> semantics defined here, yet inherits ERC-721</a>’s single-token overhead and per-position statefulness, which are inefficient for large scale issuance and compliance checks. Implementers who require slot-style compatibility may optionally expose ERC-3525</a> through ERC-165</a> by mapping slot</code> to partition and value</code> to amount</code>. ERC-6909</a>, while a minimal multi-token variant, omits partition metadata and compliance hooks and is therefore unsuitable for regulated assets. ERC-7518</a> extends this lineage by representing partitions as ERC-1155</a> tokenId</code>s, enabling dynamic minting, merging, and voucher based dynamic compliance that can evolve without redeployment. Overall, ERC-7518</a> uses ERC-1155</a> as its canonical substrate because it balances composability, efficiency, and regulatory flexibility, turning fractionalization into a compliance-preserving primitive rather than an auxiliary layer. The functions wrapToken</code> and wrapTokenFromPartition</code> are essential for simplifying conversions within the token system. wrapToken</code> is specifically designed for wrapping ERC-20-like tokens to this protocol, on the other hand, wrapTokenFromPartition</code> is used when we want to convert tokens from non-fungible tokens or any multi-standard token into proposed protocol. It allows for more specialized conversions, ensuring tokens from different standards can work together smoothly. The unwrapToken</code> function is used to reverse the process of wrapping tokens. When tokens are wrapped, they're usually locked or held in a special way to ensure they're used correctly. users can unlock or release these tokens, returning them to their original standard, essentially, frees up tokens that were previously locked, giving users more control over their assets in the ecosystem. Payment distribution</h3> The payout</code> function enables direct payments to individual token holders for one-off or event-triggered distributions, facilitating targeted disbursements. Meanwhile, the batchPayout</code> function processes multiple payments in a single transaction, optimizing efficiency for larger-scale or regular payouts on the blockchain Backwards Compatibility</h2> The proposal is fully compatible with ERC-1155</a> , and any ERC-1155</a> compliant wallet or marketplace can interact with the proposal's tokens. The additional functions introduced by this proposal do not conflict with the ERC-1155</a> interface, ensuring seamless integration with existing ecosystem tools and infrastructure. Security Considerations</h2> Access Control: The proposal includes functions that can significantly impact token transfers and balances, such as forceTransfer</code>, freezeAddress</code>, and lockTokens</code>. It is crucial to implement proper access control mechanisms, such as role-based permissions, to ensure that only authorized entities can execute these functions.</li> Parameter Validation: Functions like safeTransferFrom</code>, lockTokens</code>, and forceTransfer</code> should validate input parameters to prevent unauthorized or unintended actions. This includes checking for valid addresses, sufficient balances, and appropriate permissions.</li> Reentrancy Protection: The contract should implement reentrancy guards to prevent potential vulnerabilities arising from external calls, especially in functions that transfer tokens or update balances.</li> Overflow/Underflow Protection: The contract should use safe math libraries or built-in overflow protection to prevent integer overflow and underflow vulnerabilities.</li> Payout Security: The payout</code> and batchPayout</code> functions should ensure that only authorized entities can initiate payouts and that the total payout amount does not exceed the available balance. Proper access control and input validation are essential to prevent unauthorized or fraudulent payouts.</li> Off-Chain Voucher Security: When using off-chain vouchers for dynamic compliance management, it is crucial to ensure the security and integrity of the voucher generation process. The compliance service responsible for generating vouchers should have robust security measures in place to prevent unauthorized voucher creation or tampering. Additionally, the proposed contract should thoroughly validate the authenticity and validity of vouchers before allowing transfers to proceed.</li> Operational considerations for unfreezing: Unfreezing restores an account's ability to transfer and receive payouts. Implementers and operators should evaluate applicable regulatory and contractual obligations before unfreezing an address.</li> </ol> Copyright</h2> Copyright and related rights waived via CC0</a>. SSZ ProgressiveContainer 2023-08-18T00:00:00+00:00 Abstract</h2> This EIP introduces a new Simple Serialize (SSZ)</a> type to represent containers with forward-compatible Merkleization: A given field is always assigned the same stable generalized index (gindex)</a> even when different container versions append new fields or drop existing fields. Motivation</h2> SSZ containers are frequently versioned, for example across fork boundaries. When the number of fields reaches a new power of two, or a field is removed or replaced with one of a different type, the shape of the underlying Merkle tree changes, breaking verifiers of Merkle proofs for these containers. Deploying a new verifier may involve security councils to upgrade smart contract logic, or require firmware updates for embedded devices. This effort is needed even when no semantic changes apply to the fields that the verifier is interested in. Progressive containers address these shortcomings by: Using the progressive Merkle tree</a> structure to progressively grow to the actual field count with minimal overhead, ensuring provers remain valid as the field count changes.</li> Assigning stable gindices for each field across all versions by allowing gaps in the Merkle tree where a field is absent.</li> Serializing in a compact form where absent fields do not consume space.</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. ProgressiveContainer(active_fields)</code></h3> A new SSZ composite types</a> is defined: progressive container: ordered heterogeneous collection of values with stable Merkleization python dataclass notation with key-type pairs, e.g.</li> </ul> class Square(ProgressiveContainer(active_fields=[1, 0, 1])): side: uint16 # Merkleized at field index #0 (location of first 1 in `active_fields`) color: uint8 # Merkleized at field index #2 (location of second 1 in `active_fields`) class Circle(ProgressiveContainer(active_fields=[0, 1, 1])): radius: uint16 # Merkleized at field index #1 (location of first 1 in `active_fields`) color: uint8 # Merkleized at field index #2 (location of second 1 in `active_fields`)</code></pre></li> </ul> The default value</a> is defined as: Type</th> Default Value</th></tr></thead> ProgressiveContainer(active_fields)</code></td> [default(type) for type in progressive_container]</code></td></tr> </tbody></table> The following types are considered illegal</a>: ProgressiveContainer</code> with no fields are illegal.</li> ProgressiveContainer</code> with an active_fields</code> configuration of more than 256 entries are illegal.</li> ProgressiveContainer</code> with an active_fields</code> configuration ending in 0</code> are illegal.</li> ProgressiveContainer</code> with an active_fields</code> configuration with a different count of 1</code> than fields are illegal.</li> </ul> Serialization</h4> Serialization of ProgressiveContainer(active_fields)</code> is identical to Container</code></a>. Deserialization</h4> Deserialization of ProgressiveContainer(active_fields)</code> is identical to Container</code></a>. JSON mapping</h4> The canonical JSON mapping</a> is updated: SSZ</th> JSON</th> Example</th></tr></thead> ProgressiveContainer(active_fields)</code></td> object</td> { "field": ... }</code></td></tr> </tbody></table> Merkleization</h4> The SSZ Merkleization specification</a> is extended with two helper functions: get_active_fields(value)</code>, where value</code> is of type ProgressiveContainer(active_fields)</code>: return active_fields</code>.</li> mix_in_active_fields</code>: Given a Merkle root root</code> and an active_fields</code> configuration return hash(root, pack_bits(active_fields))</code>. Note that active_fields</code> is restricted to ≤ 256 bits.</li> </ul> The Merkleization definitions are extended. mix_in_active_fields(merkleize_progressive([hash_tree_root(element) for element in value]), get_active_fields(value))</code> if value</code> is a progressive container.</li> </ul> Rationale</h2> Why is active_fields</code> limited to 256 bits?</h3> 256 bits (1 word) allows the mix-in to be simple, consistent with the length mix-in for lists, and is practically sufficient. An alternate design with a ProgressiveBitlist</code> mix-in was explored, however deemed too over-engineered as it would effectively require introducing caches to pre-compute the mix-in's hash_tree_root</code> to avoid repeated computations, and also makes verifier logic more complex than necessary. Even though the 256 field limit includes all fields (including deprecated ones), it is unlikely that many progressive containers come close to reach 256 fields (BeaconState</code> currently reaches around 40 fields). If that happens, one can add a more</code> field with a nested ProgressiveContainer</code>. Why is empty ProgressiveContainer</code> an illegal type?</h3> It would result in 0-length serialization, meaning that the length of a list of such a container cannot be determined from the serialization. Optional[type]</code>?</h3> Introducing Optional</code> is not required by any current functionality and is deferred to a future EIP. The active_fields</code> bitvector can be updated to also indicate optionality. Further, serialization for sparse lists should be explored. Backwards Compatibility</h2> ProgressiveContainer(active_fields)</code> is a new SSZ type and does not conflict with existing types. Test Cases</h2> ethereum/remerkleable</code> contains static tests in test_impl.py</code> and test_typing.py</code>.</li> ethereum/consensus-specs</code> releases contain random tests in tests/general/phase0/ssz_generic</code>, generated according to a format defined in tests/format/ssz_generic</code>.</li> </ul> Reference Implementation</h2> See ethereum/remerkleable</code>. Security Considerations</h2> Light client based verifiers and smart contracts (e.g., based on EIP-4788</a>) do not update at the same cadence as Ethereum. If a future fork removes a field from a ProgressiveContainer(active_fields)</code>, the active_fields</code> mix-in enables such verifiers to distinguish absent fields from 0</code> values. Without active_fields</code>, the hash_tree_root</code> for these cases would collide. Copyright</h2> Copyright and related rights waived via CC0</a>. Token Converter 2023-07-27T00:00:00+00:00 Abstract</h2> There are multiple token standards on Ethereum chain currently. This EIP introduces a concept of cross-standard interoperability by creating a service that allows ERC-20</a> tokens to be upgraded to ERC-223</a> tokens anytime. ERC-223</a> tokens can be converted back to ERC-20</a> version without any restrictions to avoid any problems with backwards compatibility and allow different standards to co-exist and become interoperable and interchangeable. In order to perform the conversion, a user must deposit tokens of one standard to the Converter contract and it will automatically send tokens of another standard back. Motivation</h2> This proposal introduces a concept of a token standard upgrading procedure driven by a specialized smart-contract which can convert tokens of one standard to another at any time. Currently some tokens are available on different chains in different standards, for example most exchanges support ERC-20</a> USDT, TRX USDT, BEP-20 USDT and all this tokens are in fact the same USDT token. This proposal is intended to introduce a concept where there can be a ERC-20</a> USDT and ERC-223</a> USDT available on Ethereum mainnet at the same time and these would be freely interchangeable. The address of the deployed Token Converter must be described here as to solve the trust issues for the token developers and help them figure out a proper way of interacting with the Converter. As Ethereum already has an established ecosystem of tokens and ERC-20</a> is the most adopted standard at the moment the lack of defined migration processes can be a bottleneck for newer standards adoption. This proposal addresses the problem of coordinating the upgrading process and addresses the backwards compatibility problems for ERC-20</a> and ERC-223</a> tokens. The Token Converter is supposed to allow anyone to create an alternative version of an existing token implemented in a different standard. This proposal focuses on ERC-20</a> and ERC-223</a> standards and takes into account the specifics of this particular token standards. It is assumed that the most common case would be creation of ERC-223</a> version for an existing ERC-20</a> token. The implementation of this service is an alternative to convincing each token developer to choose an alternative standard at the moment of the token deployment or during the development stage of their project. With this service there will be no need to choose one standard and stick with it as every token can be available in both concurrently. The implementation of this Token Converter service is supposed to be a contract deployed on Ethereum mainnet once and forever. It's address will be provided in the text of this proposal as to avoid any potential trust issues and assure the developers that the service they are interacting with is exactly the one which drives the conversion process of existing tokens. All the ERC-223</a> tokens created by the Token Converter will be identical in a way that they all implement the same functions, which return the same values and there is no ambiguity there. This helps to avoid problems where a token deployed during the early stage of a token standard adoption may implement it improperly or there can be an ambiguity in the standard itself that would allow developers to implement tokens of one standard in different ways. For example it was a common case with ERC-20</a> where developers could implement custom logic of the transfer</code> function and mess the return values. The ERC-20</a> specification declares that a transfer</code> function MUST return a bool</code> value, however in practice we have three different types of ERC-20</a> tokens which are not compatible with each other: ERC-20</a> tokens that return true</code> on success and revert on an error.</li> ERC-20</a> tokens that return true</code> on success and false</code> on an error without reverting the transaction.</li> ERC-20</a> tokens that don't have return values and revert on an error.</li> </ol> Technically the third category of tokens is not compatible with ERC-20</a> standard. However, USDT token deployed on Ethereum mainnet at 0xdac17f958d2ee523a2206206994597c13d831ec7</code> address does not implement return values and it is one of the most used tokens and it is not an option to deny supporting USDT due to it's improper implementation of the standard. The Token Converter eliminates the issue where different development teams may implement the standard with slight modifications and result in a situation where we would have different versions of the same standard on the mainnet. At the same time the Converter enables the concurrent token support in other smart-contracts, such as decentralized exchanges. The Converter can guarantee that a pair of two tokens one of which is a wrapper for another is in fact the same token that can be converted from one standard to another at any time. This enables the creation of liquidity pools where two different tokens are dealt with as if they were one token. 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. The Token Converter system comprises two main components: Converter contract. </li> Wrapper contracts. Each original token can have exactly one wrapper of each standard. </li> </ul> Converter contract can deploy new ERC-223</a> wrapper contracts for any ERC-20</a> token that does not have a ERC-223</a> wrapper currently. There MUST be exactly one ERC-223</a> wrapper for each ERC-20</a> token. Converter contract MUST accept deposits of ERC-20</a> tokens and send ERC-223</a> tokens to the depositor at 1:1 ratio. Upon depositing 1234 units of ERC20 token_A</code> the depositor MUST receive exactly 1234 units of ERC223 token_A</code>. This is done by issuing new ERC-223</a> tokens at the moment of ERC-20</a> deposit. The original ERC-20</a> tokens MUST be frozen in the Converter contract and available for claiming back. Converter contract MUST accept deposits of ERC-223</a> tokens and send ERC-20</a> tokens to the depositor at 1:1 ratio. This is done by releasing the original ERC-20</a> tokens at the moment of ERC-223</a> deposit. The deposited ERC-223</a> tokens must be burned. Token Converter</h3> Conver contract methods</h4> getERC20WrapperFor</code></h5> function getERC20WrapperFor(address _token) public view returns (address)</code></pre> Returns the address of the ERC-20</a> wrapper for a given token address. Returns 0x0</code> if there is no ERC-20</a> version for the provided token address. There can be exactly one wrapper for any given ERC-223</a> token address created by the Token Converter contract. getERC223WrapperFor</code></h5> function getERC223WrapperFor(address _token) public view returns (address)</code></pre> Returns the address of the ERC-223</a> wrapper for a given token address. Returns 0x0</code> if there is no ERC-223</a> version for the provided token address. There can be exactly one ERC-223</a> wrapper for any given ERC-20</a> token address created by the Token Converter contract. getERC20OriginFor</code></h5> function getERC20OriginFor(address _erc223Token) public view returns (address)</code></pre> Returns the address of the original ERC-20</a> token for the provided ERC-223</a> wrapper. Returns 0x0</code> if the provided _erc223Token</code> is not an address of any ERC-223</a> wrapper created by the Token Converter contract. getERC223OriginFor</code></h5> function getERC223OriginFor(address _erc20Token) public view returns (address)</code></pre> Returns the address of the original ERC-223</a> token for the provided ERC-20</a> wrapper. Returns 0x0</code> if the provided _erc20Token</code> is not an address of any wrapper created by the Token Converter contract. predictWrapperAddress</code></h5> function predictWrapperAddress(address _token, bool _isERC20 // Is the provided _token a ERC-20 or not? // If it is set as ERC-20 then we will predict the address of a // ERC-223 wrapper for that token. // Otherwise we will predict ERC-20 wrapper address. ) view external returns (address)</code></pre> Wrapper contracts are deployed via CREATE2</code> opcode and it is possible to predict the address of a wrapper which is not yet deployed. The address of a wrapper contract depends on the bytecode therefore it is necessary to specify if the address of wrapper ERC-20</a> or wrapper ERC-223</a> must be predicted. Providing _token</code> address and _isERC20 = false</code> will result in ERC-20</a> wrapper address being predicted. Providing _token</code> address and _isERC20 = true</code> will result in ERC-223</a> wrapper address being predicted. createERC223Wrapper</code></h5> function createERC223Wrapper(address _erc20Token) public returns (address)</code></pre> Creates a new ERC-223</a> wrapper for a given _erc20Token</code> if it does not exist yet. Reverts the transaction if the wrapper already exist. Returns the address of the new wrapper token contract on success. Reverts if _erc223Token</code> is a wrapper created by the Converter. The deployed contract will be a standard ERC-223</a> token with approve</code> and transferFrom</code> functions implemented for backwards compatibility. All ERC-223</a> wrappers deployed by the Converter will have standard() pure returns (bytes32)</code> function implemented which returns 223</code>. This serves further token standard introspection as ERC-165</a> may not be reliable when dealing with identifying the internal logic implemented within transfer</code> function of a token. NOTE: This function does not verify the standard of _erc20Token</code> because there is no reliable method of introspection available which could guarantee that the provided token implements a particular standard. As the result it is possible to create a ERC-223</a> wrapper for an original ERC-223</a> token. createERC20Wrapper</code></h5> function createERC20Wrapper(address _erc223Token) public returns (address)</code></pre> Creates a new ERC-20</a> wrapper for a given _erc223Token</code> if it does not exist yet. Reverts the transaction if the wrapper already exist. Returns the address of the new wrapper token contract on success. Reverts if _erc223Token</code> is a wrapper created by the Converter. NOTE: This function does not verify the standard of _erc223Token</code> because there is no reliable method of introspection available which could guarantee that the provided token implements a particular standard. As the result it is possible to create a ERC-20</a> wrapper for an original ERC-20</a> token. wrapERC20toERC223</code></h5> function wrapERC20toERC223(address _ERC20token, uint256 _amount) public returns (bool)</code></pre> Withdraws _amount</code> of ERC-20</a> tokens from the transaction sender with transferFrom</code> function. Delivers the _amount</code> of ERC-223</a> wrapper tokens to the sender of the transaction. Stores the original tokens at the balance of the Token Converter contract for future claims. Returns true</code> on success. The Token Converter must keep record of the amount of ERC-20</a> tokens that were deposited with wrapERC20toERC223</code> function because it is possible to deposit ERC-20</a> tokens to any contract by directly sending them with transfer</code> function. If there is no ERC-223</a> wrapper for the _ERC20token</code> then creates it by calling a createERC223Wrapper(_erc20toke)</code> function. There is no special function to unwrap ERC-223</a> wrappers to ERC-20</a> origin as this logic is implemented in the tokenReceived</code> function of the Converter. unwrapERC20toERC223</code></h5> function unwrapERC20toERC223(address _ERC20token, uint256 _amount) public returns (bool)</code></pre> Withdraws _amount</code> of ERC-20</a> tokens from the transaction sender with transferFrom</code> function. Delivers the _amount</code> of ERC-223</a> wrapper tokens to the sender of the transaction. Stores the original tokens at the balance of the Token Converter contract for future claims. Returns true</code> on success. The Token Converter must keep record of the amount of ERC-20</a> tokens that were deposited with wrapERC20toERC223</code> function because it is possible to deposit ERC-20</a> tokens to any contract by directly sending them with transfer</code> function. If there is no ERC-223</a> wrapper for the _ERC20token</code> then creates it by calling a createERC223Wrapper(_erc20toke)</code> function. convertERC20</code></h5> function convertERC20(address _token, uint256 _amount) public returns (bool)</code></pre> Automatically determines if the provided ERC-20</a> token is a wrapper or not. If it is a wrapper then executes unwrapERC20toERC223</code> function. If the provided token is an origin then executes wrapERC20toERC223</code> function. This function is implemented to significantly simplify the workflow of services that integrate both versions of one token in the same contract and need to automatically convert tokens through the Converter. isWrapper</code></h5> function isWrapper(address _token) public view returns (bool)</code></pre> Returns true</code> if the provided _token</code> address is an address of a wrapper created by the Converter. NOTE: This function does not identify the standard of a _token</code>. There can be exactly one origin for any wrapper created by the Converter. However an original token can have two wrappers, one of each standard. tokenReceived</code></h5> function tokenReceived(address _from, uint _value, bytes memory _data) public override returns (bytes4)</code></pre> This is a standard ERC-223</a> transaction handler function and it is called by the ERC-223</a> token contract when _from</code> is sending _value</code> of ERC-223</a> tokens to address(this)</code> address. In the scope of this function msg.sender</code> is the address of the ERC-223</a> token contract and _from</code> is the sender of the token transfer. Automatically determines If msg.sender</code> is an address of ERC-223</a> wrapper created by the Token Converter then _value</code> of ERC-20</a> original token must be sent to the _from</code> address. If msg.sender</code> is not an address of any ERC-223</a> wrapper known to the Token Converter then it is considered a ERC-223</a> origin and _value</code> amount of ERC-20</a> wrapper tokens must be sent to the _from</code> address. If the ERC-20</a> wrapper for the msg.sender</code> token does not exist then create it first. Returns 0x8943ec02</code>. extractStuckERC20</code></h5> function extractStuckERC20(address _token)</code></pre> This function allows to extract the ERC-20</a> tokens that were directly deposited to the contract with transfer</code> function to prevent users who may send tokens by mistake from permanently losing their tokens. Since the Token Converter calculates the amount of tokens that were deposited legitimately with convertERC20toERC223</code> function it is always possible to calculate the amount of "accidentally deposited tokens" by subtracting the recorded amount from the returned value of the balanceOf( address(this) )</code> function called on the ERC-20</a> token contract. Converting ERC-20</a> tokens to ERC-223</a></h3> In order to convert ERC-20</a> tokens to ERC-223</a> the token holder should: Call the approve</code> function of the ERC-20</a> token and allow Token Converter to withdraw tokens from the token holders address via transferFrom</code> function.</li> Wait for the transaction with approve</code> to be submitted to the blockchain.</li> Call the convertERC20toERC223</code> function of the Token Converter contract.</li> </ol> Converting ERC-223</a> wrapper tokens back to ERC-20</a></h3> In order to convert ERC-20</a> tokens to ERC-223</a> the token holder should: Send ERC-223</a> tokens to the address of the Token Converter contract via transfer</code> function of the ERC-223</a> token contract.</li> </ol> Rationale</h2> Support of ERC-223</a> original tokens</h3> Two methods of implementing a Token Converter service were considered: (1) a converter that can only create ERC-223</a> versions of the existing ERC-20</a> tokens, and (2) a converter that can create both versions (ERC-20</a> and ERC-223</a>) of any original token. The first approach would encourage developers to always deploy an original token as ERC-20</a> and then create it's ERC-223</a> version in the converter. If it would happen that some developers may consider ERC-223</a> as their original standard then they would be left with the problem of creating their custom ERC-20</a> version of the token. In addition, if any third party contracts like liquidity pools are using the proposed Token Converter to ensure that a token can be listed on a DEX with two versions and both can be combined within one pool - then such contract would not be able to recognize any original ERC-223</a> token and it's ERC-20</a> version as a valid pair of contracts that represent one token available in two standards. For that reason it was decided to go with the second approach where the Converter can create ERC-20</a> wrappers for original ERC-223</a> tokens. Support of approve</code> & transferFrom</code> functions in the ERC-223</a> wrapper tokens</h3> This functions are superfluous for a ERC-223</a> token since the transfer</code> function can be used to deposit tokens of this standard to contracts. The current ecosystem is built for ERC-20</a> tokens however and there are plenty of multisig contracts that rely on accepting tokens deposited without any callback with an assumption that it is not necessary for a multisig to count the amount of tokens it stores. There can be any other contracts and scenarios where it would be necessary to deposit a token to a contract which is relying on an assumption that tokens are deposited without invoking a callback in the recipient. As the result we can expect that any original deployed ERC-223</a> tokens will support this functions, as token developers strive for backward compatibility with the existing ecosystem. In order to make tokens deployed by the converter a reference implementation for developers that can be used without any modifications it was decided to support this functions in the ERC-223</a> wrapper contracts. transferFrom</code> function does not support error handling and this needs to be taken into account. It is possible to deposit tokens to a contract which is not designed to receive them by approving X tokens to your own address and then calling a transferFrom(self, contract, X)</code>. The tokens will be deposited regardless of whether the recipient contract is designed to hold/receive tokens or not. The tokens may get permanently stuck if the recipient contract did not implement the extraction functions. The approve</code> & transferFrom</code> function is not the default method of token transferring however and it is not directly used by any wallets and any other software that manages tokens. The transfer</code> function (which is safe) is used instead. The transferFrom</code> function is supposed to be invoked by a contract to pull tokens from the approver. As the result, the approve</code> & transferFrom</code> transferring method must be avoided with ERC-223</a> tokens whenever possible. Modified transfer events of the ERC-223</a> token</h3> The pure ERC-223</a> token implementation has the following event emitted on a token transfer: event Transfer(address indexed _from, address indexed _to, uint256 _value, bytes _data)</code>. This events are different from ones emitted by ERC-20</a> tokens and may not be properly recognized by existing blockchain explorers, wallets and other services that browse token transfers history. It was considered that events are not an important part of the standard as these do not affect the logic of the token, it's workflow and it's security. When developing the Converter it was decided to prioritize compatibility with existing ecosystem. standard()</code> function usage for the introspection</h3> The main existing method of introspection is currently ERC-165</a> which inspects the signatures of functions implemented in a contract. It is not possible to differentiate an ERC-20</a> token from an ERC-223</a> token by just browsing functions that they implement without digging their internal logic. Here is a token and it is not possible to identify if it should be dealt with as ERC-20</a> or ERC-223</a> because it depends on the actual implemenation of it's transfer</code> function logic. abstract contract Token { function name() external virtual returns (string memory); function symbol() external virtual returns (string memory); function decimals() external virtual returns (uint8); function transfer(address, uint256) external virtual returns (bool); function approve(address, uint256) external virtual returns (bool); function transferFrom(address, address, uint256) external virtual returns (bool); }</code></pre> In case of this implementation the token will behave as ERC-20</a>: function transfer(address _to, uint256 _amount) external virtual returns (bool) { balances[msg.sender] -= _amount; balances[_to] += _amount; } }</code></pre> In case of this implementation the token will behave as ERC-223</a>: function transfer(address _to, uint256 _amount) external virtual returns (bool) { balances[msg.sender] -= _amount; balances[_to] += _amount; if(_to.isContract()) { IERC223Recipient(_to).tokenReceived(msg.sender, _amount, hex"000000"); } } }</code></pre> Also, there are plenty of tokens that do not implement ERC-165</a> introspection at all. As the result it was decided to implement a special standard() returns (uint32)</code> function in all ERC-223</a> wrappers created by the Converter and assume that original ERC-223</a> tokens may explicityly declare themselves as ERC-223</a> by implementing the same function too. It is assumed that if a token does not implement this function then it is ERC-20</a>. This method of token standard introspection is more precise than ERC-165</a>. Backwards Compatibility</h2> This proposal is supposed to eliminate the backwards compatibility concerns for different token standards making them interchangeable and interoperable. This service is the first of its kind and therefore does not have any backwards compatibility issues as it does not have any predecessors. Reference Implementation</h2> pragma solidity =0.8.19; library Address { function isContract(address account) internal view returns (bool) { // This method relies on extcodesize, which returns 0 for contracts in // construction, since the code is only stored at the end of the // constructor execution. uint256 size; // solhint-disable-next-line no-inline-assembly assembly { size := extcodesize(account) } return size > 0; } } interface IERC20 { function totalSupply() external view returns (uint256); function balanceOf(address account) external view returns (uint256); function transfer(address recipient, uint256 amount) external returns (bool); function allowance(address owner, address spender) external view returns (uint256); function approve(address spender, uint256 amount) external returns (bool); function transferFrom(address sender, address recipient, uint256 amount) external returns (bool); event Transfer(address indexed from, address indexed to, uint256 value); event Approval(address indexed owner, address indexed spender, uint256 value); } interface IERC20Metadata is IERC20 { /// @return The name of the token function name() external view returns (string memory); /// @return The symbol of the token function symbol() external view returns (string memory); /// @return The number of decimal places the token has function decimals() external view returns (uint8); } abstract contract IERC223Recipient { function tokenReceived(address _from, uint _value, bytes memory _data) public virtual returns (bytes4) { return 0x8943ec02; } } abstract contract ERC165 { / * bytes4(keccak256('supportsInterface(bytes4)')) == 0x01ffc9a7 */ bytes4 private constant _INTERFACE_ID_ERC165 = 0x01ffc9a7; mapping(bytes4 => bool) private _supportedInterfaces; constructor () { // Derived contracts need only register support for their own interfaces, // we register support for ERC165 itself here _registerInterface(_INTERFACE_ID_ERC165); } function supportsInterface(bytes4 interfaceId) public view virtual returns (bool) { return _supportedInterfaces[interfaceId]; } function _registerInterface(bytes4 interfaceId) internal virtual { require(interfaceId != 0xffffffff, "ERC165: invalid interface id"); _supportedInterfaces[interfaceId] = true; } } abstract contract IERC223 { function name() public view virtual returns (string memory); function symbol() public view virtual returns (string memory); function decimals() public view virtual returns (uint8); function totalSupply() public view virtual returns (uint256); function balanceOf(address who) public virtual view returns (uint); function transfer(address to, uint value) public virtual returns (bool success); function transfer(address to, uint value, bytes calldata data) public payable virtual returns (bool success); event Transfer(address indexed from, address indexed to, uint value, bytes data); } interface standardERC20 { event Transfer(address indexed from, address indexed to, uint256 value); event Approval(address indexed owner, address indexed spender, uint256 value); function totalSupply() external view returns (uint256); function balanceOf(address account) external view returns (uint256); function transfer(address to, uint256 value) external returns (bool); function allowance(address owner, address spender) external view returns (uint256); function approve(address spender, uint256 value) external returns (bool); function transferFrom(address from, address to, uint256 value) external returns (bool); } /** * @dev Interface of the ERC20 standard. */ interface IERC223WrapperToken { function name() external view returns (string memory); function symbol() external view returns (string memory); function decimals() external view returns (uint8); function standard() external view returns (string memory); function origin() external view returns (address); function totalSupply() external view returns (uint256); function balanceOf(address account) external view returns (uint256); function transfer(address to, uint256 value) external payable returns (bool); function transfer(address to, uint256 value, bytes calldata data) external payable returns (bool); function allowance(address owner, address spender) external view returns (uint256); function approve(address spender, uint256 value) external returns (bool); function transferFrom(address from, address to, uint256 value) external returns (bool); function mint(address _recipient, uint256 _quantity) external; function burn(address _recipient, uint256 _quantity) external; } interface IERC20WrapperToken { function name() external view returns (string memory); function symbol() external view returns (string memory); function decimals() external view returns (uint8); function standard() external view returns (string memory); function origin() external view returns (address); function totalSupply() external view returns (uint256); function balanceOf(address account) external view returns (uint256); function transfer(address to, uint256 value) external returns (bool); function allowance(address owner, address spender) external view returns (uint256); function approve(address spender, uint256 value) external returns (bool); function transferFrom(address from, address to, uint256 value) external returns (bool); function mint(address _recipient, uint256 _quantity) external; function burn(address _recipient, uint256 _quantity) external; } contract ERC20Rescue { // ERC20 tokens can get stuck on a contracts balance due to lack of error handling. // // The author of the ERC7417 can extract ERC20 tokens if they are mistakenly sent // to the wrapper-contracts balance. // Contact dexaran@ethereumclassic.org address public extractor = 0x01000B5fE61411C466b70631d7fF070187179Bbf; function safeTransfer(address token, address to, uint value) internal { // bytes4(keccak256(bytes('transfer(address,uint256)'))); (bool success, bytes memory data) = token.call(abi.encodeWithSelector(0xa9059cbb, to, value)); require(success && (data.length == 0 || abi.decode(data, (bool))), 'TransferHelper: TRANSFER_FAILED'); } function rescueERC20(address _token, uint256 _amount) external { safeTransfer(_token, extractor, _amount); } } contract ERC223WrapperToken is IERC223, ERC165, ERC20Rescue { address public creator = msg.sender; address private wrapper_for; mapping(address account => mapping(address spender => uint256)) private allowances; event Transfer(address indexed from, address indexed to, uint256 amount); event TransferData(bytes data); event Approval(address indexed owner, address indexed spender, uint256 amount); function set(address _wrapper_for) external { require(msg.sender == creator); wrapper_for = _wrapper_for; } uint256 private _totalSupply; mapping(address => uint256) private balances; // List of user balances. function totalSupply() public view override returns (uint256) { return _totalSupply; } function balanceOf(address _owner) public view override returns (uint256) { return balances[_owner]; } /** * @dev The ERC165 introspection function. */ function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) { return interfaceId == type(IERC20).interfaceId || interfaceId == type(standardERC20).interfaceId || interfaceId == type(IERC223WrapperToken).interfaceId || interfaceId == type(IERC223).interfaceId || super.supportsInterface(interfaceId); } /** * @dev Standard ERC223 transfer function. * Calls _to if it is a contract. Does not transfer tokens to contracts * which do not explicitly declare the tokenReceived function. * @param _to - transfer recipient. Can be contract or EOA. * @param _value - the quantity of tokens to transfer. * @param _data - metadata to send alongside the transaction. Can be used to encode subsequent calls in the recipient. */ function transfer(address _to, uint _value, bytes calldata _data) public payable override returns (bool success) { balances[msg.sender] = balances[msg.sender] - _value; balances[_to] = balances[_to] + _value; if (msg.value > 0) { (bool sent, bytes memory data) = _to.call{value: msg.value}(""); require(sent); } if(Address.isContract(_to)) { IERC223Recipient(_to).tokenReceived(msg.sender, _value, _data); } emit Transfer(msg.sender, _to, _value, _data); emit Transfer(msg.sender, _to, _value); // Old ERC20 compatible event. Added for backwards compatibility reasons. return true; } /** * @dev Standard ERC223 transfer function without _data parameter. It is supported for * backwards compatibility with ERC20 services. * Calls _to if it is a contract. Does not transfer tokens to contracts * which do not explicitly declare the tokenReceived function. * @param _to - transfer recipient. Can be contract or EOA. * @param _value - the quantity of tokens to transfer. */ function transfer(address _to, uint _value) public override returns (bool success) { bytes memory _empty = hex"00000000"; balances[msg.sender] = balances[msg.sender] - _value; balances[_to] = balances[_to] + _value; if(Address.isContract(_to)) { IERC223Recipient(_to).tokenReceived(msg.sender, _value, _empty); } emit Transfer(msg.sender, _to, _value, _empty); emit Transfer(msg.sender, _to, _value); // Old ERC20 compatible event. Added for backwards compatibility reasons. return true; } function name() public view override returns (string memory) { return IERC20Metadata(wrapper_for).name(); } function symbol() public view override returns (string memory) { return string.concat(IERC20Metadata(wrapper_for).symbol(), "223"); } function decimals() public view override returns (uint8) { return IERC20Metadata(wrapper_for).decimals(); } function standard() public pure returns (uint32) { return 223; } function origin() public view returns (address) { return wrapper_for; } /** * @dev Minting function which will only be called by the converter contract. * @param _recipient - the address which will receive tokens. * @param _quantity - the number of tokens to create. */ function mint(address _recipient, uint256 _quantity) external { require(msg.sender == creator, "Wrapper Token: Only the creator contract can mint wrapper tokens."); balances[_recipient] += _quantity; _totalSupply += _quantity; } /** * @dev Burning function which will only be called by the converter contract. * @param _quantity - the number of tokens to destroy. TokenConverter can only destroy tokens on it's own address. * Only the token converter is allowed to burn wrapper-tokens. / function burn(uint256 _quantity) external { require(msg.sender == creator, "Wrapper Token: Only the creator contract can destroy wrapper tokens."); balances[msg.sender] -= _quantity; _totalSupply -= _quantity; } // ERC20 functions for backwards compatibility. function allowance(address owner, address spender) public view virtual returns (uint256) { return allowances[owner][spender]; } function approve(address _spender, uint _value) public returns (bool) { require(_spender != address(0), "ERC223: Spender error."); allowances[msg.sender][_spender] = _value; emit Approval(msg.sender, _spender, _value); return true; } function transferFrom(address _from, address _to, uint _value) public returns (bool) { require(allowances[_from][msg.sender] >= _value, "ERC223: Insufficient allowance."); balances[_from] -= _value; allowances[_from][msg.sender] -= _value; balances[_to] += _value; emit Transfer(_from, _to, _value); return true; } } contract ERC20WrapperToken is IERC20, ERC165, ERC20Rescue { address public creator = msg.sender; address public wrapper_for; mapping(address account => mapping(address spender => uint256)) private allowances; function set(address _wrapper_for) external { require(msg.sender == creator); wrapper_for = _wrapper_for; } uint256 private _totalSupply; mapping(address => uint256) private balances; // List of user balances. function balanceOf(address _owner) public view override returns (uint256) { return balances[_owner]; } function name() public view returns (string memory) { return IERC20Metadata(wrapper_for).name(); } function symbol() public view returns (string memory) { return string.concat(IERC223(wrapper_for).symbol(), "20"); } function decimals() public view returns (uint8) { return IERC20Metadata(wrapper_for).decimals(); } function totalSupply() public view override returns (uint256) { return _totalSupply; } function origin() public view returns (address) { return wrapper_for; } function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) { return interfaceId == type(IERC20).interfaceId || interfaceId == type(IERC20WrapperToken).interfaceId || super.supportsInterface(interfaceId); } function transfer(address _to, uint _value) public override returns (bool success) { balances[msg.sender] = balances[msg.sender] - _value; balances[_to] = balances[_to] + _value; emit Transfer(msg.sender, _to, _value); return true; } function mint(address _recipient, uint256 _quantity) external { require(msg.sender == creator, "Wrapper Token: Only the creator contract can mint wrapper tokens."); balances[_recipient] += _quantity; _totalSupply += _quantity; } function burn(address _from, uint256 _quantity) external { require(msg.sender == creator, "Wrapper Token: Only the creator contract can destroy wrapper tokens."); balances[_from] -= _quantity; _totalSupply -= _quantity; } function allowance(address owner, address spender) public view virtual returns (uint256) { return allowances[owner][spender]; } function approve(address _spender, uint _value) public returns (bool) { // Safety checks. require(_spender != address(0), "ERC20: Spender error."); allowances[msg.sender][_spender] = _value; emit Approval(msg.sender, _spender, _value); return true; } function transferFrom(address _from, address _to, uint _value) public returns (bool) { require(allowances[_from][msg.sender] >= _value, "ERC20: Insufficient allowance."); balances[_from] -= _value; allowances[_from][msg.sender] -= _value; balances[_to] += _value; emit Transfer(_from, _to, _value); return true; } } contract TokenStandardConverter is IERC223Recipient { event ERC223WrapperCreated(address indexed _token, address indexed _ERC223Wrapper); event ERC20WrapperCreated(address indexed _token, address indexed _ERC20Wrapper); mapping (address => ERC223WrapperToken) public erc223Wrappers; // A list of token wrappers. First one is ERC20 origin, second one is ERC223 version. mapping (address => ERC20WrapperToken) public erc20Wrappers; mapping (address => address) public erc223Origins; mapping (address => address) public erc20Origins; mapping (address => uint256) public erc20Supply; // Token => how much was deposited. function getERC20WrapperFor(address _token) public view returns (address) { return address(erc20Wrappers[_token]); } function getERC223WrapperFor(address _token) public view returns (address) { return address(erc223Wrappers[_token]); } function getERC20OriginFor(address _token) public view returns (address) { return (address(erc20Origins[_token])); } function getERC223OriginFor(address _token) public view returns (address) { return (address(erc223Origins[_token])); } function predictWrapperAddress(address _token, bool _isERC20 // Is the provided _token a ERC20 or not? // If it is set as ERC20 then we will predict the address of a // ERC223 wrapper for that token. // Otherwise we will predict ERC20 wrapper address. ) view external returns (address) { bytes memory _bytecode; if(_isERC20) { _bytecode = type(ERC223WrapperToken).creationCode; } else { _bytecode = type(ERC20WrapperToken).creationCode; } bytes32 hash = keccak256( abi.encodePacked( bytes1(0xff), address(this), keccak256(abi.encode(_token)), keccak256(_bytecode) ) ); return address(uint160(uint(hash))); } function tokenReceived(address _from, uint _value, bytes memory / _data */) public override returns (bytes4) { require(erc223Origins[msg.sender] == address(0), "Error: creating wrapper for a wrapper token."); // There are two possible cases: // 1. A user deposited ERC223 origin token to convert it to ERC20 wrapper // 2. A user deposited ERC223 wrapper token to unwrap it to ERC20 origin. if(erc20Origins[msg.sender] != address(0)) { // Origin for deposited token exists. // Unwrap ERC-223 wrapper. erc20Supply[erc20Origins[msg.sender]] -= _value; safeTransfer(erc20Origins[msg.sender], _from, _value); ERC223WrapperToken(msg.sender).burn(_value); return this.tokenReceived.selector; } // Otherwise origin for the sender token doesn't exist // There are two possible cases: // 1. ERC20 wrapper for the deposited token exists // 2. ERC20 wrapper for the deposited token doesn't exist and must be created. else if(address(erc20Wrappers[msg.sender]) == address(0)) { // Create ERC-20 wrapper if it doesn't exist. createERC20Wrapper(msg.sender); } // Mint ERC-20 wrapper tokens for the deposited ERC-223 token // if the ERC-20 wrapper didn't exist then it was just created in the above statement. erc20Wrappers[msg.sender].mint(_from, _value); return this.tokenReceived.selector; } function createERC223Wrapper(address _token) public returns (address) { require(address(erc223Wrappers[_token]) == address(0), "ERROR: Wrapper exists"); require(!isWrapper(_token), "Error: Creating wrapper for a wrapper token"); ERC223WrapperToken _newERC223Wrapper = new ERC223WrapperToken{salt: keccak256(abi.encode(_token))}(); _newERC223Wrapper.set(_token); erc223Wrappers[_token] = _newERC223Wrapper; erc20Origins[address(_newERC223Wrapper)] = _token; emit ERC223WrapperCreated(_token, address(_newERC223Wrapper)); return address(_newERC223Wrapper); } function createERC20Wrapper(address _token) public returns (address) { require(address(erc20Wrappers[_token]) == address(0), "ERROR: Wrapper already exists."); require(!isWrapper(_token), "Error: Creating wrapper for a wrapper token"); ERC20WrapperToken _newERC20Wrapper = new ERC20WrapperToken{salt: keccak256(abi.encode(_token))}(); _newERC20Wrapper.set(_token); erc20Wrappers[_token] = _newERC20Wrapper; erc223Origins[address(_newERC20Wrapper)] = _token; emit ERC20WrapperCreated(_token, address(_newERC20Wrapper)); return address(_newERC20Wrapper); } function wrapERC20toERC223(address _ERC20token, uint256 _amount) public returns (bool) { // If there is no active wrapper for a token that user wants to wrap // then create it. if(address(erc223Wrappers[_ERC20token]) == address(0)) { createERC223Wrapper(_ERC20token); } uint256 _converterBalance = IERC20(_ERC20token).balanceOf(address(this)); // Safety variable. safeTransferFrom(_ERC20token, msg.sender, address(this), _amount); _amount = IERC20(_ERC20token).balanceOf(address(this)) - _converterBalance; erc20Supply[_ERC20token] += _amount; erc223Wrappers[_ERC20token].mint(msg.sender, _amount); return true; } function unwrapERC20toERC223(address _ERC20token, uint256 _amount) public returns (bool) { require(IERC20(_ERC20token).balanceOf(msg.sender) >= _amount, "Error: Insufficient balance."); require(erc223Origins[_ERC20token] != address(0), "Error: provided token is not a ERC-20 wrapper."); ERC20WrapperToken(_ERC20token).burn(msg.sender, _amount); safeTransfer(erc223Origins[_ERC20token], msg.sender, _amount); return true; } function convertERC20(address _token, uint256 _amount) public returns (bool) { if(isWrapper(_token)) return unwrapERC20toERC223(_token, _amount); else return wrapERC20toERC223(_token, _amount); } function isWrapper(address _token) public view returns (bool) { return erc20Origins[_token] != address(0) || erc223Origins[_token] != address(0); } function extractStuckERC20(address _token) external { require(msg.sender == address(0x01000B5fE61411C466b70631d7fF070187179Bbf)); safeTransfer(_token, address(0x01000B5fE61411C466b70631d7fF070187179Bbf), IERC20(_token).balanceOf(address(this)) - erc20Supply[_token]); } function safeTransfer(address token, address to, uint value) internal { // bytes4(keccak256(bytes('transfer(address,uint256)'))); (bool success, bytes memory data) = token.call(abi.encodeWithSelector(0xa9059cbb, to, value)); require(success && (data.length == 0 || abi.decode(data, (bool))), 'TransferHelper: TRANSFER_FAILED'); } function safeTransferFrom(address token, address from, address to, uint value) internal { // bytes4(keccak256(bytes('transferFrom(address,address,uint256)'))); (bool success, bytes memory data) = token.call(abi.encodeWithSelector(0x23b872dd, from, to, value)); require(success && (data.length == 0 || abi.decode(data, (bool))), 'TransferHelper: TRANSFER_FROM_FAILED'); } }</code></pre>Security Considerations</h2> While it is possible to implement a service that converts any token standard to any other standard - it is better to keep different standard convertors separate from one another as different standards may contain specific logic and therefore require different conversion approach. This proposal focuses on ERC-20</a> and ERC-223</a> upgradeability.</li> ERC-20</a> tokens can be deposited to any contract directly with transfer</code> function. This may result in a permanent loss of tokens because it is not possible to recognize this transaction on the recipients side. Therefore wrapper-ERC-20 tokens are prone to this problem as they are compatible with the ERC-20</a> standard. rescueERC20</code> function is implemented to address this problem.</li> Token Converter relies on ERC-20</a> approve</code> & transferFrom</code> method of depositing assets. Any related issues must be taken into account. approve</code> and transferFrom</code> are two separate transactions so it is required to make sure approval</code> was successful before relying on transferFrom</code>.</li> This is a common practice for UI services to prompt a user to issue unlimited approval</code> on any contract that may withdraw tokens from the user. This puts users funds at risk and therefore is not recommended.</li> There is no reliable token standard introspection method available that could guarantee that a token implements a particular token standard. It is possible to artificially construct a token that will pretend it is a ERC-20</a> token that implements approve & transferFrom</code> but at the same time implements ERC-223</a> logic of transferring via transfer</code> function. It can be possible to create a ERC-223</a> wrapper for this ERC-20</a>-ERC-223</a> hybrid implementation in the Token Converter. This doesn't pose any threat for the workflow of the Token Converter itself but it must be taken into account that if a token has ERC-223</a> wrapper in the Token Converter it does not automatically mean the origin is fully compatible with the ERC-20</a> standard and methods of introspection must be used to determine the origins compatibility with any existing standard.</li> Token Converter does not verify the standard of a provided token when it is asked to create a wrapper for it due to the lack of reliable standard introspection method. It is possible to call createERC20Wrapper</code> function and provide an address of an existing ERC-20</a> token. The Token Converter will successfully create a ERC-20</a> wrapper for that ERC-20</a> original token. It is also possible to create a ERC-223</a> wrapper for that exact original ERC-20</a> token. This doesn't pose any threat to the workflow of the Converter but it must be taken into account that any token regardless of it's original standard may have up to two wrappers created by the Converter, one for each standard. Any wrapper token must have exactly one origin. It is not possible to create a wrapper for a wrapper.</li> The Token Converter only holds the original tokens that were deposited during the conversion process and it assumes that tokens do not decay over time and the token balance of the Converter does not decrease on its own. If some token implements burning logic or decaying supply and it may impact the balance of the Converter then the Converter must not be used to deploy an alternative version of that token as it will not be able to guarantee that there is enough tokens for the conversion at any time.</li> </ol> Copyright</h2> Copyright and related rights waived via CC0</a>. ⚡ Flash Loans ⚡ 2023-07-25T00:00:00+00:00 Abstract</h2> A flash loan is a loan between lender and borrower smart contracts that must be repaid, plus an optional fee, before the end of the transaction. This ERC specifies interfaces for lenders to accept flash loan requests, and for borrowers to take temporary control of the transaction within the lender execution. The process for the safe execution of flash loans is also specified. Motivation</h2> The current state of the flash loan ecosystem is fragmented and lacks standardization, leading to several challenges for both lenders and borrowers. The absence of a common interface results in increased integration efforts, as each flash loan provider implements its own unique approach. This lack of standardization is expected to become more problematic as the ecosystem grows, requiring more resources to maintain compatibility. A comprehensive analysis of the existing flash loan protocols reveals significant differences in their implementations, including: Inconsistent syntax for initiating flash loans across different platforms.</li> Variations in the relationship between the loan receiver and the callback receiver, with some protocols allowing different addresses for each role while others do not.</li> Divergent repayment mechanisms, with some lenders pulling the principal and fee from the loan receiver and others requiring the loan receiver to manually return the funds.</li> Disparities in the treatment of flash minting, where some lenders allow the creation of any amount of their native asset without charging a fee, effectively permitting flash loans bounded by computational constraints rather than asset ownership limitations.</li> </ul> To address these inconsistencies and promote a more efficient and accessible flash loan ecosystem, this ERC specifies a standardized interface that encompasses the maximum flexibility required by both lenders and borrowers. By consolidating the various approaches into a unified standard, this proposal aims to streamline the integration process, enabling borrowers to seamlessly switch between flash lenders without the need for code modifications. 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. Under this standard a flash loan is a loan of an amount</code> of an ERC-20</a> asset</code> from a lender</code>. This loan can remain open for the span of a single flash</code> call in the lender</code>. This amount</code> plus a fee</code> defined by the lender</code> in the same asset</code> must be repaid before the end of flash</code> call at a repayment receiver address defined by the lender</code>. The flash</code> function is called by the initiator</code>, who defines the loan receiver, the callback receiver, the callback function, the asset</code> and the amount</code>. When the initiator</code> calls flash</code> in a lender</code>. The lender</code> will then transfer the amount</code> of asset</code> to the loan receiver. The lender</code>, after transferring amount</code> of asset</code> to the loan receiver, will execute the callback function on the callback receiver. The lender</code> will include in this callback function call a number of parameters related to the loan as defined in this standard. The amount</code> and fee</code> need to be transferred to a repayment receiver</code> before the end of the flash</code> call. The fee</code> can be set to zero asset</code>. The callback function can return any arbitrary data which will be received by the initiator</code> as the return value of the flash</code> call. The lender decides which assets</code> to support. The lender can decide to support all possible assets. Lender Specification</h3> A lender</code> MUST implement the ERC-7399</a> interface. // SPDX-License-Identifier: CC0-1.0 pragma solidity >=0.6.0 <0.9.0; import { IERC20 } from "./IERC20.sol"; interface IERC7399 { /// @dev The amount of currency available to be lent. /// @param asset The loan currency. /// @return The amount of `asset` that can be borrowed. function maxFlashLoan( address asset ) external view returns (uint256); /// @dev The fee to be charged for a given loan. Returns type(uint256).max if the loan is not possible. /// @param asset The loan currency. /// @param amount The amount of assets lent. /// @return The amount of `asset` to be charged for the loan, on top of the returned principal. function flashFee( IERC20 asset, uint256 amount ) external view returns (uint256); /// @dev Initiate a flash loan. /// @param loanReceiver The address receiving the flash loan /// @param asset The asset to be loaned /// @param amount The amount to loaned /// @param data The ABI encoded user data /// @param callback The address and signature of the callback function /// @return result ABI encoded result of the callback function flash( address loanReceiver, ERC20 asset, uint256 amount, bytes calldata data, /// @dev callback. This is a combination of the callback receiver address, and the signature of callback /// function. It is encoded packed as 20 bytes + 4 bytes. /// @dev the return of the callback function is not encoded in the parameter, but must be `returns (bytes /// memory)` for compliance with the standard. /// @param initiator The address that called this function /// @param paymentReceiver The address that needs to receive the amount plus fee at the end of the callback /// @param asset The asset to be loaned /// @param amount The amount to loaned /// @param fee The fee to be paid /// @param data The ABI encoded data to be passed to the callback /// @return result ABI encoded result of the callback function(address, address, IERC20, uint256, uint256, bytes memory) external returns (bytes memory) callback ) external returns (bytes memory); } </code></pre> The maxFlashLoan</code> function MUST return the maximum available loan for asset</code>. The maxFlashLoan</code> function MUST NOT revert. If no flash loans for the specified asset</code> are possible, the value returned MUST be zero. The flashFee</code> function MUST return the fee charged for a loan of amount</code> asset</code>. The flashFee</code> function MUST NOT revert. If a flash loan for the specified asset</code> and amount</code> is not possible, the value returned MUST be type(uint256).max</code>. The flash</code> function MUST execute the callback passed on as an argument. bytes memory result = callback(msg.sender, address(this), asset, amount, _fee, data);</code></pre> The flash</code> function MUST transfer amount</code> of asset</code> to loan receiver before executing the callback. The flash</code> function MUST include msg.sender</code> as the initiator</code> in the callback. The flash</code> function MUST NOT modify the asset</code>, amount</code> and data</code> parameter received, and MUST pass them on to the callback. The flash</code> function MUST include a fee</code> argument in the callback with the fee to pay for the loan on top of the principal, ensuring that fee == flashFee(asset, amount)</code>. Before the end of the callback, the asset</code> balance of payment receiver</code> MUST have increased by amount + fee</code> from the amount at the beginning of the callback, or revert if this is not true. The return of the flash</code> function MUST be the same as the return from the callback. Receiver Specification</h3> A callback receiver of flash loans MUST implement one or more external functions with the following arguments and return value: /// @dev This function can have any name and be overloaded. /// @param initiator The address that called this function /// @param paymentReceiver The address that needs to receive the amount plus fee at the end of the callback /// @param asset The asset to be loaned /// @param amount The amount to loaned /// @param fee The fee to be paid /// @param data The ABI encoded data to be passed to the callback /// @return result ABI encoded result of the callback function(address, address, IERC20, uint256, uint256, bytes memory) external returns (bytes memory) callback;</code></pre>Rationale</h2> The interfaces described in this ERC have been chosen as to cover the known flash lending use cases, while allowing for safe and gas efficient implementations. maxFlashLoan</code> and flashFee</code> return numerical values on impossible loans to allow sorting lenders without having to deal with reverts. maxFlashLoan</code> returns a value that is consistent with an impossible loan when the lender</code> is not able to serve the loan. flashFee</code> returns a value that is consistent with an impossible loan when the lender</code> is not able to serve the loan. flash</code> has been chosen as a function name as a verb which is descriptive enough, unlikely to clash with other functions in the lender</code>, and including both the use cases in which the assets lent are held or minted by the lender</code>. Existing flash lenders all provide flash loans of several asset types from the same contract. Providing a asset</code> parameter in both the flash</code> and callback functions matches closely the observed functionality. A bytes calldata data</code> parameter is included for the initiator</code> to pass arbitrary information to the receiver</code>. The receiver</code> can pass arbitrary information back to the initiator</code> using the bytes memory</code> return value. A initiator</code> will often be required in the callback function, which the lender</code> knows as msg.sender</code>. An alternative implementation which would embed the initiator</code> in the data</code> parameter by the caller would require an additional mechanism for the receiver to verify its accuracy, and is not advisable. A loan receiver is taken as a parameter to allow flexibility on the implementation of separate loan initiators, loan receivers, and callback receivers. This parameter is not passed on to the callback receiver on the grounds that it will be often the same as callback receiver and when not, it can be encoded in the data</code> by the initiator</code>. A payment receiver</code> allows for the same flexibility on repayments as in borrows. Control flow and asset flow are independent. The amount</code> will be required in the callback function, which the lender</code> took as a parameter. An alternative implementation which would embed the amount</code> in the data</code> parameter by the caller would require an additional mechanism for the receiver to verify its accuracy, and is not advisable. A fee</code> will often be calculated in the callback function, which the callback receiver must be aware of for repayment. Passing the fee</code> as a parameter instead of appended to data</code> is simple and effective. Arbitrary callback functions on callback receivers allows to implement different behaviours to flash loans on callback receivers without the need for encoding a function router using the data</code> argument. A function call type is 24 bytes of which the first 20 bytes are the target address and the last 4 bytes are the function signature. The amount + fee</code> are pushed to the payment receiver</code> to allow for the segregation of asset and control flows. While a "pull" architecture is more prevalent, "push" architectures are also common. For those cases where the lender</code> can't implement a "push" architecture, a simple wrapper contract can offer this proposal's external interface, while using liquidity from the lender</code> using a "pull" architecture. Backwards Compatibility</h2> This EIP is a successor of ERC-3156</a>. While not directly backwards compatible, a wrapper contract offering this proposal's external interface with liquidity obtained from an ERC-3156 flash lender</code> is trivial to implement. Security Considerations</h2> Verification of callback arguments</h3> The arguments of the flash loan callbacks are expected to reflect the conditions of the flash loan, but cannot be trusted unconditionally. They can be divided in two groups, that require different checks before they can be trusted to be genuine. No arguments can be assumed to be genuine without some kind of verification. initiator</code>, asset</code> and amount</code> refer to a past transaction that might not have happened if the caller of the callback decides to lie. fee</code> might be false or calculated incorrectly. data</code> might have been manipulated by the caller.</li> To trust that the value of initiator</code>, asset</code>, amount</code> and fee</code> are genuine a reasonable pattern is to verify that the callback caller is in a whitelist of verified flash lenders. Since often the caller of flash</code> will also be receiving the callback this will be trivial. In all other cases flash lenders will need to be approved if the arguments in the callback are to be trusted.</li> To trust that the value of data</code> is genuine, in addition to the check in point 1, it is recommended to verify that the initiator</code> belongs to a group of trusted addresses. Trusting the lender</code> and the initiator</code> is enough to trust that the contents of data</code> are genuine.</li> </ol> Flash lending security considerations</h3> Automatic approvals</h4> Any receiver</code> that repays the amount</code> and fee</code> received as arguments needs to include in the callback a mechanism to verify that the initiator and lender</code> are trusted. Alternatively, the callback receiver can implement permissioned functions that set state variables indicating that a flash loan has been initiated and what to expect as amount</code> and fee</code>. Alternatively, the callback receiver can verify that amount</code> was received by the loanReceiver</code> and use its own heuristics to determine if a fee</code> is fair and the loan repaid, or the transaction reverted. Flash minting external security considerations</h3> The typical quantum of assets involved in flash mint transactions will give rise to new innovative attack vectors. Spot Oracle Manipulation</h4> The supply of a flash-mintable asset can be easily manipulated, so oracles that take the supply of the flash-mintable asset into account must either discount amounts that were flash-minted, produce data that is averaged over time, or find some other solution to the varying supply. Arithmetic Overflow and Underflow</h4> If the flash mint provider does not place any limits on the amount of flash mintable assets in a transaction, then anyone can flash mint $2^256-1$ amount of assets. The protocols on the receiving end of the flash mints will need to ensure their contracts can handle this, either by using a compiler that embeds overflow protection in the smart contract bytecode, or by setting explicit checks. Flash minting internal security considerations</h3> The coupling of flash minting with business specific features in the same platform can easily lead to unintended consequences. Treasury Draining</h4> Assume a smart contract that flash lends its native asset. The same smart contract borrows from a third party when users burn the native asset. This pattern would be used to aggregate in the smart contract the collateralized debt of several users into a single account in the third party. The flash mint could be used to cause the lender</code> to borrow to its limit, and then pushing interest rates in the underlying lender</code>, liquidate the flash lender</code>: Flash mint from lender</code> a very large amount of FOO.</li> Redeem FOO for BAR, causing lender</code> to borrow from underwriter</code> all the way to its borrowing limit.</li> Trigger a debt rate increase in underwriter</code>, making lender</code> undercollateralized.</li> Liquidate the lender</code> for profit.</li> </ol> Copyright</h2> Copyright and related rights waived via CC0</a>. Encumber - Splitting Ownership & Guarantees 2023-06-27T00:00:00+00:00 Abstract</h2> This ERC proposes an extension to the ERC-20</a> token standard by adding Encumber—the ability for an account to grant another account exclusive right to move some portion of their balance. Encumber is a stronger version of ERC-20</a> allowances. While ERC-20</a> approve grants another account the permission to transfer a specified token amount, encumber grants the same permission while ensuring that the tokens will be available when needed. Motivation</h2> This extension adds flexibility to the ERC-20</a> token standard and caters to use cases where token locking is required, but it is preferential to maintain actual ownership of tokens. This interface can also be adapted to other token standards, such as ERC-721</a>, in a straightforward manner Token holders commonly transfer their tokens to smart contracts which will return the tokens under specific conditions. In some cases, smart contracts do not actually need to hold the tokens, but need to guarantee they will be available if necessary. Since allowances do not provide a strong enough guarantee, the only way to do guarantee token availability presently is to transfer the token to the smart contract. Locking tokens without moving them gives more clear indication of the rights and ownership of the tokens. This allows for airdrops and other ancillary benefits of ownership to reach the true owner. It also adds another layer of safety, where draining a pool of ERC-20</a> tokens can be done in a single transfer, iterating accounts to transfer encumbered tokens would be significantly more prohibitive in gas usage. 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. A compliant token MUST implement the following interface /** * @dev Interface of the ERC-7246 standard. */ interface IERC7246{ /** * @dev Emitted when `amount` tokens are encumbered from `owner` to `taker`. */ event Encumber(address indexed owner, address indexed taker, uint amount); /** * @dev Emitted when the encumbrance of a `taker` to an `owner` is reduced by `amount`. */ event Release(address indexed owner, address indexed taker, uint amount); /** * @dev Returns the total amount of tokens owned by `owner` that are currently encumbered. * MUST never exceed `balanceOf(owner)` Any function which would reduce balanceOf(owner) below encumberedBalanceOf(owner) MUST revert */ function encumberedBalanceOf(address owner) external returns (uint); /** * @dev Returns the number of tokens that `owner` has encumbered to `taker`. This value increases when {encumber} or {encumberFrom} are called by the `owner` or by another permitted account. * This value decreases when {release} and {transferFrom} are called by `taker`. */ function encumbrances(address owner, address taker) external returns (uint); /** * @dev Increases the amount of tokens that the caller has encumbered to `taker` by `amount`. * Grants to `taker` a guaranteed right to transfer `amount` from the caller's balance by using `transferFrom`. MUST revert if caller does not have `amount` tokens available * (e.g. if `balanceOf(caller) - encumberedBalanceOf(caller) < amount`). Emits an {Encumber} event. */ function encumber(address taker, uint amount) external; /** * @dev Increases the amount of tokens that `owner` has encumbered to `taker` by `amount`. * Grants to `taker` a guaranteed right to transfer `amount` from `owner` using transferFrom The function SHOULD revert unless the owner account has deliberately authorized the sender of the message via some mechanism. MUST revert if `owner` does not have `amount` tokens available * (e.g. if `balanceOf(owner) - encumberedBalanceOf(owner) < amount`). Emits an {Encumber} event. */ function encumberFrom(address owner, address taker, uint amount) external; /** * @dev Reduces amount of tokens encumbered from `owner` to caller by `amount` Emits a {Release} event. */ function release(address owner, uint amount) external; /** * @dev Convenience function for reading the unencumbered balance of an address. * Trivially implemented as `balanceOf(owner) - encumberedBalanceOf(owner)` */ function availableBalanceOf(address owner) public view returns (uint); }</code></pre>Rationale</h2> The specification was designed to complement and mirror the ERC-20 specification to ease adoption and understanding. The specification is intentionally minimally proscriptive of this joining, where the only true requirement is that an owner cannot transfer encumbered tokens. However, the example implementation includes some decisions about where to connect with ERC-20 functions worth noting. It was designed for minimal invasiveness of standard ERC-20 definitions. The example has a dependency on approve</code> to facilitate encumberFrom</code>. This proposal allows for an implementer to define another mechanism, such as an approveEncumber</code> which would mirror ERC-20 allowances, if desired.</li> transferFrom(src, dst, amount)</code> is written to first reduce the encumbrances(src, amount)</code>, and then subsequently spend from allowance(src, msg.sender)</code>. Alternatively, transferFrom</code> could be implemented to spend from allowance simultaneously to spending encumbrances. This would require approve</code> to check that the approved balance does not decrease beneath the amount required by encumbered balances, and also make creating the approval a prerequisite to calling encumber</code>.</li> </ul> It is possible to stretch the Encumber interface to cover ERC-721 tokens by using the tokenId</code> in place of amount</code> param since they are both uint</code>. The interface opts for clarity with the most likely use case (ERC-20), even if it is compatible with other formats. Backwards Compatibility</h2> This EIP is backwards compatible with the existing ERC-20</a> standard. Implementations must add the functionality to block transfer of tokens that are encumbered to another account. Reference Implementation</h2> This can be implemented as an extension of any base ERC-20</a> contract by modifying the transfer function to block the transfer of encumbered tokens and to release encumbrances when spent via transferFrom. // An erc-20 token that implements the encumber interface by blocking transfers. pragma solidity ^0.8.0; import {ERC20} from "../lib/openzeppelin-contracts/contracts/token/ERC20/ERC20.sol"; import { IERC7246 } from "./IERC7246.sol"; contract EncumberableERC20 is ERC20, IERC7246 { // Owner -> Taker -> Amount that can be taken mapping (address => mapping (address => uint)) public encumbrances; // The encumbered balance of the token owner. encumberedBalance must not exceed balanceOf for a user // Note this means rebasing tokens pose a risk of diminishing and violating this prototocol mapping (address => uint) public encumberedBalanceOf; address public minter; constructor(string memory name, string memory symbol) ERC20(name, symbol) { minter = msg.sender; } function mint(address recipient, uint amount) public { require(msg.sender == minter, "only minter"); _mint(recipient, amount); } function encumber(address taker, uint amount) external { _encumber(msg.sender, taker, amount); } function encumberFrom(address owner, address taker, uint amount) external { require(allowance(owner, msg.sender) >= amount); _encumber(owner, taker, amount); } function release(address owner, uint amount) external { _release(owner, msg.sender, amount); } // If bringing balance and encumbrances closer to equal, must check function availableBalanceOf(address a) public view returns (uint) { return (balanceOf(a) - encumberedBalanceOf[a]); } function _encumber(address owner, address taker, uint amount) private { require(availableBalanceOf(owner) >= amount, "insufficient balance"); encumbrances[owner][taker] += amount; encumberedBalanceOf[owner] += amount; emit Encumber(owner, taker, amount); } function _release(address owner, address taker, uint amount) private { if (encumbrances[owner][taker] < amount) { amount = encumbrances[owner][taker]; } encumbrances[owner][taker] -= amount; encumberedBalanceOf[owner] -= amount; emit Release(owner, taker, amount); } function transfer(address dst, uint amount) public override returns (bool) { // check but dont spend encumbrance require(availableBalanceOf(msg.sender) >= amount, "insufficient balance"); _transfer(msg.sender, dst, amount); return true; } function transferFrom(address src, address dst, uint amount) public override returns (bool) { uint encumberedToTaker = encumbrances[src][msg.sender]; bool exceedsEncumbrance = amount > encumberedToTaker; if (exceedsEncumbrance) { uint excessAmount = amount - encumberedToTaker; // check that enough unencumbered tokens exist to spend from allowance require(availableBalanceOf(src) >= excessAmount, "insufficient balance"); // Exceeds Encumbrance , so spend all of it _spendEncumbrance(src, msg.sender, encumberedToTaker); _spendAllowance(src, dst, excessAmount); } else { _spendEncumbrance(src, msg.sender, amount); } _transfer(src, dst, amount); return true; } function _spendEncumbrance(address owner, address taker, uint256 amount) internal virtual { uint256 currentEncumbrance = encumbrances[owner][taker]; require(currentEncumbrance >= amount, "insufficient encumbrance"); uint newEncumbrance = currentEncumbrance - amount; encumbrances[owner][taker] = newEncumbrance; encumberedBalanceOf[owner] -= amount; emit Release(owner, taker, amount); } }</code></pre>Security Considerations</h2> Parties relying on balanceOf</code> to determine the amount of tokens available for transfer should instead rely on balanceOf(account) - encumberedBalance(account)</code>, or, if implemented, availableBalanceOf(account)</code>. The property that encumbered balances are always backed by a token balance can be accomplished in a straightforward manner by altering transfer</code> and transferFrom</code> to block . If there are other functions that can alter user balances, such as a rebasing token or an admin burn function, additional guards must be added by the implementer to likewise ensure those functions prevent reducing balanceOf(account)</code> below encumberedBalanceOf(account)</code> for any given account. Copyright</h2> Copyright and related rights waived via CC0</a>. NFT Creator Attribution 2023-05-11T00:00:00+00:00 Abstract</h2> This Ethereum Improvement Proposal aims to solve the issue of creator attribution for Non-Fungible Token (NFT) standards (ERC-721</a>, ERC-1155</a>). To achieve this, this EIP proposes a mechanism where the NFT creator signs the required parameters for the NFT creation, including the NFT metadata in a hash along with any other relevant information. The signed parameters and the signature are then validated and emitted during the deployment transaction, which allows the NFT to validate the creator and NFT platforms to attribute creatorship correctly. This method ensures that even if a different wallet sends the deployment transaction, the correct account is attributed as the creator. Motivation</h2> Current NFT platforms assume that the wallet deploying the smart contract is the creator of the NFT, leading to a misattribution in cases where a different wallet sends the deployment transaction. This happens often when working with smart wallet accounts, and new contract deployment strategies such as the first collector deploying the NFT contract. This proposal aims to solve the problem by allowing creators to sign the parameters required for NFT creation so that any wallet can send the deployment transaction with an signal in a verifiable way who is the creator. 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. ERC-721 and ERC-1155 compliant contracts MAY implement this NFT Creator Attribution extension to provide a standard event to be emitted that defines the NFT creator at the time of contract creation. This EIP takes advantage of the fact that contract addresses can be precomputed before a contract is deployed. Whether the NFT contract is deployed through another contract (a factory) or through an EOA, the creator can be correctly attributed using this specification. Signing Mechanism Creator consent is given by signing an EIP-712</a> compatible message; all signatures compliant with this EIP MUST include all fields defined. The struct signed can be any arbitrary data that defines how to create the token; it must hashed in an EIP-712 compatible format with a proper EIP-712 domain. The following shows some examples of structs that could be encoded into structHash</code> (defined below): // example struct that can be encoded in `structHash`; defines that a token can be created with a metadataUri and price: struct TokenCreation { string metadataUri; uint256 price; uint256 nonce; }</code></pre> Signature Validation Creator attribution is given through a signature verification that MUST be verified by the NFT contract being deployed and an event that MUST be emitted by the NFT contract during the deployment transaction. The event includes all the necessary fields for reconstructing the signed digest and validating the signature to ensure it matches the specified creator. The event name is CreatorAttribution</code> and includes the following fields: structHash</code>: hashed information for deploying the NFT contract (e.g. name, symbol, admins etc). This corresponds to the value hashStruct</code> as defined in the EIP-712 definition of hashStruct</a> standard.</li> domainName</code>: the domain name of the contract verifying the signature (for EIP-712 signature validation).</li> version</code>: the version of the contract verifying the signature (for EIP-712 signature validation)</li> creator</code>: the creator's account</li> signature</code>: the creator’s signature</li> </ul> The event is defined as follows: event CreatorAttribution( bytes32 structHash, string domainName, string version, address creator, bytes signature );</code></pre> Note that although the chainId</code> parameters is necessary for EIP-712</a> signatures, we omit the parameter from the event as it can be inferred through the transaction data. Similarly, the verifyingContract</code> parameter for signature verification is omitted since it MUST be the same as the emitter</code> field in the transaction. emitter</code> MUST be the token. A platform can verify the validity of the creator attribution by reconstructing the signature digest with the parameters emitted and recovering the signer from the signature</code> parameter. The recovered signer MUST match the creator</code> emitted in the event. If CreatorAttribution</code> event is present creator and the signature is validated correctly, attribution MUST be given to the creator</code> instead of the account that submitted the transaction. Reference Implementation</h3> Example signature validator</h4> pragma solidity 0.8.20; import "@openzeppelin/contracts/utils/cryptography/EIP712.sol"; import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol"; import "@openzeppelin/contracts/interfaces/IERC1271.sol"; abstract contract ERC7015 is EIP712 { error Invalid_Signature(); event CreatorAttribution( bytes32 structHash, string domainName, string version, address creator, bytes signature ); /// @notice Define magic value to verify smart contract signatures (ERC1271). bytes4 internal constant MAGIC_VALUE = bytes4(keccak256("isValidSignature(bytes32,bytes)")); function _validateSignature( bytes32 structHash, address creator, bytes memory signature ) internal { if (!_isValid(structHash, creator, signature)) revert Invalid_Signature(); emit CreatorAttribution(structHash, "ERC7015", "1", creator, signature); } function _isValid( bytes32 structHash, address signer, bytes memory signature ) internal view returns (bool) { require(signer != address(0), "cannot validate"); bytes32 digest = _hashTypedDataV4(structHash); // if smart contract is the signer, verify using ERC-1271 smart-contract /// signature verification method if (signer.code.length != 0) { try IERC1271(signer).isValidSignature(digest, signature) returns ( bytes4 magicValue ) { return MAGIC_VALUE == magicValue; } catch { return false; } } // otherwise, recover signer and validate that it matches the expected // signer address recoveredSigner = ECDSA.recover(digest, signature); return recoveredSigner == signer; } }</code></pre>Rationale</h2> By standardizing the CreatorAttribution</code> event, this EIP enables platforms to ascertain creator attribution without relying on implicit assumptions. Establishing a standard for creator attribution empowers platforms to manage the complex aspects of deploying contracts while preserving accurate onchain creator information. This approach ensures a more reliable and transparent method for identifying NFT creators, fostering trust among participants in the NFT ecosystem. ERC-5375</a> attempts to solve the same issue and although offchain data offers improved backward compatibility, ensuring accurate and immutable creator attribution is vital for NFTs. A standardized onchain method for creator attribution is inherently more reliable and secure. In contrast to this proposal, ERC-5375 does not facilitate specifying creators for all tokens within an NFT collection, which is a prevalent practice, particularly in emerging use cases. Both this proposal and ERC-5375 share similar limitations regarding address-based creator attribution: The standard defines a protocol to verify that a certain address provided consent. However, it does not guarantee that the address corresponds to the expected creator […]. Proving a link between an address and the entity behind it is beyond the scope of this document. </blockquote> Backwards Compatibility</h2> Since the standard requires an event to be emitted during the NFTs deployment transaction, existing NFTs cannot implement this standard. Security Considerations</h2> A potential attack exploiting this proposal could involve deceiving creators into signing creator attribution consent messages unintentionally. Consequently, creators MUST ensure that all signature fields correspond to the necessary ones before signing. Copyright</h2> Copyright and related rights waived via CC0</a>. ERC-721 with transaction validation step. 2023-05-07T00:00:00+00:00 Abstract</h2> This standard is an extension of ERC-721</a>. It defines new validation functionality to avoid wallet draining: every transfer</code> or approve</code> will be locked waiting for validation. Motivation</h2> The power of the blockchain is at the same time its weakness: giving the user full responsibility for their data. Many cases of NFT theft currently exist, and current NFT anti-theft schemes, such as transferring NFTs to cold wallets, make NFTs inconvenient to use. Having a validation step before every transfer</code> and approve</code> would give Smart Contract developers the opportunity to create secure NFT anti-theft schemes. An implementation example would be a system where a validator address is responsible for validating all Smart Contract transactions. This address would be connected to a dApp where the user could see the validation requests of his NFTs and accept the correct ones. Giving this address only the power to validate transactions would make a much more secure system where to steal an NFT the thief would have to have both the user's address and the validator address simultaneously. 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. ERC-721</a> compliant contracts MAY implement this EIP. All the operations that change the ownership of an NFT, like a transferFrom</code>/safeTransferFrom</code>, SHALL create a TransferValidation</code> pending to be validated and emit a ValidateTransfer</code>, and SHALL NOT transfer the ownership of an NFT. All the operations that enable an approval to manage an NFT, like an approve</code>/setApprovalForAll</code>, SHALL create an ApprovalValidation</code> pending to be validated and emit a ValidateApproval</code>, and SHALL NOT enable an approval. When the transfer is called by an approved account and not the owner, it MUST be executed directly without the need for validation. This is in order to adapt to all current marketplaces that require approve to directly move your NFTs. When validating a TransferValidation</code> or ApprovalValidation</code> the valid field MUST be set to true and MUST NOT be validated again. The operations that validate a TransferValidation</code> SHALL change the ownership of the NFT or enable the approval. The operations that validate an ApprovalValidation</code> SHALL enable the approval. Contract Interface</h3> interface IERC6997 { struct TransferValidation { // The address of the owner. address from; // The address of the receiver. address to; // The token Id. uint256 tokenId; // Whether is a valid transfer. bool valid; } struct ApprovalValidation { // The address of the owner. address owner; // The approved address. address approve; // The token Id. uint256 tokenId; // Whether it is a total approval. bool approveAll; // Whether it is a valid approval. bool valid; } /** * @dev Emitted when a new transfer validation has been requested. */ event ValidateTransfer(address indexed from, address to, uint256 indexed tokenId, uint256 indexed transferValidationId); /** * @dev Emitted when a new approval validation has been requested. */ event ValidateApproval(address indexed owner, address approve, uint256 tokenId, bool indexed approveAll, uint256 indexed approvalValidationId); /** * @dev Returns true if this contract is a validator ERC721. */ function isValidatorContract() external view returns (bool); /** * @dev Returns the transfer validation struct using the transfer ID. / function transferValidation(uint256 transferId) external view returns (TransferValidation memory); /** * @dev Returns the approval validation struct using the approval ID. / function approvalValidation(uint256 approvalId) external view returns (ApprovalValidation memory); /** * @dev Return the total amount of transfer validations created. / function totalTransferValidations() external view returns (uint256); /** * @dev Return the total amount of transfer validations created. / function totalApprovalValidations() external view returns (uint256); }</code></pre> The isValidatorContract()</code> function MUST be implemented as public</code>. The transferValidation(uint256 transferId)</code> function MAY be implemented as public</code> or external</code>. The approvalValidation(uint256 approveId)</code> function MAY be implemented as public</code> or external</code>. The totalTransferValidations()</code> function MAY be implemented as pure</code> or view</code>. The totalApprovalValidations()</code> function MAY be implemented as pure</code> or view</code>. Rationale</h2> Universality</h3> The standard only defines the validation functions, but not how they should be used. It defines the validations as internal and lets the user decide how to manage them. An example could be to have an address validator connected to a dApp so that users could manage their validations. This validator could be used for all NFTs or only for some users. It could also be used as a wrapped Smart Contract for existing ERC-721, allowing 1/1 conversion with existing NFTs. Extensibility</h3> This standard only defines the validation function, but does not define the system with which it has to be validated. A third-party protocol can define how it wants to call these functions as it wishes. Backwards Compatibility</h2> This standard is an extension of ERC-721</a>, compatible with all the operations except transferFrom</code>/safeTransferFrom</code>/approve</code>/setApprovalForAll</code>. This operations will be overridden to create a validation petition instead of transfer ownership of an NFT or enable an approval. Reference Implementation</h2> // SPDX-License-Identifier: CC0-1.0 pragma solidity ^0.8.0; import "./IERC6997.sol"; import "@openzeppelin/contracts/token/ERC721/ERC721.sol"; /** * @dev Implementation of ERC6997 */ contract ERC6997 is IERC6997, ERC721 { // Mapping from transfer ID to transfer validation mapping(uint256 => TransferValidation) private _transferValidations; // Mapping from approval ID to approval validation mapping(uint256 => ApprovalValidation) private _approvalValidations; // Total number of transfer validations uint256 private _totalTransferValidations; // Total number of approval validations uint256 private _totalApprovalValidations; /** * @dev Initializes the contract by setting a `name` and a `symbol` to the token collection. */ constructor(string memory name_, string memory symbol_) ERC721(name_, symbol_){ } /** * @dev Returns true if this contract is a validator ERC721. */ function isValidatorContract() public pure returns (bool) { return true; } /** * @dev Returns the transfer validation struct using the transfer ID. / function transferValidation(uint256 transferId) public view override returns (TransferValidation memory) { require(transferId < _totalTransferValidations, "ERC6997: invalid transfer ID"); TransferValidation memory v = _transferValidation(transferId); return v; } /** * @dev Returns the approval validation struct using the approval ID. / function approvalValidation(uint256 approvalId) public view override returns (ApprovalValidation memory) { require(approvalId < _totalApprovalValidations, "ERC6997: invalid approval ID"); ApprovalValidation memory v = _approvalValidation(approvalId); return v; } /** * @dev Return the total amount of transfer validations created. / function totalTransferValidations() public view override returns (uint256) { return _totalTransferValidations; } /** * @dev Return the total amount of approval validations created. / function totalApprovalValidations() public view override returns (uint256) { return _totalApprovalValidations; } /** * @dev Returns the transfer validation of the `transferId`. Does NOT revert if transfer doesn't exist */ function _transferValidation(uint256 transferId) internal view virtual returns (TransferValidation memory) { return _transferValidations[transferId]; } /** * @dev Returns the approval validation of the `approvalId`. Does NOT revert if transfer doesn't exist */ function _approvalValidation(uint256 approvalId) internal view virtual returns (ApprovalValidation memory) { return _approvalValidations[approvalId]; } /** * @dev Validate the transfer using the transfer ID. / function _validateTransfer(uint256 transferId) internal virtual { TransferValidation memory v = transferValidation(transferId); require(!v.valid, "ERC6997: the transfer is already validated"); address from = v.from; address to = v.to; uint256 tokenId = v.tokenId; super._transfer(from, to, tokenId); _transferValidations[transferId].valid = true; } /** * @dev Validate the approval using the approval ID. / function _validateApproval(uint256 approvalId) internal virtual { ApprovalValidation memory v = approvalValidation(approvalId); require(!v.valid, "ERC6997: the approval is already validated"); if(!v.approveAll) { require(v.owner == ownerOf(v.tokenId), "ERC6997: The token have a new owner"); super._approve(v.approve, v.tokenId); } else { super._setApprovalForAll(v.owner, v.approve, true); } _approvalValidations[approvalId].valid = true; } /** * @dev Create a transfer petition of `tokenId` from `from` to `to`. Requirements: - `to` cannot be the zero address. * - `tokenId` token must be owned by `from`. Emits a {TransferValidate} event. */ function _transfer( address from, address to, uint256 tokenId ) internal virtual override { require(ERC721.ownerOf(tokenId) == from, "ERC6997: transfer from incorrect owner"); require(to != address(0), "ERC6997: transfer to the zero address"); if(_msgSender() == from) { TransferValidation memory v; v.from = from; v.to = to; v.tokenId = tokenId; _transferValidations[_totalTransferValidations] = v; emit ValidateTransfer(from, to, tokenId, _totalTransferValidations); _totalTransferValidations++; } else { super._transfer(from, to, tokenId); } } /** * @dev Create an approval petition from `to` to operate on `tokenId` Emits an {ValidateApproval} event. */ function _approve(address to, uint256 tokenId) internal override virtual { ApprovalValidation memory v; v.owner = ownerOf(tokenId); v.approve = to; v.tokenId = tokenId; _approvalValidations[_totalApprovalValidations] = v; emit ValidateApproval(v.owner, to, tokenId, false, _totalApprovalValidations); _totalApprovalValidations++; } /** * @dev If approved is true create an approval petition from `operator` to operate on * all of `owner` tokens, if not remove `operator` from operate on all of `owner` tokens Emits an {ValidateApproval} event. */ function _setApprovalForAll( address owner, address operator, bool approved ) internal override virtual { require(owner != operator, "ERC6997: approve to caller"); if(approved) { ApprovalValidation memory v; v.owner = owner; v.approve = operator; v.approveAll = true; _approvalValidations[_totalApprovalValidations] = v; emit ValidateApproval(v.owner, operator, 0, true, _totalApprovalValidations); _totalApprovalValidations++; } else { super._setApprovalForAll(owner, operator, approved); } } }</code></pre>Security Considerations</h2> As is defined in the Specification the operations that change the ownership of an NFT or enable an approval to manage the NFT SHALL create a TransferValidation</code> or an ApprovalValidation</code> pending to be validated and SHALL NOT transfer the ownership of an NFT or enable an approval. With this premise in mind, the operations in charge of validating a TransferValidation</code> or an ApprovalValidation</code> must be protected with the maximum security required by the applied system. For example, a valid system would be one where there is a validator address in charge of validating the transactions. To give another example, a system where each user could choose his validator address would also be correct. In any case, the importance of security resides in the fact that no address can validate a TransferValidation</code> or an ApprovalValidation</code> without the permission of the chosen system. Copyright</h2> Copyright and related rights waived via CC0</a>. ERC-20 with transaction validation step. 2023-05-07T00:00:00+00:00 Abstract</h2> This standard is an extension of ERC-20</a>. It defines new validation functionality to avoid wallet draining: every transfer</code> or approve</code> will be locked waiting for validation. Motivation</h2> The power of the blockchain is at the same time its weakness: giving the user full responsibility for their data. Many cases of Token theft currently exist, and current Token anti-theft schemes, such as transferring Tokens to cold wallets, make Tokens inconvenient to use. Having a validation step before every transfer</code> and approve</code> would give Smart Contract developers the opportunity to create secure Token anti-theft schemes. An implementation example would be a system where a validator address is responsible for validating all Smart Contract transactions. This address would be connected to a dApp where the user could see the validation requests of his Tokens and accept the correct ones. Giving this address only the power to validate transactions would make a much more secure system where to steal a Token the thief would have to have both the user's address and the validator address simultaneously. 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. ERC-20</a> compliant contracts MAY implement this EIP. All the operations that change the ownership of Tokens, like a transfer</code>/transferFrom</code>, SHALL create a TransferValidation</code> pending to be validated and emit a ValidateTransfer</code>, and SHALL NOT transfer the Tokens. All the operations that enable an approval to manage a Token, like an approve</code>, SHALL create an ApprovalValidation</code> pending to be validated and emit a ValidateApproval</code>, and SHALL NOT enable an approval. When the transfer is called by an approved account and not the owner, it MUST be executed directly without the need for validation. This is in order to adapt to all current projects that require approve to directly move your Tokens. When validating a TransferValidation</code> or ApprovalValidation</code> the valid field MUST be set to true and MUST NOT be validated again. The operations that validate a TransferValidation</code> SHALL change the ownership of the Tokens. The operations that validate an ApprovalValidation</code> SHALL enable the approval. Contract Interface</h3> interface IERC7144 { struct TransferValidation { // The address of the owner. address from; // The address of the receiver. address to; // The token amount. uint256 amount; // Whether is a valid transfer. bool valid; } struct ApprovalValidation { // The address of the owner. address owner; // The spender address. address spender; // The token amount approved. uint256 amount; // Whether is a valid approval. bool valid; } /** * @dev Emitted when a new transfer validation has been requested. */ event ValidateTransfer(address indexed from, address indexed to, uint256 amount, uint256 indexed transferValidationId); /** * @dev Emitted when a new approval validation has been requested. */ event ValidateApproval(address indexed owner, address indexed spender, uint256 amount, uint256 indexed approvalValidationId); /** * @dev Returns true if this contract is a validator ERC20. */ function isValidatorContract() external view returns (bool); /** * @dev Returns the transfer validation struct using the transfer ID. / function transferValidation(uint256 transferId) external view returns (TransferValidation memory); /** * @dev Returns the approval validation struct using the approval ID. / function approvalValidation(uint256 approvalId) external view returns (ApprovalValidation memory); /** * @dev Return the total amount of transfer validations created. / function totalTransferValidations() external view returns (uint256); /** * @dev Return the total amount of transfer validations created. / function totalApprovalValidations() external view returns (uint256); }</code></pre> The isValidatorContract()</code> function MUST be implemented as public</code>. The transferValidation(uint256 transferId)</code> function MAY be implemented as public</code> or external</code>. The approvalValidation(uint256 approveId)</code> function MAY be implemented as public</code> or external</code>. The totalTransferValidations()</code> function MAY be implemented as pure</code> or view</code>. The totalApprovalValidations()</code> function MAY be implemented as pure</code> or view</code>. Rationale</h2> Universality</h3> The standard only defines the validation functions, but not how they should be used. It defines the validations as internal and lets the user decide how to manage them. An example could be to have an address validator connected to a dApp so that users could manage their validations. This validator could be used for all Tokens or only for some users. It could also be used as a wrapped Smart Contract for existing ERC-20, allowing 1/1 conversion with existing Tokens. Extensibility</h3> This standard only defines the validation function, but does not define the system with which it has to be validated. A third-party protocol can define how it wants to call these functions as it wishes. Backwards Compatibility</h2> This standard is an extension of ERC-20</a>, compatible with all the operations except transfer</code>/transferFrom</code>/approve</code>. This operations will be overridden to create a validation petition instead of transfer the Tokens or enable an approval. Reference Implementation</h2> // SPDX-License-Identifier: CC0-1.0 pragma solidity ^0.8.0; import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; import "./IERC7144.sol"; /** * @dev Implementation of ERC7144 */ contract ERC7144 is IERC7144, ERC20 { // Mapping from transfer ID to transfer validation mapping(uint256 => TransferValidation) private _transferValidations; // Mapping from approval ID to approval validation mapping(uint256 => ApprovalValidation) private _approvalValidations; // Total number of transfer validations uint256 private _totalTransferValidations; // Total number of approval validations uint256 private _totalApprovalValidations; /** * @dev Initializes the contract by setting a `name` and a `symbol` to the token collection. */ constructor(string memory name_, string memory symbol_) ERC20(name_, symbol_){ } /** * @dev Returns true if this contract is a validator ERC721. */ function isValidatorContract() public pure returns (bool) { return true; } /** * @dev Returns the transfer validation struct using the transfer ID. / function transferValidation(uint256 transferId) public view override returns (TransferValidation memory) { require(transferId < _totalTransferValidations, "ERC7144: invalid transfer ID"); TransferValidation memory v = _transferValidation(transferId); return v; } /** * @dev Returns the approval validation struct using the approval ID. / function approvalValidation(uint256 approvalId) public view override returns (ApprovalValidation memory) { require(approvalId < _totalApprovalValidations, "ERC7144: invalid approval ID"); ApprovalValidation memory v = _approvalValidation(approvalId); return v; } /** * @dev Return the total amount of transfer validations created. / function totalTransferValidations() public view override returns (uint256) { return _totalTransferValidations; } /** * @dev Return the total amount of approval validations created. / function totalApprovalValidations() public view override returns (uint256) { return _totalApprovalValidations; } /** * @dev Returns the transfer validation of the `transferId`. Does NOT revert if transfer doesn't exist */ function _transferValidation(uint256 transferId) internal view virtual returns (TransferValidation memory) { return _transferValidations[transferId]; } /** * @dev Returns the approval validation of the `approvalId`. Does NOT revert if transfer doesn't exist */ function _approvalValidation(uint256 approvalId) internal view virtual returns (ApprovalValidation memory) { return _approvalValidations[approvalId]; } /** * @dev Validate the transfer using the transfer ID. / function _validateTransfer(uint256 transferId) internal virtual { TransferValidation memory v = transferValidation(transferId); require(!v.valid, "ERC721V: the transfer is already validated"); super._transfer(v.from, v.to, v.amount); _transferValidations[transferId].valid = true; } /** * @dev Validate the approval using the approval ID. / function _validateApproval(uint256 approvalId) internal virtual { ApprovalValidation memory v = approvalValidation(approvalId); require(!v.valid, "ERC7144: the approval is already validated"); super._approve(v.owner, v.spender, v.amount); _approvalValidations[approvalId].valid = true; } /** * @dev Create a transfer petition of `tokenId` from `from` to `to`. Requirements: - `from` cannot be the zero address. * - `to` cannot be the zero address. Emits a {ValidateTransfer} event. */ function _transfer( address from, address to, uint256 amount ) internal virtual override { require(from != address(0), "ERC7144: transfer from the zero address"); require(to != address(0), "ERC7144: transfer to the zero address"); if(_msgSender() == from) { TransferValidation memory v; v.from = from; v.to = to; v.amount = amount; _transferValidations[_totalTransferValidations] = v; emit ValidateTransfer(from, to, amount, _totalTransferValidations); _totalTransferValidations++; } else { super._transfer(from, to, amount); } } /** * @dev Create an approval petition from `owner` to operate the `amount` Emits an {ValidateApproval} event. */ function _approve( address owner, address spender, uint256 amount ) internal virtual override { require(owner != address(0), "ERC7144: approve from the zero address"); require(spender != address(0), "ERC7144: approve to the zero address"); ApprovalValidation memory v; v.owner = owner; v.spender = spender; v.amount = amount; _approvalValidations[_totalApprovalValidations] = v; emit ValidateApproval(v.owner, spender, amount, _totalApprovalValidations); _totalApprovalValidations++; } }</code></pre>Security Considerations</h2> As is defined in the Specification the operations that change the ownership of Tokens or enable an approval to manage the Tokens SHALL create a TransferValidation</code> or an ApprovalValidation</code> pending to be validated and SHALL NOT transfer the Tokens or enable an approval. With this premise in mind, the operations in charge of validating a TransferValidation</code> or an ApprovalValidation</code> must be protected with the maximum security required by the applied system. For example, a valid system would be one where there is a validator address in charge of validating the transactions. To give another example, a system where each user could choose his validator address would also be correct. In any case, the importance of security resides in the fact that no address can validate a TransferValidation</code> or an ApprovalValidation</code> without the permission of the chosen system. Copyright</h2> Copyright and related rights waived via CC0</a>. Asset-bound Non-Fungible Tokens 2023-04-29T00:00:00+00:00 Abstract</h2> This standard allows integrating physical and digital ASSETS without signing capabilities into dApps/web3 by extending ERC-721</a>. An ASSET, for example a physical object, is marked with a uniquely identifiable ANCHOR. The ANCHOR is bound in a secure and inseparable manner 1:1 to an NFT on-chain - over the complete life cycle of the ASSET. Through an ATTESTATION, an ORACLE testifies that a particular ASSET associated with an ANCHOR has been CONTROLLED when defining the to</code>-address for certain operations (mint, transfer, burn, approve, ...). The ORACLE signs the ATTESTATION off-chain. The operations are authorized through verifying on-chain that ATTESTATION has been signed by a trusted ORACLE. Note that authorization is solely provided through the ATTESTATION, or in other words, through PROOF-OF-CONTROL over the ASSET. The controller of the ASSET is guaranteed to be the controller of the Asset-Bound NFT. The proposed ATTESTATION-authorized operations such as transferAnchor(attestation)</code> are permissionless, meaning neither the current owner (from</code>-address) nor the receiver (to</code>-address) need to sign. Figure 1 shows the data flow of an ASSET-BOUND NFT transfer. The simplified system is utilizing a smartphone as user-device to interact with a physical ASSET and specify the to</code>-address. Motivation</h2> The well-known ERC-721</a> establishes that NFTs may represent "ownership over physical properties [...] as well as digital collectables and even more abstract things such as responsibilities" - in a broader sense, we will refer to all those things as ASSETS, which typically have value to people. The Problem</h3> ERC-721 outlines that "NFTs can represent ownership over digital or physical assets". ERC-721 excels in this task when used to represent ownership over digital, on-chain assets, that is when the asset is "holding a token of a specific contract" or the asset is an NFT's metadata. Today, people commonly treat an NFT's metadata (images, traits, ...) as asset-class, with their rarity often directly defining the value of an individual NFT. However, we see integrity issues not solvable with ERC-721, primarily when NFTS are used to represent off-chain ASSETS ("ownership over physical products", "digital collectables", "in-game assets", "responsibilities", ...). Over an ASSET's lifecycle, the ASSET's ownership and possession state changes multiple, sometimes thousands, of times. Each of those state changes may result in shifting obligations and privileges for the involved parties. Therefore tokenization of an ASSET without enforcably anchoring the ASSET's associated obligation and properties to the token is not complete. Nowadays, off-chain ASSETs are often "anchored" through adding an ASSET-identifier to a NFT's metadata. NFT-ASSET integrity: Contrary to a popular belief among NFT-investors, metadata is data that is, more often than not, mutable and off-chain. Therefore the link between an ASSET through an asset-identifier stored in mutable metadata, which is only linked to the NFT through tokenURI, can be considered weak at best. Approaches to ensure integrity between metadata (=reference to ASSET) and a token exist. This is most commonly achieved by storing metadata-hashes onchain. Additional problems arise through hashing; For many applications, metadata (besides the asset-identifier) should be update-able. Therefore making metadata immutable through storing a hash is problematic. Further the offchain metadata-resource specified via tokenURI must be made available until eternity, which has historically been subject to failure (IPFS bucket disappears, central tokenURI-provider has downtimes, ...) Off-chain-on-chain-integrity: There are approaches where off-chain ASSET ownership is enforced or conditioned through having ownership over the on-chain representation. A common approach is to burn tokens in order to get the (physical) ASSET, as the integrity cannot be maintained. However, there are no approaches known, where on-chain ownership is enforced through having off-chain ownership of the ASSET. Especially when the current owner of an NFT is incooperative or incapacitated, integrity typically fail due to lack of signing-power from the current NFT owner. Metadata is off-chain. The majority of implementations completely neglect that metadata is mutable. More serious implementations strive to preserve integrity by for example hashing metadata and storing the hash mapped to the tokenId on-chain. However, this approach does not allow for use-case, where metadata besides the asset-identifier, for example traits, "hours played", ... shall be mutable or evolvable. ASSET-BOUND NON-FUNGIBLE TOKENS</h3> In this standard we propose to Elevate the concept of representing physical or digital off-chain ASSETS by on-chain ANCHORING the ASSET inseperably into an NFT.</li> Being off-chain in control over the ASSET must mean being on-chain in control over the anchored NFT.</li> (Related) A change in off-chain ownership over the ASSET inevitably should be reflected by a change in on-chain ownership over the anchored NFT, even if the current owner is uncooperative or incapacitated.</li> </ol> As 2. and 3. indicate, the control/ownership/possession of the ASSET should be the single source of truth, not the possession of an NFT. Hence, we propose an ASSET-BOUND NFT, where off-chain CONTROL over the ASSET enforces on-chain CONTROL over the anchored NFT. Also the proposed ASSET-BOUND NFTs allow to anchor digital metadata inseperably to the ASSET. When the ASSET is a physical asset, this allows to design "phygitals" in their purest form, namely creating a "phygital" asset with a physical and digital component that are inseparable. Note that metadata itself can still change, for instance for "Evolvable NFT". We propose to complement the existing transfer control mechanisms of a token according to ERC-721</a> by another mechanism; ATTESTATION. An ATTESTATION is signed off-chain by the ORACLE and must only be issued when the ORACLE verified that whoever specifies the to</code> address or beneficiary address has simultaneously been in control over the ASSET. The to</code> address of an attestation may be used for Transfers as well as for approvals and other authorizations. Transactions authorized via ATTESTATION shall not require signature or approval from neither the from</code> (donor, owner, sender) nor to</code> (beneficiary, receiver) account, namely making transfers permissionless. Ideally, transaction are signed independent from the ORACLE as well, allowing different scenarios in terms of gas-fees. Lastly we want to mention two major side-benefits of using the proposed standard, which drastically lowers hurdles in onboarding web2 users and increase their security; New users, e.g 0xaa...aa</code> (Fig.1), can use gasless wallets, hence participate in Web3/dApps/DeFi and mint+transfer tokens without ever owning crypto currency. Gas-fees may be paid through a third-party account 0x..gasPayer</code> (Fig.1). The gas is typically covered by the ASSET issuer, who signs transferAnchor()</code> transactions</li> Users cannot get scammed. Common attacks (for example wallet-drainer scams) are no longer possible or easily reverted, since only the anchored NFT can be stolen, not the ASSET itself. Also mishaps like transferring the NFT to the wrong account, losing access to an account etc can be mitigated by executing another transferAnchor()</code> transaction based on proofing control over the ASSET, namely the physical object.</li> </ul> Related work</h3> We primarily aim to onboard physical or digital ASSETS into dApps, which do not signing-capabilities of their own (contrary to other proposals relying on crypto-chips). Note that we do not see any restrictions preventing to use such solutions in combination with this standard, as the address of the crypto-chip qualifies as an ANCHOR. 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. Definitions (alphabetical)</h3> ANCHOR uniquely identifies the off-chain ASSET, whether it is physical or digital. </li> ANCHOR-TECHNOLOGY MUST ensure that the ANCHOR is inseparable from the ASSET (physically or otherwise)</li> an ORACLE can establish PROOF-OF-CONTROL over the ASSET beyond reasonable doubt</li> For physical ASSETS, additional Security considerations for Physical Assets</a> MUST be taken into account</li> </ul> </li> ASSET refers to the "thing", being it physical or digital, which is represented through NFTs according to the proposed standard. Typically, an ASSET does not have signing capabilities. </li> ATTESTATION is the confirmation that PROOF OF CONTROL was established when specifying the to</code> (receiver, beneficiary) address. </li> PROOF-OF-CONTROL over the ASSET means owning or otherwise controlling an ASSET. How Proof of Control is established depends on the ASSET and may be implemented using technical, legal or other means. For physical ASSETS, CONTROL is typically verified by proofing physical proximity between a physical ASSET and an input device (for example a smartphone) used to specify the to</code> address. </li> An ORACLE has signing capabilities. MUST be able to sign ATTESTATIONS off-chain in a way such that signatures can be verified on-chain. </li> </ul> Base Interface</h3> Every contract compliant to this standard MUST implement the the proposed standard interface</a>, ERC-721</a> and ERC-165</a> interfaces and is subject to Caveats</a> below: // SPDX-License-Identifier: MIT OR CC0-1.0 pragma solidity ^0.8.18; /** * @title IERC6956 Asset-Bound Non-Fungible Tokens * @notice Asset-bound Non-Fungible Tokens anchor a token 1:1 to a (physical or digital) asset and token transfers are authorized through attestation of control over the asset * @dev See https://eips.ethereum.org/EIPS/eip-6956 * Note: The ERC-165 identifier for this interface is 0xa9cf7635 */ interface IERC6956 { /** @dev Authorization, typically mapped to authorizationMaps, where each bit indicates whether a particular ERC6956Role is authorized * Typically used in constructor (hardcoded or params) to set burnAuthorization and approveAuthorization * Also used in optional updateBurnAuthorization, updateApproveAuthorization, I */ enum Authorization { NONE, // = 0, // None of the above OWNER, // = (1<<OWNER), // The owner of the token, i.e. the digital representation ISSUER, // = (1<<ISSUER), // The issuer of the tokens, i.e. this smart contract ASSET, // = (1<<ASSET), // The asset, i.e. via attestation OWNER_AND_ISSUER, // = (1<<OWNER) | (1<<ISSUER), OWNER_AND_ASSET, // = (1<<OWNER) | (1<<ASSET), ASSET_AND_ISSUER, // = (1<<ASSET) | (1<<ISSUER), ALL // = (1<<OWNER) | (1<<ISSUER) | (1<<ASSET) // Owner + Issuer + Asset } /** * @notice This emits when approved address for an anchored tokenId is changed or reaffirmed via attestation * @dev This emits when approveAnchor() is called and corresponds to ERC-721 behavior * @param owner The owner of the anchored tokenId * @param approved The approved address, address(0) indicates there is no approved address * @param anchor The anchor, for which approval has been changed * @param tokenId ID (>0) of the anchored token */ event AnchorApproval(address indexed owner, address approved, bytes32 indexed anchor, uint256 tokenId); /** * @notice This emits when the ownership of any anchored NFT changes by any mechanism * @dev This emits together with tokenId-based ERC-721.Transfer and provides an anchor-perspective on transfers * @param from The previous owner, address(0) indicate there was none. * @param to The new owner, address(0) indicates the token is burned * @param anchor The anchor which is bound to tokenId * @param tokenId ID (>0) of the anchored token */ event AnchorTransfer(address indexed from, address indexed to, bytes32 indexed anchor, uint256 tokenId); /** * @notice This emits when an attestation has been used indicating no second attestation with the same attestationHash will be accepted * @param to The to address specified in the attestation * @param anchor The anchor specified in the attestation * @param attestationHash The hash of the attestation, see ERC-6956 for details * @param totalUsedAttestationsForAnchor The total number of attestations already used for the particular anchor */ event AttestationUse(address indexed to, bytes32 indexed anchor, bytes32 indexed attestationHash, uint256 totalUsedAttestationsForAnchor); /** * @notice This emits when the trust-status of an oracle changes. * @dev Trusted oracles must explicitly be specified. * If the last event for a particular oracle-address indicates it's trusted, attestations from this oracle are valid. * @param oracle Address of the oracle signing attestations * @param trusted indicating whether this address is trusted (true). Use (false) to no longer trust from an oracle. */ event OracleUpdate(address indexed oracle, bool indexed trusted); /** * @notice Returns the 1:1 mapped anchor for a tokenId * @param tokenId ID (>0) of the anchored token * @return anchor The anchor bound to tokenId, 0x0 if tokenId does not represent an anchor */ function anchorByToken(uint256 tokenId) external view returns (bytes32 anchor); /** * @notice Returns the ID of the 1:1 mapped token of an anchor. * @param anchor The anchor (>0x0) * @return tokenId ID of the anchored token, 0 if no anchored token exists */ function tokenByAnchor(bytes32 anchor) external view returns (uint256 tokenId); /** * @notice The number of attestations already used to modify the state of an anchor or its bound tokens * @param anchor The anchor(>0) * @return attestationUses The number of attestation uses for a particular anchor, 0 if anchor is invalid. */ function attestationsUsedByAnchor(bytes32 anchor) view external returns (uint256 attestationUses); /** * @notice Decodes and returns to-address, anchor and the attestation hash, if the attestation is valid * @dev MUST throw when * - Attestation has already been used (an AttestationUse-Event with matching attestationHash was emitted) * - Attestation is not signed by trusted oracle (the last OracleUpdate-Event for the signer-address does not indicate trust) * - Attestation is not valid yet or expired * - [if IERC6956AttestationLimited is implemented] attestationUsagesLeft(attestation.anchor) <= 0 * - [if IERC6956ValidAnchors is implemented] validAnchors(data) does not return true. * @param attestation The attestation subject to the format specified in ERC-6956 * @param data Optional additional data, may contain proof as the first abi-encoded argument when IERC6956ValidAnchors is implemented * @return to Address where the ownership of an anchored token or approval shall be changed to * @return anchor The anchor (>0) * @return attestationHash The attestation hash computed on-chain as `keccak256(attestation)` */ function decodeAttestationIfValid(bytes memory attestation, bytes memory data) external view returns (address to, bytes32 anchor, bytes32 attestationHash); /** * @notice Indicates whether any of ASSET, OWNER, ISSUER is authorized to burn */ function burnAuthorization() external view returns(Authorization burnAuth); /** * @notice Indicates whether any of ASSET, OWNER, ISSUER is authorized to approve */ function approveAuthorization() external view returns(Authorization approveAuth); /** * @notice Corresponds to transferAnchor(bytes,bytes) without additional data * @param attestation Attestation, refer ERC-6956 for details */ function transferAnchor(bytes memory attestation) external; /** * @notice Changes the ownership of an NFT mapped to attestation.anchor to attestation.to address. * @dev Permissionless, i.e. anybody invoke and sign a transaction. The transfer is authorized through the oracle-signed attestation. * - Uses decodeAttestationIfValid() * - When using a centralized "gas-payer" recommended to implement IERC6956AttestationLimited. * - Matches the behavior of ERC-721.safeTransferFrom(ownerOf[tokenByAnchor(attestation.anchor)], attestation.to, tokenByAnchor(attestation.anchor), ..) and mint an NFT if `tokenByAnchor(anchor)==0`. * - Throws when attestation.to == ownerOf(tokenByAnchor(attestation.anchor)) * - Emits AnchorTransfer * * @param attestation Attestation, refer ERC-6956 for details * @param data Additional data, may be used for additional transfer-conditions, may be sent partly or in full in a call to safeTransferFrom * */ function transferAnchor(bytes memory attestation, bytes memory data) external; /** * @notice Corresponds to approveAnchor(bytes,bytes) without additional data * @param attestation Attestation, refer ERC-6956 for details */ function approveAnchor(bytes memory attestation) external; /** * @notice Approves attestation.to the token bound to attestation.anchor. . * @dev Permissionless, i.e. anybody invoke and sign a transaction. The transfer is authorized through the oracle-signed attestation. * - Uses decodeAttestationIfValid() * - When using a centralized "gas-payer" recommended to implement IERC6956AttestationLimited. * - Matches the behavior of ERC-721.approve(attestation.to, tokenByAnchor(attestation.anchor)). * - Throws when ASSET is not authorized to approve. * * @param attestation Attestation, refer ERC-6956 for details */ function approveAnchor(bytes memory attestation, bytes memory data) external; /** * @notice Corresponds to burnAnchor(bytes,bytes) without additional data * @param attestation Attestation, refer ERC-6956 for details */ function burnAnchor(bytes memory attestation) external; /** * @notice Burns the token mapped to attestation.anchor. Uses ERC-721._burn. * @dev Permissionless, i.e. anybody invoke and sign a transaction. The transfer is authorized through the oracle-signed attestation. * - Uses decodeAttestationIfValid() * - When using a centralized "gas-payer" recommended to implement IERC6956AttestationLimited. * - Throws when ASSET is not authorized to burn * * @param attestation Attestation, refer ERC-6956 for details */ function burnAnchor(bytes memory attestation, bytes memory data) external; }</code></pre>Caveats for Base Interface</h4> MUST implement ERC-721 and ERC-165 </li> MUST have bidirectional mapping tokenByAnchor(anchor)</code> and anchorByToken(tokenId)</code>. This implies that a maximum of one token per ANCHOR exists. </li> MUST have a mechanism to determine whether an ANCHOR is valid for the contract. RECOMMENDED to implement the proposed ValidAnchors-Interface</a> </li> MUST implement decodeAttestationIfValid(attestation, data)</code> to validate and decode ATTESTATIONS as specified in the ORACLE-Section</a> MUST return attestation.to</code>, attestation.anchor</code>, attestation.attestationHash</code>.</li> MUST not modify state, as this function can be used to check an ATTESTATION's validity without redeeming it.</li> MUST throw when ATTESTATION is not signed from a trusted ORACLE.</li> ATTESTATION has expired or is not valid yet</li> ATTESTATION has not been redeemed. "Redeemed" being defined in at least one state-changing operation has been authorized through a particular ATTESTATION.</li> If AttestationLimited-Interface</a> implemented: When attestationUsagesLeft(attestation.to) <= 0</code></li> If ValidAnchors-Interface</a> implemented: When validAnchor() != true</code>.</li> </ul> </li> If ValidAnchors-Interface</a> implemented: MUST call validAnchor(attestation.to, abi.decode('bytes32[]',data))</code>, meaning the first abi-encoded value in the data</code> parameter corresponds to proof</code>.</li> </ul> </li> MUST have a ANCHOR-RELEASED mechanism, indicating whether the anchored NFT is released/transferable. Any ANCHOR MUST NOT be released by default.</li> </ul> </li> MUST extend any ERC-721 token transfer mechanism by: MUST throw when ANCHOR</code> is not released.</li> MUST throw when batchSize > 1, namely no batch transfers are supported with this contract.</li> MUST emit AnchorTransfer(from, to, anchorByToken[tokenId], tokenId)</code></li> </ul> </li> MUST implement attestationsUsedByAnchor(anchor)</code>, returning how many attestations have already been used for a specific anchor. </li> MUST implement the state-changing transferAnchor(..)</code>, burnAnchor(..)</code>, approveAnchor(..)</code> and OPTIONAL MAY implement additional state-changing operations which MUST use the decodeAttestationIfValid()</code> to determine to</code>, anchor</code> and attestationHash</code></li> MUST redeem each ATTESTATION in the same transaction as any authorized state-changing operation. RECOMMENDED by storing each used attestationHash</code></li> MUST increment attestationsUsedByAnchor[anchor]</code></li> MUST emit AttestationUsed</code></li> transferAnchor(attestation)</code> MUST behave and emit events like ERC-721.safeTransferFrom(ownerOf[tokenByAnchor(attestation.anchor)], attestation.to, tokenByAnchor(attestation.anchor), ..)</code> and mint an NFT if tokenByAnchor(anchor)==0</code>.</li> </ul> </li> RECOMMENDED to implement tokenURI(tokenId)</code> to return an anchorBased-URI, namely baseURI/anchor</code>. This anchoring metadata to ASSET. Before an anchor is not used for the first time, the ANCHOR's mapping to tokenId is unknown. Hence, using the anchor in instead of the tokenId is preferred. </li> </ul> ORACLE</h3> MUST provide an ATTESTATION. Below we define the format how an ORACLE testifies that the to</code> address of a transfer has been specified under the pre-condition of PROOF-OF-CONTROL associated with the particular ANCHOR being transferred to to</code>.</li> The ATTESTATION MUST abi-encode the following: to</code>, MUST be address, specifying the beneficiary, for example the to-address, approved account etc.</li> ANCHOR, aka the ASSET identifier, MUST have a 1:1 relation to the ASSET</li> attestationTime</code>, UTC seconds, time when attestation was signed by ORACLE,</li> validStartTime</code> UTC seconds, start time of the ATTESTATION's validity timespan</li> validEndTime</code>, UTC seconds, end time of the ATTESTATION's validity timespan</li> signature</code>, ETH-signature (65 bytes). Output of an ORACLE signing the attestationHash = keccak256([to, anchor, attestationTime, validStartTime, validEndTime])</code>.</li> </ul> </li> How PROOF-OF-CONTROL is establish in detail through an ANCHOR-TECHNOLOGY is not subject to this standard. Some ORACLE requirements and ANCHOR-TECHNOLOGY requirements when using PHYSICAL ASSETS are outlined in Security considerations for Physical Assets</a>.</li> </ul> A Minimal Typescript sample to generate an ATTESTATION is available in the Reference Implementation section</a> of this proposal. AttestationLimited-Interface</h3> Every contract compliant to this standard MAY implement the proposed AttestationLimited interface</a> and is subject to Caveats</a> below: // SPDX-License-Identifier: MIT OR CC0-1.0 pragma solidity ^0.8.18; import "./IERC6956.sol"; /** * @title Attestation-limited Asset-Bound NFT * @dev See https://eips.ethereum.org/EIPS/eip-6956 * Note: The ERC-165 identifier for this interface is 0x75a2e933 */ interface IERC6956AttestationLimited is IERC6956 { enum AttestationLimitPolicy { IMMUTABLE, INCREASE_ONLY, DECREASE_ONLY, FLEXIBLE } /// @notice Returns the attestation limit for a particular anchor /// @dev MUST return the global attestation limit per default /// and override the global attestation limit in case an anchor-based limit is set function attestationLimit(bytes32 anchor) external view returns (uint256 limit); /// @notice Returns number of attestations left for a particular anchor /// @dev Is computed by comparing the attestationsUsedByAnchor(anchor) and the current attestation limit /// (current limited emitted via GlobalAttestationLimitUpdate or AttestationLimit events) function attestationUsagesLeft(bytes32 anchor) external view returns (uint256 nrTransfersLeft); /// @notice Indicates the policy, in which direction attestation limits can be updated (globally or per anchor) function attestationLimitPolicy() external view returns (AttestationLimitPolicy policy); /// @notice This emits when the global attestation limit is updated event GlobalAttestationLimitUpdate(uint256 indexed transferLimit, address updatedBy); /// @notice This emits when an anchor-specific attestation limit is updated event AttestationLimitUpdate(bytes32 indexed anchor, uint256 indexed tokenId, uint256 indexed transferLimit, address updatedBy); /// @dev This emits in the transaction, where attestationUsagesLeft becomes 0 event AttestationLimitReached(bytes32 indexed anchor, uint256 indexed tokenId, uint256 indexed transferLimit); }</code></pre>Caveats for AttestationLimited-Interface</h4> MUST extend the proposed standard interface</li> MUST define one of the above listed AttestationLimit update policies and expose it via attestationLimitPolicy()</code> MUST support different update modes, namely FIXED, INCREASE_ONLY, DECREASE_ONLY, FLEXIBLE (= INCREASABLE and DECREASABLE)</li> RECOMMENDED to have a global transfer limit, which can be overwritten on a token-basis (when attestationLimitPolicy() != FIXED</code>)</li> </ul> </li> MUST implement attestationLimit(anchor)</code>, specifying how often an ANCHOR can be transferred in total. Changes in the return value MUST reflect the AttestationLimit-Policy.</li> MUST implement attestationUsagesLeft(anchor)</code>, returning the number of usages left (namely attestationLimit(anchor)-attestationsUsedByAnchor[anchor]</code>) for a particular anchor</li> </ul> Floatable-Interface</h3> Every contract compliant to this extension MAY implement the proposed Floatable interface</a> and is subject to Caveats</a> below: // SPDX-License-Identifier: MIT OR CC0-1.0 pragma solidity ^0.8.18; import "./IERC6956.sol"; /** * @title Floatable Asset-Bound NFT * @notice A floatable Asset-Bound NFT can (temporarily) be transferred without attestation * @dev See https://eips.ethereum.org/EIPS/eip-6956 * Note: The ERC-165 identifier for this interface is 0xf82773f7 */ interface IERC6956Floatable is IERC6956 { enum FloatState { Default, // 0, inherits from floatAll Floating, // 1 Anchored // 2 } /// @notice Indicates that an anchor-specific floating state changed event FloatingStateChange(bytes32 indexed anchor, uint256 indexed tokenId, FloatState isFloating, address operator); /// @notice Emits when FloatingAuthorization is changed. event FloatingAuthorizationChange(Authorization startAuthorization, Authorization stopAuthorization, address maintainer); /// @notice Emits, when the default floating state is changed event FloatingAllStateChange(bool areFloating, address operator); /// @notice Indicates whether an anchored token is floating, namely can be transferred without attestation function floating(bytes32 anchor) external view returns (bool); /// @notice Indicates whether any of OWNER, ISSUER, (ASSET) is allowed to start floating function floatStartAuthorization() external view returns (Authorization canStartFloating); /// @notice Indicates whether any of OWNER, ISSUER, (ASSET) is allowed to stop floating function floatStopAuthorization() external view returns (Authorization canStartFloating); /** * @notice Allows to override or reset to floatAll-behavior per anchor * @dev Must throw when newState == Floating and floatStartAuthorization does not authorize msg.sender * @dev Must throw when newState == Anchored and floatStopAuthorization does not authorize msg.sender * @param anchor The anchor, whose anchored token shall override default behavior * @param newState Override-State. If set to Default, the anchor will behave like floatAll */ function float(bytes32 anchor, FloatState newState) external; }</code></pre>Caveats for Floatable-Interface</h4> If floating(anchor)</code> returns true, the token identified by tokenByAnchor(anchor)</code> MUST be transferable without attestation, typically authorized via ERC721.isApprovedOrOwner(msg.sender, tokenId)</code> ValidAnchors-Interface</h3> Every contract compliant to this extension MAY implement the proposed ValidAnchors interface</a> and is subject to Caveats</a> below: // SPDX-License-Identifier: MIT OR CC0-1.0 pragma solidity ^0.8.18; import "./IERC6956.sol"; /** * @title Anchor-validating Asset-Bound NFT * @dev See https://eips.ethereum.org/EIPS/eip-6956 * Note: The ERC-165 identifier for this interface is 0x051c9bd8 */ interface IERC6956ValidAnchors is IERC6956 { /** * @notice Emits when the valid anchors for the contract are updated. * @param validAnchorHash Hash representing all valid anchors. Typically Root of Merkle-Tree * @param maintainer msg.sender when updating the hash */ event ValidAnchorsUpdate(bytes32 indexed validAnchorHash, address indexed maintainer); /** * @notice Indicates whether an anchor is valid in the present contract * @dev Typically implemented via MerkleTrees, where proof is used to verify anchor is part of the MerkleTree * MUST return false when no ValidAnchorsUpdate-event has been emitted yet * @param anchor The anchor in question * @param proof Proof that the anchor is valid, typically MerkleProof * @return isValid True, when anchor and proof can be verified against validAnchorHash (emitted via ValidAnchorsUpdate-event) / function anchorValid(bytes32 anchor, bytes32[] memory proof) external view returns (bool isValid); }</code></pre>Caveats for ValidAnchors-Interface</h4> MUST implement validAnchor(anchor, proof)</code> which returns true when anchor is valid, namely MerkleProof is correct, false otherwise.</li> </ul> Rationale</h2> Why do you use an anchor<>tokenId mapping and not simply use tokenIds directly? Especially for collectable use-cases, special or sequential tokenIds (for example low numbers), have value. Holders may be proud to have claimed tokenId=1 respectively the off-chain ASSET with tokenId=1 may increase in value, because it was the first ever claimed. Or an Issuer may want to address the first 100 owners who claimed their ASSET-BOUND NFT. While these use-cases technically can certainly be covered by observing the blockchain state-changes, we consider reflecting the order in the tokenIds to be the user-friendly way. Please refer Security considerations</a> on why sequential anchors shall be avoided. Why is tokenId=0 and anchor=0x0 invalid? For gas efficiency. This allows to omit checks and state-variables for the existence of a token or anchor, since mappings of a non-existent key return 0 and cannot be easily distinguished from anchor=0 or tokenId=0. ASSETS are often batch-produced with the goal of identical properties, for example a batch of automotive spare parts. Why should do you extend ERC-721 and not Multi-Token standards? Even if a (physical) ASSET is mass produced with fungible characteristics, each ASSET has an individual property/ownership graph and thus shall be represented in a non-fungible way. Hence this EIP follows the design decision that ASSET (represented via a unique asset identifier called ANCHOR) and token are always mapped 1-1 and not 1-N, so that a token represents the individual property graph of the ASSET. Why is there a burnAnchor() and approveAnchor()? Due to the permissionless nature ASSET-BOUND NFTs can even be transferred to or from any address. This includes arbitrary and randomly generated accounts (where the private key is unknown) and smart-contracts which would traditionally not support ERC-721 NFTs. Following that owning the ASSET must be equivalent to owning the NFT, this means that we also need to support ERC-721 operations like approval and burning in such instances through authorizing the operations with an attestation. Implementation alternatives considered Soulbound burn+mint combination, for example through Consensual Soulbound Tokens (ERC-5484</a>). Disregarded because appearance is highly dubious, when the same asset is represented through multiple tokens over time. An predecessor of this EIP has used this approach and can be found deployed to Mumbai Testnet under address 0xd04c443913f9ddcfea72c38fed2d128a3ecd719e</code>. When should I implement AttestationLimited-Interface Naturally, when your use-case requires each ASSET being transferable only a limited number of times. But also for security reasons, see Security Considerations</a> Why is there the IERC6956Floatable.FloatState</code> enum? In order to allow gas-efficient implementation of floatAll(), which can be overruled by anchor-based floatability in all combinations. (See rationale for tokenId=0 above). Why is there no floating(tokenId)</code> function? This would behave identically to an isTransferable(tokenId,...)</code> mechanism proposed in many other EIPs (refer e.g. ERC-6454</a>). Further, the proposed floating(anchorByToken(tokenId))</code> can be used. Why are there different FloatingAuthorizations for start and stop? Depending on the use-case, different roles should be able to start or stop floating. Note that for many applications the ISSUER may want to have control over the floatability of the collection. Example Use Cases and recommended combination of interfaces</h3> Possession based use cases are covered by the standard interface IERC6956</code>: The holder of ASSET is in possession of ASSET. Possession is an important social and economical tool: In many sports games possession of ASSET, commonly referred to as "the ball", is of essence. Possession can come with certain obligations and privileges. Ownership over an ASSET can come with rights and benefits as well as being burdened with liens and obligations. For example, an owned ASSET can be used for collateral, can be rented or can even yield a return. Example use-cases are Possession based token gating: Club guest in possession of limited T-Shirt (ASSET) gets a token which allows him to open the door to the VIP lounge. </li> Possession based digital twin: A gamer is in possession of a pair of physical sneakers (ASSET), and gets a digital twin (NFT) to wear them in metaverse. </li> Scarce possession based digital twin: The producer of the sneakers (ASSET) decided that the product includes a limit of 5 digital twins (NFTs), to create scarcity. </li> Lendable digital twin: The gamer can lend his sneaker-tokens (NFT) to a friend in the metaverse, so that the friend can run faster. </li> Securing ownership from theft: If ASSET is owned off-chain, the owner wants to secure the anchored NFT, namely not allow transfers to prevent theft or recover the NFT easily through the ASSET. </li> Selling a house with a mortgage: The owner holds NFT as proof of ownership. The DeFi-Bank finances the house and puts a lock on the transfer of NFT. Allow Transfers of the NFT require the mortgage to be paid off. Selling the ASSET (house) off-chain will be impossible, as it's no longer possible to finance the house. </li> Selling a house with a lease: A lease contract puts a lien on an ASSET's anchored NFT. The old owner removes the lock, the new owner buys and refinances the house. Transfer of NFT will also transfer the obligations and benefits of the lien to the new owner. </li> Buying a brand new car with downpayment: A buyer configures a car and provides a downpayment, for a car that will have an ANCHOR. As long as the car is not produced, the NFT can float and be traded on NFT market places. The owner of the NFT at time of delivery of the ASSET has the permission to pick up the car and the obligation to pay full price. </li> Buying a barrel of oil by forward transaction: A buyer buys an oil option on a forward contract for one barrel of oil (ASSET). On maturity date the buyer has the obligation to pick up the oil. </li> </ul> The use case matrix below shows which extensions and settings must (additionally to IERC6956</code>!) be implemented for the example use-cases together with relevant configurations. Note that for Lockable</code> listed in the table below, the proposed EIP can be extended with any Lock- or Lien-Mechanism known to extend for ERC-721, for example ERC-5192</a> or ERC-6982</a>. We recommend to verify whether a token is locked in the _beforeTokenTransfer()</code>-hook, as this is called from safeTransferFrom()</code> as well as transferAnchor()</code>, hence suitable to block "standard" ERC-721 transfers as well as the proposed attestation-based transfers. Use Case</th> approveAuthorization</th> burnAuthorization</th> IERC6956Floatable</code></th> IERC6956AttestationLimited</code></th> Lockable</th></tr></thead> Managing Possession</td> </td> </td> </td> </td> </td></tr> Token gating</td> ASSET</td> ANY</td> incompatible</td> -</td> -</td></tr> Digital twin</td> ASSET</td> ANY</td> incompatible</td> -</td> -</td></tr> Scarce digital twin</td> ASSET</td> ANY</td> incompatible</td> required</td> -</td></tr> Lendable digital twin</td> OWNER_AND_ASSET</td> ASSET</td> required</td> -</td> -</td></tr> Managing Ownership</td> </td> </td> </td> </td> </td></tr> Securing ownership from theft</td> OWNER or OWNER_AND_ASSET</td> ANY</td> optional</td> -</td> required</td></tr> Selling an house with a mortgage</td> ASSET or OWNER_AND_ASSET</td> ANY</td> optional</td> optional</td> required</td></tr> Selling a house with a lease</td> ASSET or OWNER_AND_ASSET</td> ANY</td> optional</td> optional</td> required</td></tr> Buying a brand new car with downpayment</td> ASSET or OWNER_AND_ASSET</td> ANY</td> optional</td> optional</td> required</td></tr> Buying a barrel of oil by forward transaction</td> ASSET or OWNER_AND_ASSET</td> ANY</td> optional</td> optional</td> required</td></tr> </tbody></table> Legend: required ... we don't see a way how to implement the use-case without it</li> incompatible ... this MUSTN'T be implemented, as it is a security risk for the use-case</li> optional ... this MAY optionally be implemented</li> </ul> Backwards Compatibility</h2> No backward compatibility issues found. This EIP is fully compatible with ERC-721 and (when extended with the IERC6956Floatable</code>-interface) corresponds to the well-known ERC-721 behavior with an additional authorization-mechanism via attestations. Therefore we recommend - especially for physical assets - to use the present EIP instead of ERC-721 and amend it with extensions designed for ERC-721. However, it is RECOMMENDED to extend implementations of the proposed standard with an interface indicating transferability of NFTs for market places. Examples include ERC-6454</a> and ERC-5484</a>. Many ERC-721 extensions suggest to add additional throw-conditions to transfer methods. This standard is fully compatible, as The often-used ERC-721 _beforeTokenTransfer()</code> hook must be called for all transfers including attestation-authorized transfers.</li> A _beforeAnchorUse()</code> hook is suggested in the reference implementation, which only is called when using attestation as authorization.</li> </ul> Test Cases</h2> Test cases are available: For only implementing the proposed standard interface</a> can be found here</a></li> For implementing the proposed standard interface</a>, the Floatable extension</a>, the ValidAnchors extension</a> and the AttestationLimited extension</a> can be found here</a></li> </ul> Reference Implementation</h2> Minimal implementation, only supporting the proposed standard interface</a> can be found here</a></li> Full implementation, with support for the proposed standard interface</a>, the Floatable extension</a>, the ValidAnchors extension</a> and the AttestationLimited extension</a> can be found here</a></li> A Minimal Typescript sample to generate an ATTESTATION using ethers library is available here</a></li> </ul> Security Considerations</h2> If the asset is stolen, does this mean the thief has control over the NFT? Yes.The standard aims to anchor an NFT to the asset inseperably and unconditionally. This includes reflecting theft, as the ORACLE will testify that PROOF-OF-CONTROL over the ASSET is established. The ORACLE does not testify whether the controller is the legitimate owner, Note that this may even be a benefit. If the thief (or somebody receiving the asset from the thief) should interact with the anchor, an on-chain address of somebody connected to the crime (directly or another victim) becomes known. This can be a valuable starting point for investigation. Also note that the proposed standard can be combined with any lock-mechanism, which could lock attestation-based action temporarily or permanently (after mint). How to use AttestationLimits to avoid fund-draining A central security mechanism in blockchain applications are gas fees. Gas fees ensure that executing a high number of transactions get penalized, hence all DoS or other large-scale attacks are discouraged. Due to the permissionless nature of attestation-authorized operations, many use-cases will arise, where the issuer of the ASSET (which normally is also the issuer of the ASSET-BOUND NFT) will pay for all transactions - contrary to the well-known ERC-721 behavior, where either from- or to-address are paying. So a user with malicious intent may just let the ORACLE approve PROOF-OF-CONTROL multiple times with specifying alternating account addresses. These ATTESTATIONS will be handed to the central gas-payer, who will execute them in a permissionless way, paying gas-fees for each transactions. This effectively drains the funds from the gas-payer, making the system unusable as soon as the gas-payer can no longer pay for transactions. Why do you recommend hashing serial numbers over using them plain? Using any sequential identifier allows to at least conclude of the number between the lowest and highest ever used serial number. This therefore provides good indication over the total number of assets on the market. While a limited number of assets is often desirable for collectables, publishing exact production numbers of assets is undesirable for most industries, as it equals to publishing sales/revenue numbers per product group, which is often considered confidential. Within supply chains, serial numbers are often mandatory due to their range-based processing capability. The simplest approach to allow using physical serial numbers and still obfuscating the actual number of assets is through hashing/encryption of the serial number. Why is anchor-validation needed, why not simply trust the oracle to attest only valid anchors? The oracle testifies PROOF-OF-CONTROL. As the ORACLE has to know the merkle-tree of valid anchors, it could also modify the merkle-tree with malicious intent. Therefore, having an on-chain verification, whether the original merkle-tree has been used, is needed. Even if the oracle gets compromised, it should not have the power to introduce new anchors. This is achieved by requiring that the oracle knows the merkle-tree, but updateValidAnchors() can only be called by a maintainer. Note that the oracle must not be the maintainer. As a consequence, care shall be taken off-chain, in order to ensure that compromising one system-part not automatically compromises oracle and maintainer accounts. Why do you use merkle-trees for anchor-validation? For security- and gas-reasons. Except for limited collections, anchors will typically be added over time, e.g. when a new batch of the asset is produced or issued. While it is already ineffective to store all available anchors on-chain gas-wise, publishing all anchors would also expose the total number of assets. When using the data from anchor-updates one could even deduce the production capabilities of that asset, which is usually considered confidential information. Assume you have N anchors. If all anchored NFTs are minted, what use is a merkle-tree? If all anchored NFTs are minted this implies that all anchors have been published and could be gathered on-chain. Consequently, the merkle-tree can be reconstructed. While this may not be an issue for many use cases (all supported anchors are minted anyway), we still recommend to add one "salt-leave" to the merkle-tree, characterized in that the ORACLE will never issue an attestation for an ANCHOR matching that salt-leave. Therefore, even if all N anchors are Security Considerations for PHYSICAL ASSETS</h3> In case the ASSET is a physical object, good or property, the following ADDITIONAL specifications MUST be satisfied: ORACLE for Physical Anchors</h4> Issuing an ATTESTATION requires that the ORACLE MUST proof physical proximity between an input device (for example smartphone) specifying the to</code> address and a particular physical ANCHOR and it's associated physical object. Typical acceptable proximity is ranges between some millimeters to several meters.</li> The physical presence MUST be verified beyond reasonable doubt, in particular the employed method MUST be robust against duplication or reproduction attempts of the physical ANCHOR,</li> MUST be robust against spoofing (for example presentation attacks) etc.</li> </ul> </li> MUST be implemented under the assumption that the party defining the to</code> address has malicious intent and to acquire false ATTESTATION, without currently or ever having access to the physical object comprising the physical ANCHOR.</li> </ul> </li> </ul> Physical ASSET</h4> MUST comprise an ANCHOR, acting as the unique physical object identifier, typically a serial number (plain (NOT RECOMMENDED) or hashed (RECOMMENDED))</li> MUST comprise a physical security device, marking or any other feature that enables proofing physical presence for ATTESTATION through the ORACLE</li> Is RECOMMENDED to employ ANCHOR-TECHNOLOGIES featuring irreproducible security features.</li> In general it is NOT RECOMMENDED to employ ANCHOR-TECHNOLOGIES that can easily be replicated (for example barcodes, "ordinary" NFC chips, .. ). Replication includes physical and digital replication.</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>. L2 Token List 2023-03-20T00:00:00+00:00 Abstract</h2> The document describes a JSON token list that ensures that two or more Layer 1, Layer 2, or Sidechains can identify tokens from a different Layer 1, Layer 2, or Sidechain. Motivation</h2> This particular work by the L2 WG of the EEA Communities Projects managed by OASIS, an open-source initiative, is motivated by a significant challenge around the definition and listing of tokens on Layer 1 (L1), Layer 2 (L2), and Sidechain systems. Note that for simplicity, this document we will collectively refer to L1, L2 and Sidechain systems as chains below since the challenge described below is valid across all such systems: Consensus on the "canonical" token on chain B that corresponds to some token on chain A. When one wants to bridge token X from chain A to chain B, one must create some new representation of the token on chain B. It is worth noting that this problem is not limited to L2s -- every chain connected via bridges must deal with the same issue.</li> </ul> Related to the above challenge is the standardization around lists of bridges and their routes across different chains. This will be addressed in a separate document. Note that both of these issues are fundamental problems for the current multi-chain world. Therefore, the goal of this document is to help token users to operationalize and disambiguate the usage of a token in their systems. For lists of canonical tokens, L2s currently maintain their own customized versions of the Uniswap token list. For example, Arbitrum maintains a token list with various custom extensions. Optimism also maintains a custom token list, but with different extensions. It should be noted that both of these custom extensions refer to the bridge that these tokens can be carried through. However, these are not the only bridges that the tokens can be carried through, which means that bridges and token lists should be separated. Also note that currently, both Optimism and Arbitrum base "canonicity" on the token name + symbol pair. An example of an Arbitrum token entry is given below: { logoURI: "https://assets.coingecko.com/coins/images/13469/thumb/1inch-token.png?1608803028", chainId: 42161, address: "0x6314C31A7a1652cE482cffe247E9CB7c3f4BB9aF", name: "1INCH Token", symbol: "1INCH", decimals: 18, extensions: { bridgeInfo: { 1: { tokenAddress: "0x111111111117dc0aa78b770fa6a738034120c302", originBridgeAddress: "0x09e9222e96e7b4ae2a407b98d48e330053351eee", destBridgeAddress: "0xa3A7B6F88361F48403514059F1F16C8E78d60EeC" } } } }</code></pre> This standard will build upon the current framework and augment it with concepts from Decentralized Identifiers (DIDs)</a> based on the JSON linked data model JSON-LD</a> such as resolvable unique resource identifiers (URIs) and JSON-LD schemas which enable easier schema verification using existing tools. Note that a standard for defining tokens is beyond the scope of this document. Specification</h2> Keywords:</h3> 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 [RFC2119</a>] when, and only when, they appear in all capitals, as shown here. Typographical Convention: Requirement Ids</h3> A requirement is uniquely identified by a unique ID composed of its requirement level followed by a requirement number, as per convention [RequirementLevelRequirementNumber]. There are four requirement levels that are coded in requirement ids as per below convention: [R] - The requirement level for requirements which IDs start with the letter R is to be interpreted as MUST as described in RFC2119</a>. [D] - The requirement level for requirements which IDs start with the letter D is to be interpreted as SHOULD as described in RFC2119</a>. [O] - The requirement level for requirements which IDs start with the letter O is to be interpreted as MAY as described in RFC2119</a>. Note that requirements are uniquely numbered in ascending order within each requirement level. Example : It should be read that [R1] is an absolute requirement of the specification whereas [D1] is a recommendation and [O1] is truly optional. [R1] </a> The following data elements MUST be present in a canonical token list: type</li> tokenListId</li> name</li> createdAt</li> updatedAt</li> versions</li> tokens</li> </ul> Note, that the detailed definition of the data elements in [R1]</a> along with descriptions and examples are given in the schema itself below. [R1]</a> testability: See suggested test fixtures for the data schema below. [R2] </a> The tokens data element is a composite which MUST minimally contain the following data elements: chainId</li> chainURI</li> tokenId</li> tokenType</li> address</li> name</li> symbol</li> decimals</li> createdAt</li> updatedAt</li> </ul> Note, that the detailed definition of the data elements in [R2]</a> along with descriptions and examples are given in the schema itself below. [R2]</a> testability: See suggested test fixtures for this documents' data schema below. [D1] </a> All other data elements of the schema SHOULD be included in a representation of a canonical token list. [D1]</a> testability: See suggested test fixtures for this documents' data schema below. [CR1]>[D1] </a> If the extension data elements is used, the following data elements MUST be present in the schema representation: rootChainId</li> rootChainURI</li> rootAddress</li> </ul> Note, that the detailed definition of the data elements in [D1]</a> and [CR1]>[D1]</a> along with descriptions and examples are given in the schema itself below. [CR1]>[D1]</a> testability: See suggested test fixtures for this documents' data schema below. [R3] </a> All properties in the schema identified in the description to be a Universal Resource Identifier (URI) MUST follow in their semantics RFC 3986</a>. [R3]</a> testability: All requirements for RFC 3986</a> are testable. [R4] </a> The chainId property utilized MUST allow for the requirements of the EIP-155</a> standard to be met. Namely, transaction replay protection on the network that is identified by the chainId property value. Note, that for replay protection to be guaranteed, the chainId should be unique. Ensuring a unique chainId is beyond the scope of this document. [R4]</a> testability: EIP-155 requires that a transaction hash is derived from the keccak256 hash of the following nine RLP encoded elements (nonce, gasprice, startgas, to, value, data, chainid, 0, 0)</code> which can be tested easily with existing cryptographic libraries. EIP-155 further requires that the v</code> value of the secp256k1 signature must be set to {0,1} + CHAIN_ID 2 + 35</code> where {0,1}</code> is the parity of the y</code> value of the curve point for which the signature r</code>-value is the x</code>-value in the secp256k1 signing process. This requirement is testable with available open-source secp256k1 digital signature suites. Therefore, [R4]</a> is testable. [O1] </a> The humanReadableTokenSymbol</code> property MAY be used. [O1]</a> testability: A data property is always implementable in a schema. [CR2]>[O1] </a> The humanReadableTokenSymbol</code> property MUST be constructed as the hyphenated concatenation of first the tokenSymbol</code> and then the chainId</code>. An example would be: "tokenSymbol" = ETH; "chainId" = 1; "humanReadableTokenSymbol" = ETH-1;</code></pre> [CR2]>[O1]</a> testability: humanReadableTokenSymbol</code> can be parsed and split based on existing open source packages and the result compared to the tokenSymbol</code> and chainId</code> used in the data schema. The schema for a canonical token list is given below as follows and can be utilized as a JSON-LD schema if a JSON-LD context file is utilized (see [W3C-DID]</a> for a concrete example in the context of a standard): { "$id": "https://github.com/eea-oasis/l2/schemas/CanonicalTokenList.json", "$schema": "https://json-schema.org/draft-07/schema#", "$comment": "{\"term\": \"CanonicalTokenList\", \"@id\": \"https://github.com/eea-oasis/l2#CanonicalTokenList\"}", "title": "CanonicalTokenList", "description": "Canonical Token List", "type": "object", "required": [ "type", "tokenListId", "name", "createdAt", "updatedAt", "versions", "tokens" ], "properties": { "@context": { "type": "array" }, "type": { "oneOf": [ { "type": "string" }, { "type": "array" } ], "examples": ["CanonicalTokenList"] }, "tokenListId": { "$comment": "{\"term\": \"tokenListId\", \"@id\": \"https://schema.org/identifier\"}", "title": "tokenListId", "description": "A resolvable URI to the publicly accessible place where this list can be found following the RFC 3986 standard.", "type": "string", "examples": ["https://ipfs.io/ipns/k51qzi5uqu5dkkciu33khkzbcmxtyhn376i1e83tya8kuy7z9euedzyr5nhoew"] }, "name": { "$comment": "{\"term\": \"name\", \"@id\": \"https://schema.org/name\"}", "title": "name", "description": "Token List name", "type": "string", "examples": ["Aggregate Canonical Token List"] }, "logoURI": { "$comment": "{\"term\": \"logoURI\", \"@id\": \"https://schema.org/identifier\"}", "title": "logoURI", "description": "URI or URL of the token list logo following the RFC 3986 standard", "type": "string", "examples": ["https://ipfs.io/ipns/k51qzi5uqu5dh5kbbff1ucw3ksphpy3vxx4en4dbtfh90pvw4mzd8nfm5r5fnl"] }, "keywords": { "$comment": "{\"term\": \"keywords\", \"@id\": \"https://schema.org/DefinedTerm\"}", "title": "keywords", "description": "List of key words for the token list", "type": "array", "examples": [Aggregate Token List] }, "createdAt": { "$comment": "{\"term\": \"createdAt\", \"@id\": \"https://schema.org/datePublished\"}", "title": "createdAt", "description": "Date and time token list was created", "type": "string", "examples": ["2022-05-08"] }, "updatedAt": { "$comment": "{\"term\": \"updatedAt\", \"@id\": \"https://schema.org/dateModified\"}", "title": "updatedAt", "description": "Date and time token list was updated", "type": "string", "examples": ["2022-05-09"] }, "versions": { "$comment": "{\"term\": \"versions\", \"@id\": \"https://schema.org/version\"}", "title": "versions", "description": "Versions of the canonical token list", "type": "array", "items": { "type":"object", "required":[ "major", "minor", "patch" ], "properties": { "major": { "$comment": "{\"term\": \"major\", \"@id\": \"https://schema.org/Number\"}", "title": "major", "description": "Major Version Number of the Token List", "type": "integer", "examples": [1] }, "minor": { "$comment": "{\"term\": \"minor\", \"@id\": \"https://schema.org/Number\"}", "title": "minor", "description": "Minor Version Number of the Token List", "type": "integer", "examples": [1] }, "patch": { "$comment": "{\"term\": \"patch\", \"@id\": \"https://schema.org/Number\"}", "title": "patch", "description": "Patch Number of the Token List", "type": "integer", "examples": [1] }, } } }, "tokens": { "title": "Listed Token Entry", "description": "Listed Token Entry", "type": "array", "items": { "type":"object", "required": [ "chainId", "chainURI", "tokenId", "tokenType", "address", "name", "symbol", "decimals", "createdAt", "updatedAt" ], "properties": { "chainId": { "$comment": "{\"term\": \"chainId\", \"@id\": \"https://schema.org/identifier\"}", "title": "chainId", "description": "The typically used number identifier for the chain on which the token was issued.", "type": "number", "examples": [137] }, "chainURI": { "$comment": "{\"term\": \"chainURI\", \"@id\": \"https://schema.org/identifier\"}", "title": "chainURI", "description": "A resolvable URI to the genesis block of the chain on which the token was issued following the RFC 3986 standard.", "type": "string" "examples": ["https://polygonscan.com/block/0"] }, "genesisBlockHash": { "$comment": "{\"term\": \"genesisBlockHash\", \"@id\": \"https://schema.org/sha256\"}", "title": "genesisBlockHash", "description": "The hash of the genesis block of the chain on which the token was issued.", "type": "string", "examples": ["0xa9c28ce2141b56c474f1dc504bee9b01eb1bd7d1a507580d5519d4437a97de1b"] }, "tokenIssuerId": { "$comment": "{\"term\": \"tokenIssuerId\", \"@id\": \"https://schema.org/identifier\"}", "title": "tokenIssuerId", "description": "A resolvable URI identifying the token issuer following the RFC 3986 standard.", "type": "string", "examples": ["https://polygonscan.com/address/0xa9c28ce2141b56c474f1dc504bee9b01eb1bd7d1a507580d5519d4437a97de1b"] }, "tokenIssuerName": { "$comment": "{\"term\": \"tokenIssuerName\", \"@id\": \"https://schema.org/name\"}", "title": "tokenIssuerName", "description": "The name oof the token issuer.", "type": "string" "examples": ["Matic"] }, "tokenId": { "$comment": "{\"term\": \"tokenId\", \"@id\": \"https://schema.org/identifier\"}", "title": "tokenId", "description": "A resolvable URI of the token following the RFC 3986 standard to for example the deployment transaction of the token, or a DID identifying the token and its issuer.", "type": "string", "example": ["https://polygonscan.com/address/0x0000000000000000000000000000000000001010"] }, "tokenType": { "$comment": "{\"term\": \"tokenType\", \"@id\": \https://schema.org/StructuredValue\"}", "title": "tokenType", "description": "Describes the type of token.", "type": "array" "examples"[["fungible","transferable"]] }, "tokenDesc": { "$comment": "{\"term\": \"tokenDesc\", \"@id\": \"https://schema.org/description\"}", "title": "tokenDesc", "description": "Brief description of the token and its functionality.", "type": "string", "examples": ["Protocol Token for the Matic Network"] }, "standard": { "$comment": "{\"term\": \"standard\", \"@id\": \"https://schema.org/citation\"}", "title": "standard", "description": "A resolvable URI to the description of the token standard.", "type": "string", "examples": ["https://github.com/ethereum/EIPs/blob/master/EIPS/./00020.md"] }, "address": { "$comment": "{\"term\": \"address\", \"@id\": \"https://schema.org/identifier\"}", "title": "address", "description": "Address of the token smart contract.", "type": "string", "examples": ["0x0000000000000000000000000000000000001010"] }, "addressType": { "$comment": "{\"term\": \"address\", \"@id\": \"https://schema.org/Intangible\"}", "title": "addressType", "description": "AddressType of the token smart contract.", "type": "string", "examples": ["MaticNameSpace"] }, "addressAlg": { "$comment": "{\"term\": \"addressAlg\", \"@id\": \"https://schema.org/algorithm\"}", "title": "addressAlg", "description": "Algorithm used to create the address e.g. CREATE2 or the standard ethereum address construction which is the last 40 characters/20 bytes of the Keccak-256 hash of a secp256k1 public key.", "type": "string", "examples": ["CREATE2"] }, "name": { "$comment": "{\"term\": \"name\", \"@id\": \"https://schema.org/name\"}", "title": "name", "description": "Token name.", "type": "string", "examples": ["Matic"] }, "symbol": { "$comment": "{\"term\": \"symbol\", \"@id\": \"https://schema.org/currency\"}", "title": "symbol", "description": "Token symbol e.g. ETH.", "type": "string", "examples": ["MATIC"] }, "humanReadableTokenSymbol": { "$comment": "{\"term\": \"humanReadableTokenSymbol\", \"@id\": \"https://schema.org/currency\"}", "title": "humanReadableTokenSymbol", "description": "A Token symbol e.g. ETH, concatenated with the `chainId` the token was issued on or bridged to, e.g. ETH-1", "type": "string", "examples": ["MATIC-137"] }, "decimals": { "$comment": "{\"term\": \"decimals\", \"@id\": \"https://schema.org/Number\"}", "title": "decimals", "description": "Allowed number of decimals for the listed token. This property may be named differently by token standards e.g. granularity for ERC-777", "type": "integer", "examples": [18] }, "logoURI": { "$comment": "{\"term\": \"logoURI\", \"@id\": \"https://schema.org/identifier\"}", "title": "logoURI", "description": "URI or URL of the token logo following the RFC 3986 standard.", "type": "string" "examples": ["https://polygonscan.com/token/images/matic_32.png"] }, "createdAt": { "$comment": "{\"term\": \"createdAt\", \"@id\": \"https://schema.org/datePublished\"}", "title": "createdAt", "description": "Date and time token was created", "type": "string", "examples": ["2020-05-31"] }, "updatedAt": { "$comment": "{\"term\": \"updatedAt\", \"@id\": \"https://schema.org/dateModified\"}", "title": "updatedAt", "description": "Date and time token was updated", "type": "string" "examples": ["2020-05-31"] }, "extensions": { "title": "extensions", "description": "Extension to the token list entry to specify an origin chain if the token entry refers to another chain other than the origin chain of the token", "type": "array", "items": { "type":"object", "required": [ "rootChainId", "rootChainURI", "rootAddress", ], "properties": { "rootChainId": { "$comment": "{\"term\": \"rootChainId\", \"@id\": \"https://schema.org/identifier\"}", "title": "rootChainId", "description": "The typically used number identifier for the root chain on which the token was originally issued.", "type": "number", "examples": [137] }, "rootChainURI": { "$comment": "{\"term\": \"rootChainURI\", \"@id\": \"https://schema.org/identifier\"}", "title": "rootChainURI", "description": "A resolvable URI to the genesis block of the root chain on which the token was originally issued following the RFC 3986 standard.", "type": "string", "examples": ["https://polygonscan.com/block/0"] }, "rootAddress": { "$comment": "{\"term\": \"rootAddress\", \"@id\": \"https://schema.org/identifier\"}", "title": "rootAddress", "description": "Root address of the token smart contract.", "type": "string", "examples": ["0x0000000000000000000000000000000000001010"] } } } } } } } }, "additionalProperties": false, }</code></pre> Data Schema Testability: As the above data schema follows a JSON/JSON-LD schema format, and since such formats are known to be testable for schema conformance (see for example the W3C CCG Traceability Work Item), the above data schema is testable. Conformance</h3> This section describes the conformance clauses and tests required to achieve an implementation that is provably conformant with the requirements in this document. Conformance Targets</h4> This document does not yet define a standardized set of test-fixtures with test inputs for all MUST, SHOULD, and MAY requirements with conditional MUST or SHOULD requirements. A standardized set of test-fixtures with test inputs for all MUST, SHOULD, and MAY requirements with conditional MUST or SHOULD requirements is intended to be published with the next version of the standard. Conformance Levels</h4> This section specifies the conformance levels of this standard. The conformance levels offer implementers several levels of conformance. These can be used to establish competitive differentiation. This document defines the conformance levels of a canonical token list as follows: Level 1: All MUST requirements are fulfilled by a specific implementation as proven by a test report that proves in an easily understandable manner the implementation's conformance with each requirement based on implementation-specific test-fixtures with implementation-specific test-fixture inputs.</li> Level 2: All MUST and SHOULD requirements are fulfilled by a specific implementation as proven by a test report that proves in an easily understandable manner the implementation's conformance with each requirement based on implementation-specific test-fixtures with implementation-specific test-fixture inputs.</li> Level 3: All MUST, SHOULD, and MAY requirements with conditional MUST or SHOULD requirements are fulfilled by a specific implementation as proven by a test report that proves in an easily understandable manner the implementation's conformance with each requirement based on implementation-specific test-fixtures with implementation-specific test-fixture inputs.</li> </ul> [D2] </a> A claim that a canonical token list implementation conforms to this specification SHOULD describe a testing procedure carried out for each requirement to which conformance is claimed, that justifies the claim with respect to that requirement. [D2]</a> testability: Since each of the non-conformance-target requirements in this documents is testable, so must be the totality of the requirements in this document. Therefore, conformance tests for all requirements can exist, and can be described as required in [D2]</a>. [R5] </a> A claim that a canonical token list implementation conforms to this specification at Level 2 or higher MUST describe the testing procedure carried out for each requirement at Level 2 or higher, that justifies the claim to that requirement. [R5]</a> testability: Since each of the non-conformance-target requirements in this documents is testable, so must be the totality of the requirements in this document. Therefore, conformance tests for all requirements can exist, be described, be built and implemented and results can be recorded as required in [R5]</a>. Rationale</h2> This specification is extending and clarifying current custom lists such as from Arbitrum and Optimism as referenced in the Motivation</a> or the Uniswap Tokenlist Project to improve clarity, security and encourage adoption by non-Web3 native entities. The specification is utilizing the current JSON-LD standard to describe a token list to allow for easy integrations with Self-Sovereign-Identity frameworks such as W3C DID and W3C Verifiable Credential standards that allow for interoperability across L2s, Sidechains and L1s when identifying token list relevant entities such as Token Issuers. In addition, being compatible to W3C utilized frameworks allows implementers to use existing tooling around JSON-LD, W3C DIDs and W3C Verifiable Credentials. The choice of referencing known data property definitions from schema.org further disambiguates the meaning and usage of terms. Security Considerations</h2> There are no additional security requirements apart from the warnings that URIs utilized in implementations of this standard might be direct to malicious resources such as websites, and that implementers should ensure that data utilized for a canonical token list is secure and correct. Since this standard is focused on a data schema and its data properties there are no additional security considerations from for example homoglyph attacks (see CVE-2021-42574 (2021-10-25T12:38:28)</a>). Security Considerations: Data Privacy</h3> The standard does not set any requirements for compliance to jurisdiction legislation/regulations. It is the responsibility of the implementer to comply with applicable data privacy laws. Security Considerations: Production Readiness</h3> The standard does not set any requirements for the use of specific applications/tools/libraries etc. The implementer should perform due diligence when selecting specific applications/tools/libraries. Security Considerations: Internationalization and Localization</h3> The standard encourages implementers to follow the W3C "Strings on the Web: Language and Direction Metadata" best practices guide</a> for identifying language and base direction for strings used on the Web wherever appropriate. Copyright</h2> Copyright and related rights waived via CC0</a>. Cultural and Historical Asset Token 2023-02-28T00:00:00+00:00 Abstract</h2> This EIP proposes the establishment of a comprehensive metadata standard for Cultural and Historical Asset Tokens (CHATs) on the Ethereum platform. These tokens represent cultural and historical assets such as artwork, artifacts, collectibles, and rare items, providing crucial context and provenance to substantiate their significance and value. While existing NFT standards ensure the immutability and decentralized ownership of assets on the blockchain, based on our research they do not adequately capture the cultural and historical importance and value of such assets needed for widespread adoption by institutions such as museums. The CHAT standard aims to overcome these limitations by preserving the provenance, history, and evolving context of cultural and historical assets, thus substantiating their value. Furthermore, it incentivises museums, institutions, and asset owners to create tamper-proof records on the blockchain, ensuring transparency and accountability and accelerating adoption of web3 protocols. Additionally, the CHAT standard promotes interoperability with existing metadata standards in the arts and cultural sector, facilitating the search, discovery, and connection of distributed assets. Motivation</h2> Preserving context and significance - Provenance and context are crucial for cultural and historical assets. The CHAT standard captures and preserves the provenance and history of these assets, as well as the changing contexts that emerge from new knowledge and information. This context and provenance substantiate the significance and value of cultural and historical assets. Proof-based preservation - The recent incidents of lost artifacts and data breaches at a number of significant international museums points to a need in reassessing our current record keeping mechanisms. While existing systems mostly operate on trust, blockchain technology offers opportunities to establish permanent and verifiable records in a proof-based environment. Introducing the CHAT standard on the Ethereum platform enables museums, institutions, and owners of significant collections to create tamper-proof records on the blockchain. By representing these valuable cultural and historical assets as tokens on the blockchain, permanent and tamper-proof records can be established whenever amendments are made, ensuring greater transparency and accountability. Interoperability - The proposed standard addresses the multitude of existing metadata standards used in the arts and cultural sector. The vision is to create a metadata structure specifically built for preservation on the blockchain that is interoperable with these existing standards and compliant with the Open Archives Initiative (OAI) as well as the International Image Interoperability Framework protocol (IIIF). Search and Discovery - Ownership and history of artworks, artifacts, and historical intellectual properties are often distributed. Although there may never be a fully consolidated archive, a formalized blockchain-based metadata structure enables consolidation for search and discovery of the assets, without consolidating the ownership. For example, an artifact from an archaeological site of the Silk Road can be connected with Buddhist paintings, statues, and texts about the ancient trade route across museum and institutional collections internationally. The proposed CHAT metadata structure will facilitate easy access to these connections for the general public, researchers, scholars, other cultural professionals, brands, media, and any other interested parties. Currently, the ERC-721</a> standard includes a basic metadata extension, which optionally provides functions for identifying NFT collections ("name" and "symbol") and attributes for representing assets ("name," "description," and "image"). However, to provide comprehensive context and substantiate the value of tokenized assets, NFT issuers often create their own metadata structures. We believe that the basic extension alone is insufficient to capture the context and significance of cultural and historical assets. The lack of interoperable and consistent rich metadata hinders users' ability to search, discover, and connect tokenized assets on the blockchain. While connectivity among collections may not be crucial for NFTs designed for games and memberships, it is of utmost importance for cultural and historical assets. As the number and diversity of tokenized assets on the blockchain increase, it becomes essential to establish a consistent and comprehensive metadata structure that provides context, substantiates value, and enables connected search and discovery at scale. 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. This EIP extends ERC-721</a> and ERC-1155</a> with 48 additional properties to capture the cultural and historical significance of the underlying asset. Compatible contracts, besides implementing the relevant metadata schemas ("Metadata JSON Schema" for ERC-721</a> contracts or "Metadata URI JSON Schema" for ERC-1155</a> contracts), must implement the following metadata interface. Cultural and Historical Asset Metadata Extension TypeScript Interface</h3> The following TypeScript interface defines the Metadata JSON Schema compatible tokens must conform to: interface HistoricalAssetMetadata { name?: string; // Name of the CHAT description?: string; // Full description of the CHAT to provide the cultural and historical // context image?: string; // A URI pointing to a resource with mime type image/* to serve as the // cover image of the CHAT attributes?: CHATAttribute[]; // A list of attributes to describe the CHAT. Attribute object may be // repeated if a field has multiple values attributesExt?: ExtendedCHATAttribute[]; // A list of extended attributes to describe the CHAT, not to be // displayed. Attribute object may be repeated if a field has // multiple values } type CHATAttribute = { trait_type: "Catalogue Level", value: string } | { trait_type: "Publication / Creation Date", value: string } | { trait_type: "Creator Name", value: string } | { trait_type: "Creator Bio", value: string } | { trait_type: "Asset Type", value: string } | { trait_type: "Classification", value: string } | { trait_type: "Materials and Technology", value: string } | { trait_type: "Subject Matter", value: string } | { trait_type: "Edition", value: string } | { trait_type: "Series name", value: string } | { trait_type: "Dimensions Unit", value: string } | { trait_type: "Dimensions (height)", value: number } | { trait_type: "Dimensions (width)", value: number } | { trait_type: "Dimensions (depth)", value: number } | { trait_type: "Inscriptions / Marks", value: string } | { trait_type: "Credit Line", value: string } | { trait_type: "Current Owner", value: string } | { trait_type: "Provenance", value: string } | { trait_type: "Acquisition Date", value: string } | { trait_type: "Citation", value: string } | { trait_type: "Keyword", value: string } | { trait_type: "Copyright Holder", value: string } | { trait_type: "Bibliography", value: string } | { trait_type: "Issuer", value: string } | { trait_type: "Issue Timestamp", value: string } | { trait_type: "Issuer Description", value: string } | { trait_type: "Asset File Size", value: number } | { trait_type: "Asset File Format", value: string } | { trait_type: "Copyright / Restrictions", value: string } | { trait_type: "Asset Creation Geo", value: string } | { trait_type: "Asset Creation Location", value: string } | { trait_type: "Asset Creation Coordinates", value: string } | { trait_type: "Relevant Date", value: string } | { trait_type: "Relevant Geo", value: string } | { trait_type: "Relevant Location", value: string } | { trait_type: "Relevant Person", value: string } | { trait_type: "Relevant Entity", value: string } | { trait_type: "Asset Language", value: string } | { trait_type: "Is Physical Asset", value: boolean } type ExtendedCHATAttribute = { trait_type: "Asset Full Text", value: string } | { trait_type: "Exhibition / Loan History", value: string } | { trait_type: "Copyright Document", value: string } | { trait_type: "Provenance Document", value: string } | { trait_type: "Asset URL", value: string } | { trait_type: "Copyright Document of Underlying Asset", value: string }</code></pre>CHATAttribute Description</h4> trait_type</th> description</th></tr></thead> Catalogue Level</td> An indication of the level of cataloging represented by the record, based on the physical form or intellectual content of the material</td></tr> Publication / Creation Date</td> Earliest possible creation date of the underlying asset in ISO 8601 date format</td></tr> Creator Name</td> The name, brief biographical information, and roles (if necessary) of the named or anonymous individuals or corporate bodies responsible for the design, production, manufacture, or alteration of the work, presented in a syntax suitable for display to the end-user and including any necessary indications of uncertainty, ambiguity, and nuance. If there is no known creator, make a reference to the presumed culture or nationality of the unknown creator</td></tr> Creator Bio</td> The brief biography or description of creator</td></tr> Asset Type</td> The type of the underlying asset</td></tr> Classification</td> Classification terms or codes are used to place a work of art or architecture in a useful organizational scheme that has been devised by a repository, collector, or other person or entity. Formal classification systems are used to relate a work of art or architecture to broader, narrower, and related objects. Classification terms group similar works together according to varying criteria</td></tr> Materials and Technology</td> The materials and/or techniques used to create the physical underlying asset</td></tr> Subject Matter</td> Indexing terms that characterize in general terms what the work depicts or what is depicted in it. This subject analysis is the minimum required. It is recommended to also list specific subjects, if possible</td></tr> Edition</td> Edition of the original work</td></tr> Series Name</td> The name of the series the asset is a part of</td></tr> Dimensions Unit</td> Unit of the measurement of the dimension of the asset</td></tr> Dimensions (height)</td> Height of the underlying asset</td></tr> Dimensions (width)</td> Width of the underlying asset</td></tr> Dimensions (depth)</td> Depth of the underlying asset</td></tr> Credit Line</td> Crediting details of the source or origin of an image or content being used publicly. The credit line typically includes important details such as the name of the museum, the title or description of the artwork or object, the artist's name (if applicable), the date of creation, and any other relevant information that helps identify and contextualize the work</td></tr> Inscriptions / Marks</td> A description of distinguishing or identifying physical markings, lettering, annotations, texts, or labels that are a part of a work or are affixed, applied, stamped, written, inscribed, or attached to the work, excluding any mark or text inherent in materials (record watermarks in MATERIALS AND TECHNIQUES)</td></tr> Current Owner</td> Name of the current owner</td></tr> Provenance</td> Provenance provides crucial information about the artwork's authenticity, legitimacy, and historical significance. It includes details such as the names of previous owners, dates of acquisition, locations where the artwork or artifact resided, and any significant events or transactions related to its ownership</td></tr> Acquisition Date</td> The date on which the acquirer obtained the asset</td></tr> Citation</td> Citations of the asset in publications, journals, and any other medium</td></tr> Keyword</td> Keywords that are relevant for researchers</td></tr> Copyright Holder</td> Copyright holder of the underlying asset</td></tr> Bibliography</td> Information on where this asset has been referenced, cited, consulted, and for what purpose</td></tr> Issuer</td> Issuer of the token</td></tr> Issue Timestamp</td> Date of token creation</td></tr> Issuer Description</td> Brief description of the issuing party</td></tr> Asset File Size</td> Size of the digital file of the underlying asset in bytes</td></tr> Asset File Format</td> The physical form or the digital format of the underlying asset. For digital format, a MIME type should be specified</td></tr> Copyright / Restrictions</td> The copyright status the work is under</td></tr> Asset Creation Geo</td> Country, subdivision, and city where the underlying asset was created. Reference to ISO 3166-2 standard for the short name of the country and subdivision. Utilize the official name for the city if it is not covered in the ISO subdivision</td></tr> Asset Creation Location</td> Specific cities and named locations where the underlying asset was created</td></tr> Asset Creation Coordinates</td> Coordinates of the location where the underlying asset was created</td></tr> Relevant Date</td> Dates, in ISO 8601 date format, referenced in, and important to the significance of the CHAT</td></tr> Relevant Geo</td> Country, subdivision, and city CHATs are referenced and important to the significance of the CHAT. Reference to ISO 3166-2 standard for the short name of the country and subdivision. Utilize the official name for the city if it is not covered in the ISO subdivision</td></tr> Relevant Location</td> Specific cities and named locations referenced in, and important to the significance of the CHAT</td></tr> Relevant Person</td> Individuals referenced in, and important to the significance of the CHAT</td></tr> Relevant Entity</td> Entities referenced in, and important to the significance of the CHAT</td></tr> Asset Language</td> Languages used in the underlying asset. Reference to ISO 639 for code or macrolanguage names</td></tr> Is Physical Asset</td> Flags whether the asset is tied to a physical asset</td></tr> </tbody></table> ExtendedCHATAttribute Description</h4> trait_type</th> description</th></tr></thead> Asset Full Text</td> The full text in the underlying asset of the CHAT</td></tr> Exhibition / Loan History</td> Including exhibition/loan description, dates, title, type, curator, organizer, sponsor, venue</td></tr> Copyright Document</td> A URI pointing to the legal contract CHATs outlines the copyright of the underlying asset</td></tr> Provenance Document</td> A URI pointing to the existing provenance record documents of the underlying asset</td></tr> Asset URL</td> A URI pointing to a high-quality file of the underlying asset</td></tr> Copyright Document of Underlying Asset</td> A URI pointing to legal document outlining the rights of the token owner. Specific dimensions include the right to display a work via digital and physical mediums, present the work publicly, create or sell copies of the work, and create or sell derivations from the underlying asset</td></tr> </tbody></table> Example</h4> To illustrate the use of the CHAT metadata extension, we provide an example of a CHAT metadata JSON file for the famous Japanese woodblock print "Under the Wave off Kanagawa" by Katsushika Hokusai, which is currently held by the Art Institute of Chicago. The metadata format is compatible with the ERC-721</a> and OpenSea style metadata format. { "name": "Under the Wave off Kanagawa (Kanagawa oki nami ura), also known as The Great Wave, from the series “Thirty-Six Views of Mount Fuji (Fugaku sanjūrokkei)", "description": "Katsushika Hokusai’s much celebrated series, Thirty-Six Views of Mount Fuji (Fugaku sanjûrokkei), was begun in 1830, when the artist was 70 years old. This tour-de-force series established the popularity of landscape prints, which continues to this day. Perhaps most striking about the series is Hokusai’s copious use of the newly affordable Berlin blue pigment, featured in many of the compositions in the color for the sky and water. Mount Fuji is the protagonist in each scene, viewed from afar or up close, during various weather conditions and seasons, and from all directions.\n\nThe most famous image from the set is the “Great Wave” (Kanagawa oki nami ura), in which a diminutive Mount Fuji can be seen in the distance under the crest of a giant wave. The three impressions of Hokusai’s Great Wave in the Art Institute are all later impressions than the first state of the design.", "image": "ipfs://bafybeiav6sqcgzxk5h5afnmb3iisgma2kpnyj5fa5gnhozwaqwzlayx6se", "attributes": [ { "trait_type": "Publication / Creation Date", "value": "1826/1836" }, { "trait_type": "Creator Name", "value": "Katsushika Hokusai" }, { "trait_type": "Creator Bio", "value": "Katsushika Hokusai’s woodblock print The Great Wave is one of the most famous and recognizable works of art in the world. Hokusai spent the majority of his life in the capital of Edo, now Tokyo, and lived in a staggering 93 separate residences. Despite this frenetic movement, he produced tens of thousands of sketches, prints, illustrated books, and paintings. He also frequently changed the name he used to sign works of art, and each change signaled a shift in artistic style and intended audience." }, { "trait_type": "Asset Type", "value": "Painting" }, { "trait_type": "Classification", "value": "Arts of Asia" }, { "trait_type": "Materials and Technology", "value": "Color woodblock print, oban" }, { "trait_type": "Subject Matter", "value": "Asian Art" }, { "trait_type": "Subject Matter", "value": "Edo Period (1615-1868)" }, { "trait_type": "Subject Matter", "value": "Ukiyo-e Style" }, { "trait_type": "Subject Matter", "value": "Woodblock Prints" }, { "trait_type": "Subject Matter", "value": "Japan 1800-1900 A.D." }, { "trait_type": "Edition", "value": "1" }, { "trait_type": "Series name", "value": "Thirty-Six Views of Mount Fuji (Fugaku sanjûrokkei)" }, { "trait_type": "Dimensions Unit", "value": "cm" }, { "trait_type": "Dimensions (height)", "value": 25.4 }, { "trait_type": "Dimensions (width)", "value": 37.6 }, { "trait_type": "Inscriptions / Marks", "value": "Signature: Hokusai aratame Iitsu fude" }, { "trait_type": "Inscriptions / Marks", "value": "Publisher: Nishimura-ya Yohachi" }, { "trait_type": "Credit Line", "value": "Clarence Buckingham Collection" }, { "trait_type": "Current Owner", "value": "Art Institute of Chicago" }, { "trait_type": "Provenance", "value": "Yamanaka, New York by 1905" }, { "trait_type": "Provenance", "value": "Sold to Clarence Buckingham, Chicago by 1925" }, { "trait_type": "Provenance", "value": "Kate S. Buckingham, Chicago, given to the Art Institute of Chicago, 1925." }, { "trait_type": "Acquisition Date", "value": "1925" }, { "trait_type": "Citation", "value": "James Cuno, The Art Institute of Chicago: The Essential Guide, rev. ed. (Art Institute of Chicago, 2009) p. 100." }, { "trait_type": "Citation", "value": "James N. Wood, The Art Institute of Chicago: The Essential Guide, rev. ed. (Art Institute of Chicago, 2003), p. 86." }, { "trait_type": "Citation", "value": "Jim Ulak, Japanese Prints (Art Institute of Chicago, 1995), p. 268." }, { "trait_type": "Citation", "value": "Ukiyo-e Taikei (Tokyo, 1975), vol. 8, 29; XIII, I." }, { "trait_type": "Citation", "value": "Matthi Forrer, Hokusai (Royal Academy of Arts, London 1988), p. 264." }, { "trait_type": "Citation", "value": "Richard Lane, Hokusai: Life and Work (London, 1989), pp. 189, 192." }, { "trait_type": "Copyright Holder", "value": "Public domain" }, { "trait_type": "Copyright / Restrictions", "value": "CC0" }, { "trait_type": "Asset Creation Geo", "value": "Japan" }, { "trait_type": "Asset Creation Location", "value": "Tokyo (Edo)" }, { "trait_type": "Asset Creation Coordinates", "value": "36.2048° N, 138.2529° E" }, { "trait_type": "Relevant Date", "value": "18th Century" }, { "trait_type": "Relevant Geo", "value": "Japan, Chicago" }, { "trait_type": "Relevant Location", "value": "Art Institute of Chicago" }, { "trait_type": "Relevant Person", "value": "Katsushika Hokusai" }, { "trait_type": "Relevant Person", "value": "Yamanaka" }, { "trait_type": "Relevant Person", "value": "Clarence Buckingham" }, { "trait_type": "Relevant Person", "value": "Kate S. Buckingham" }, { "trait_type": "Relevant Entity", "value": "Art Institute of Chicago, Clarence Buckingham Collection" }, { "trait_type": "Asset Language", "value": "Japanese" }, { "trait_type": "Is Physical Asset", "value": true } ] }</code></pre>Rationale</h2> Choosing to Extend Off-Chain Metadata JSON Schema over On-Chain Interface</h3> Both the ERC-721</a> and ERC-1155</a> provide natural extension points in the metadata JSON file associated with NFTs to supply enriched datasets about the underlying assets. Providing enriched datasets through off-chain metadata JSON files allows existing NFT contracts to adopt the new metadata structure proposed in this EIP without upgrading or migrating. The off-chain design enables flexible and progressive enhancement of any NFT collections to adopt this standard gradually. This approach allows NFT collections to be deployed using already-audited and battle-tested smart contract code without creating or adapting new smart contracts, reducing the risk associated with adopting and implementing a new standard. Capturing Attributes Extensions in attributes</code> and attributesExt</code> properties</h3> In the design of the Cultural and Historical Asset Token (CHAT) metadata extension, we have made a deliberate choice to capture the metadata attributes between two main properties: attributes</code> and attributesExt</code>. This division serves two distinct purposes while ensuring maximum compatibility with existing NFT galleries and marketplaces. 1. attributes</code> Property The attributes</code> property contains core metadata attributes that are integral to the identity and categorization of CHATs. These attributes are meant to be readily accessible, displayed, and searchable by NFT galleries and marketplaces. By placing fundamental details such as the CHAT's name, description, image, and other key characteristics in attributes</code>, we ensure that these essential elements can be easily presented to users, collectors, and researchers. This approach allows CHATs to seamlessly integrate with existing NFT platforms and marketplaces without requiring major modifications. 2. attributesExt</code> Property The attributesExt</code> property, on the other hand, is dedicated to extended attributes that provide valuable, in-depth information about a CHAT but are not typically intended for display or search within NFT galleries and marketplaces. These extended attributes serve purposes such as archival documentation, provenance records, and additional context that may not be immediately relevant to a casual observer or collector. By isolating these extended attributes in attributesExt</code>, we strike a balance between comprehensiveness and user-friendliness. This approach allows CHAT creators to include rich historical and contextual data without overwhelming the typical user interface, making the extended information available for scholarly or specialized use cases. This division of attributes into attributes</code> and attributesExt</code> ensures that the CHAT standard remains highly compatible with existing NFT ecosystems, while still accommodating the specific needs of cultural and historical assets. Users can enjoy a seamless experience in browsing and collecting CHATs, while researchers and historians have access to comprehensive information when required, all within a framework that respects the practicalities of both user interfaces and extended data documentation. Backwards Compatibility</h2> This EIP is fully backward compatible with ERC-721</a> and ERC-1155</a>. Security Considerations</h2> NFT platforms and systems working with Cultural and Historical Asset Metadata JSON files are recommended to treat the files as client-supplied data and follow the appropriate best practices for processing such data. Specifically, when processing the URI fields, backend systems should take extra care to prevent a malicious issuer from exploiting these fields to perform Server-Side Request Forgery (SSRF). Frontend or client-side systems are recommended to escape all control characters that may be exploited to perform Cross-Site Scripting (XSS). Processing systems should manage resource allocation to prevent the systems from being vulnerable to Denial of Service ( DOS) attacks or circumventing security protection through arbitrary code exceptions. Improper processing of variable data, such as strings, arrays, and JSON objects, may result in a buffer overflow. Therefore, it is crucial to allocate resources carefully to avoid such vulnerabilities. The metadata JSON files and the digital resources representing both the token and underlying assets should be stored in a decentralized storage network to preserve the integrity and to ensure the availability of data for long-term preservation. Establishing the authenticity of the claims made in the Metadata JSON file is beyond the scope of this EIP, and is left to future EIPs to propose an appropriate protocol. Copyright</h2> Copyright and related rights waived via CC0</a>. Bit Based Permission 2023-02-27T00:00:00+00:00 Abstract</h2> This EIP offers a standard for building a bit-based permission and role system. Each permission is represented by a single bit. By using an uint256</code>, up to $256$ permissions and $2^{256}$ roles can be defined. We are able to specify the importance of each permission based on the order of the bits. 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. Note The following specifications use syntax from Solidity 0.8.7</code> (or above) Interface of reference is described as followed: pragma solidity ^0.8.7; /** @title EIP-6617 Bit Based Permission @dev See https://eips.ethereum.org/EIPS/eip-6617 */ interface IEIP6617 { /** MUST trigger when a permission is granted. @param _grantor Grantor of the permission @param _permission Permission that is granted @param _user User who received the permission */ event PermissionGranted(address indexed _grantor, uint256 indexed _permission, address indexed _user); /** MUST trigger when a permission is revoked. @param _revoker Revoker of the permission @param _permission Permission that is revoked @param _user User who lost the permission */ event PermissionRevoked(address indexed _revoker, uint256 indexed _permission, address indexed _user); /** @notice Check if user has permission @param _user Address of the user whose permission we need to check @param _requiredPermission The required permission @return True if the _permission is a superset of the _requiredPermission else False */ function hasPermission(address _user, uint256 _requiredPermission) external view returns (bool); /** @notice Add permission to user @param _user Address of the user to whom we are going to add a permission @param _permissionToAdd The permission that will be added @return The new permission with the _permissionToAdd */ function grantPermission(address _user, uint256 _permissionToAdd) external returns (bool); /** @notice Revoke permission from user @param _user Address of the user to whom we are going to revoke a permission @param _permissionToRevoke The permission that will be revoked @return The new permission without the _permissionToRevoke */ function revokePermission(address _user, uint256 _permissionToRevoke) external returns (bool); }</code></pre> Compliant contracts MUST implement IEIP6617</code></li> A permission in a compliant contract is represented as an uint256</code>. A permission MUST take only one bit of an uint256</code> and therefore MUST be a power of 2. Each permission MUST be unique and the 0</code> MUST be used for none permission.</li> </ul> Metadata Interface</h3> It is RECOMMENDED for compliant contracts to implement the optional extension IEIP6617Meta</code>. They SHOULD define a name and description for the base permissions and main combinaison. </li> They SHOULD NOT define a description for every subcombinaison of permissions possible. </li> </ul> /** * @dev Defined the interface of the metadata of EIP6617, MAY NOT be implemented */ interface IEIP6617Meta { /** Structure of permission description @param _permission Permission @param _name Name of the permission @param _description Description of the permission */ struct PermissionDescription { uint256 permission; string name; string description; } /** MUST trigger when the description is updated. @param _permission Permission @param _name Name of the permission @param _description Description of the permission */ event UpdatePermissionDescription(uint256 indexed _permission, string indexed _name, string indexed _description); /** Returns the description of a given `_permission`. @param _permission Permission */ function getPermissionDescription(uint256 _permission) external view returns (PermissionDescription memory description); /** Return `true` if the description was set otherwise return `false`. It MUST emit `UpdatePermissionDescription` event. @param _permission Permission @param _name Name of the permission @param _description Description of the permission */ function setPermissionDescription(uint256 _permission, string memory _name, string memory _description) external returns (bool success); }</code></pre>Rationale</h2> Currently permission and access control is performed using a single owner (ERC-173</a>) or with bytes32</code> roles (ERC-5982</a>). However, using bitwise and bitmask operations allows for greater gas-efficiency and flexibility. Gas cost efficiency</h3> Bitwise operations are very cheap and fast. For example, doing an AND</code> bitwise operation on a permission bitmask is significantly cheaper than calling any number of LOAD</code> opcodes. Flexibility</h3> With the 256 bits of the uint256</code>, we can create up to 256 different permissions which leads to $2^{256}$ unique combinations (a.k.a. roles). (A role is a combination of multiple permissions). Not all roles have to be predefined. Since permissions are defined as unsigned integers, we can use the binary OR operator to create new role based on multiple permissions. Ordering permissions by importance</h3> We can use the most significant bit to represent the most important permission, the comparison between permissions can then be done easily since they all are uint256</code>s. Associate a meaning</h3> Compared with access control managed via ERC-5982, this EIP does not provide a direct and simple understanding of the meaning of a permission or role. To deal with this problem, you can set up the metadata interface, which associates a name and description to each permission or role. Reference Implementation</h2> First implementation could be found here: Basic ERC-6617 implementation</a></li> </ul> Security Considerations</h2> No security considerations. Copyright</h2> Copyright and related rights waived via CC0</a>. Non-fungible Token Bound Accounts 2023-02-23T00:00:00+00:00 Abstract</h2> This proposal defines a system which assigns Ethereum accounts to all non-fungible tokens. These token bound accounts allow NFTs to own assets and interact with applications, without requiring changes to existing smart contracts or infrastructure. Motivation</h2> The ERC-721</a> standard enabled an explosion of non-fungible token applications. Some notable use cases have included breedable cats, generative artwork, and exchange liquidity positions. However, NFTs cannot act as agents or associate with other on-chain assets. This limitation makes it difficult to represent many real-world non-fungible assets as NFTs. For example: A character in a role-playing game that accumulates assets and abilities over time based on actions they have taken</li> An automobile composed of many fungible and non-fungible components</li> An investment portfolio composed of multiple fungible assets</li> A punch pass membership card granting access to an establishment and recording a history of past interactions</li> </ul> This proposal aims to give every NFT the same rights as an Ethereum user. This includes the ability to self-custody assets, execute arbitrary operations, control multiple independent accounts, and use accounts across multiple chains. By doing so, this proposal allows complex real-world assets to be represented as NFTs using a common pattern that mirrors Etherem's existing ownership model. This is accomplished by defining a singleton registry which assigns unique, deterministic smart contract account addresses to all existing and future NFTs. Each account is permanently bound to a single NFT, with control of the account granted to the holder of that NFT. The pattern defined in this proposal does not require any changes to existing NFT smart contracts. It is also compatible out of the box with nearly all existing infrastructure that supports Ethereum accounts, from on-chain protocols to off-chain indexers. Token bound accounts are compatible with every existing on-chain asset standard, and can be extended to support new asset standards created in the future. By giving every NFT the full capabilities of an Ethereum account, this proposal enables many novel use cases for existing and future NFTs. 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. Overview</h3> The system outlined in this proposal has two main components: A singleton registry for token bound accounts</li> A common interface for token bound account implementations</li> </ul> The following diagram illustrates the relationship between NFTs, NFT holders, token bound accounts, and the Registry: Registry</h3> The registry is a singleton contract that serves as the entry point for all token bound account address queries. It has two functions: createAccount</code> - creates the token bound account for an NFT given an implementation</code> address</li> account</code> - computes the token bound account address for an NFT given an implementation</code> address</li> </ul> The registry is permissionless, immutable, and has no owner. The complete source code for the registry can be found in the Registry Implementation</a> section. The registry MUST be deployed at address 0x000000006551c19487814612e58FE06813775758</code> using Nick's Factory (0x4e59b44847b379578588920cA78FbF26c0B4956C</code>) with salt 0x0000000000000000000000000000000000000000fd8eb4e1dca713016c518e31</code>. The registry can be deployed to any EVM-compatible chain using the following transaction: { "to": "0x4e59b44847b379578588920ca78fbf26c0b4956c", "value": "0x0", "data": "0x0000000000000000000000000000000000000000fd8eb4e1dca713016c518e31608060405234801561001057600080fd5b5061023b806100206000396000f3fe608060405234801561001057600080fd5b50600436106100365760003560e01c8063246a00211461003b5780638a54c52f1461006a575b600080fd5b61004e6100493660046101b7565b61007d565b6040516001600160a01b03909116815260200160405180910390f35b61004e6100783660046101b7565b6100e1565b600060806024608c376e5af43d82803e903d91602b57fd5bf3606c5285605d52733d60ad80600a3d3981f3363d3d373d3d3d363d7360495260ff60005360b76055206035523060601b60015284601552605560002060601b60601c60005260206000f35b600060806024608c376e5af43d82803e903d91602b57fd5bf3606c5285605d52733d60ad80600a3d3981f3363d3d373d3d3d363d7360495260ff60005360b76055206035523060601b600152846015526055600020803b61018b578560b760556000f580610157576320188a596000526004601cfd5b80606c52508284887f79f19b3655ee38b1ce526556b7731a20c8f218fbda4a3990b6cc4172fdf887226060606ca46020606cf35b8060601b60601c60005260206000f35b80356001600160a01b03811681146101b257600080fd5b919050565b600080600080600060a086880312156101cf57600080fd5b6101d88661019b565b945060208601359350604086013592506101f46060870161019b565b94979396509194608001359291505056fea2646970667358221220ea2fe53af507453c64dd7c1db05549fa47a298dfb825d6d11e1689856135f16764736f6c63430008110033", }</code></pre> The registry MUST deploy each token bound account as an ERC-1167</a> minimal proxy with immutable constant data appended to the bytecode. The deployed bytecode of each token bound account MUST have the following structure: ERC-1167 Header (10 bytes) <implementation (address)> (20 bytes) ERC-1167 Footer (15 bytes) <salt (bytes32)> (32 bytes) <chainId (uint256)> (32 bytes) <tokenContract (address)> (32 bytes) <tokenId (uint256)> (32 bytes)</code></pre> For example, the token bound account with implementation address 0xbebebebebebebebebebebebebebebebebebebebe</code>, salt 0</code>, chain ID 1</code>, token contract 0xcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcf</code> and token ID 123</code> would have the following deployed bytecode: 363d3d373d3d3d363d73bebebebebebebebebebebebebebebebebebebebe5af43d82803e903d91602b57fd5bf300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000cfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcf000000000000000000000000000000000000000000000000000000000000007b</code></pre> Each token bound account proxy MUST delegate execution to a contract that implements the IERC6551Account</code> interface. The registry MUST deploy all token bound accounts using the create2</code> opcode so that each account address is deterministic. Each token bound account address SHALL be derived from the unique combination of its implementation address, token contract address, token ID, chain ID, and salt. The registry MUST implement the following interface: interface IERC6551Registry { /** * @dev The registry MUST emit the ERC6551AccountCreated event upon successful account creation. */ event ERC6551AccountCreated( address account, address indexed implementation, bytes32 salt, uint256 chainId, address indexed tokenContract, uint256 indexed tokenId ); /** * @dev The registry MUST revert with AccountCreationFailed error if the create2 operation fails. */ error AccountCreationFailed(); /** * @dev Creates a token bound account for a non-fungible token. If account has already been created, returns the account address without calling create2. Emits ERC6551AccountCreated event. @return account The address of the token bound account */ function createAccount( address implementation, bytes32 salt, uint256 chainId, address tokenContract, uint256 tokenId ) external returns (address account); /** * @dev Returns the computed token bound account address for a non-fungible token. @return account The address of the token bound account */ function account( address implementation, bytes32 salt, uint256 chainId, address tokenContract, uint256 tokenId ) external view returns (address account); }</code></pre>Account Interface</h3> All token bound accounts SHOULD be created via the singleton registry. All token bound account implementations MUST implement ERC-165</a> interface detection. All token bound account implementations MUST implement ERC-1271</a> signature validation. All token bound account implementations MUST implement the following interface: /// @dev the ERC-165 identifier for this interface is `0x6faff5f1` interface IERC6551Account { /** * @dev Allows the account to receive Ether. Accounts MUST implement a `receive` function. Accounts MAY perform arbitrary logic to restrict conditions * under which Ether can be received. */ receive() external payable; /** * @dev Returns the identifier of the non-fungible token which owns the account. The return value of this function MUST be constant - it MUST NOT change over time. @return chainId The chain ID of the chain the token exists on * @return tokenContract The contract address of the token * @return tokenId The ID of the token */ function token() external view returns (uint256 chainId, address tokenContract, uint256 tokenId); /** * @dev Returns a value that SHOULD be modified each time the account changes state. @return The current account state */ function state() external view returns (uint256); /** * @dev Returns a magic value indicating whether a given signer is authorized to act on behalf * of the account. MUST return the bytes4 magic value 0x523e3260 if the given signer is valid. By default, the holder of the non-fungible token the account is bound to MUST be considered * a valid signer. Accounts MAY implement additional authorization logic which invalidates the holder as a * signer or grants signing permissions to other non-holder accounts. @param signer The address to check signing authorization for * @param context Additional data used to determine whether the signer is valid * @return magicValue Magic value indicating whether the signer is valid */ function isValidSigner(address signer, bytes calldata context) external view returns (bytes4 magicValue); } </code></pre>Execution Interface</h3> All token bound accounts MUST implement an execution interface which allows valid signers to execute arbitrary operations on behalf of the account. Support for an execution interface MUST be signaled by the account using ERC-165 interface detection. Token bound accounts MAY support the following execution interface: /// @dev the ERC-165 identifier for this interface is `0x51945447` interface IERC6551Executable { /** * @dev Executes a low-level operation if the caller is a valid signer on the account. Reverts and bubbles up error if operation fails. Accounts implementing this interface MUST accept the following operation parameter values: * - 0 = CALL * - 1 = DELEGATECALL * - 2 = CREATE * - 3 = CREATE2 Accounts implementing this interface MAY support additional operations or restrict a signer's * ability to execute certain operations. @param to The target address of the operation * @param value The Ether value to be sent to the target * @param data The encoded operation calldata * @param operation A value indicating the type of operation to perform * @return The result of the operation */ function execute(address to, uint256 value, bytes calldata data, uint8 operation) external payable returns (bytes memory); }</code></pre>Rationale</h2> Singleton Registry</h3> This proposal specifies a single, canonical registry that can be permissionlessly deployed to any chain at a known address. It purposefully does not specify a common interface that can be implemented by multiple registry contracts. This approach enables several critical properties. Counterfactual Accounts</h4> All token bound accounts are created using the create2 opcode, enabling accounts to exist in a counterfactual state prior to their creation. This allows token bound accounts to receive assets prior to contract creation. A singleton account registry ensures a common addressing scheme is used for all token bound account addresses. Trustless Deployments</h4> A single ownerless registry ensures that the only trusted contract for any token bound account is the implementation. This guarantees the holder of a token access to all assets stored within a counterfactual account using a trusted implementation. Without a canonical registry, some token bound accounts may be deployed using an owned or upgradable registry. This may lead to loss of assets stored in counterfactual accounts, and increases the scope of the security model that applications supporting this proposal must consider. Cross-chain Compatibility</h4> A singleton registry with a known address enables each token bound account to exist on multiple chains. The inclusion of chainId</code> as a parameter to createAccount</code> allows the contract for a token bound account to be deployed at the same address on any supported chain. Account implementations are therefore able to support cross-chain account execution, where an NFT on one chain can control its token bound account on another chain. Single Entry Point</h4> A single entry point for querying account addresses and AccountCreated</code> events simplifies the complex task of indexing token bound accounts in applications which support this proposal. Implementation Diversity</h4> A singleton registry allows diverse account implementations to share a common addressing scheme. This gives developers significant freedom to implement both account-specific features (e.g. delegation) as well as alternative account models (e.g. ephemeral accounts) in a way that can be easily supported by client applications. Registry vs Factory</h3> The term "registry" was chosen instead of "factory" to highlight the canonical nature of the contract and emphasize the act of querying account addresses (which occurs regularly) over the creation of accounts (which occurs only once per account). Variable Execution Interface</h3> This proposal does not require accounts to implement a specific execution interface in order to be compatible, so long as they signal support for at least one execution interface via ERC-165 interface detection. Allowing account developers to choose their own execution interface allows this proposal to support the wide variety of existing execution interfaces and maintain forward compatibility with likely future standardized interfaces. Account Ambiguity</h3> The specification proposed above allows NFTs to have multiple token bound accounts. During the development of this proposal, alternative architectures were considered which would have assigned a single token bound account to each NFT, making each token bound account address an unambiguous identifier. However, these alternatives present several trade offs. First, due to the permissionless nature of smart contracts, it is impossible to enforce a limit of one token bound account per NFT. Anyone wishing to utilize multiple token bound accounts per NFT could do so by deploying an additional registry contract. Second, limiting each NFT to a single token bound account would require a static, trusted account implementation to be included in this proposal. This implementation would inevitably impose specific constraints on the capabilities of token bound accounts. Given the number of unexplored use cases this proposal enables and the benefit that diverse account implementations could bring to the non-fungible token ecosystem, it is the authors' opinion that defining a canonical and constrained implementation in this proposal is premature. Finally, this proposal seeks to grant NFTs the ability to act as agents on-chain. In current practice, on-chain agents often utilize multiple accounts. A common example is individuals who use a "hot" account for daily use and a "cold" account for storing valuables. If on-chain agents commonly use multiple accounts, it stands to reason that NFTs ought to inherit the same ability. Proxy Implementation</h3> ERC-1167 minimal proxies are well supported by existing infrastructure and are a common smart contract pattern. This proposal deploys each token bound account using a custom ERC-1167 proxy implementation that stores the salt, chain id, token contract address, and token ID as ABI-encoded constant data appended to the contract bytecode. This allows token bound account implementations to easily query this data while ensuring it remains constant. This approach was taken to maximize compatibility with existing infrastructure while also giving smart contract developers full flexibility when creating custom token bound account implementations. Chain Identifier</h3> This proposal uses the chain ID to identify each NFT along with its contract address and token ID. Token identifiers are globally unique on a single Ethereum chain, but may not be unique across multiple Ethereum chains. Backwards Compatibility</h2> This proposal seeks to be maximally backwards compatible with existing non-fungible token contracts. As such, it does not extend the ERC-721 standard. Additionally, this proposal does not require the registry to perform an ERC-165 interface check for ERC-721 compatibility prior to account creation. This maximizes compatibility with non-fungible token contracts that pre-date the ERC-721 standard (such as CryptoKitties) or only implement a subset of the ERC-721 interface (such as ENS NameWrapper names). It also allows the system described in this proposal to be used with semi-fungible or fungible tokens, although these use cases are outside the scope of the proposal. Smart contract authors may optionally choose to enforce interface detection for ERC-721 in their account implementations. Reference Implementation</h2> Example Account Implementation</h3> pragma solidity ^0.8.0; import "@openzeppelin/contracts/utils/introspection/IERC165.sol"; import "@openzeppelin/contracts/token/ERC721/IERC721.sol"; import "@openzeppelin/contracts/interfaces/IERC1271.sol"; import "@openzeppelin/contracts/utils/cryptography/SignatureChecker.sol"; interface IERC6551Account { receive() external payable; function token() external view returns (uint256 chainId, address tokenContract, uint256 tokenId); function state() external view returns (uint256); function isValidSigner(address signer, bytes calldata context) external view returns (bytes4 magicValue); } interface IERC6551Executable { function execute(address to, uint256 value, bytes calldata data, uint8 operation) external payable returns (bytes memory); } contract ERC6551Account is IERC165, IERC1271, IERC6551Account, IERC6551Executable { uint256 immutable deploymentChainId = block.chainid; uint256 public state; receive() external payable {} function execute(address to, uint256 value, bytes calldata data, uint8 operation) external payable virtual returns (bytes memory result) { require(_isValidSigner(msg.sender), "Invalid signer"); require(operation == 0, "Only call operations are supported"); ++state; bool success; (success, result) = to.call{value: value}(data); if (!success) { assembly { revert(add(result, 32), mload(result)) } } } function isValidSigner(address signer, bytes calldata) external view virtual returns (bytes4) { if (_isValidSigner(signer)) { return IERC6551Account.isValidSigner.selector; } return bytes4(0); } function isValidSignature(bytes32 hash, bytes memory signature) external view virtual returns (bytes4 magicValue) { bool isValid = SignatureChecker.isValidSignatureNow(owner(), hash, signature); if (isValid) { return IERC1271.isValidSignature.selector; } return bytes4(0); } function supportsInterface(bytes4 interfaceId) external pure virtual returns (bool) { return interfaceId == type(IERC165).interfaceId || interfaceId == type(IERC6551Account).interfaceId || interfaceId == type(IERC6551Executable).interfaceId; } function token() public view virtual returns (uint256, address, uint256) { bytes memory footer = new bytes(0x60); assembly { extcodecopy(address(), add(footer, 0x20), 0x4d, 0x60) } return abi.decode(footer, (uint256, address, uint256)); } function owner() public view virtual returns (address) { (uint256 chainId, address tokenContract, uint256 tokenId) = token(); if (chainId != deploymentChainId) return address(0); return IERC721(tokenContract).ownerOf(tokenId); } function _isValidSigner(address signer) internal view virtual returns (bool) { return signer == owner(); } }</code></pre>Registry Implementation</h3> // SPDX-License-Identifier: MIT pragma solidity ^0.8.4; interface IERC6551Registry { /** * @dev The registry MUST emit the ERC6551AccountCreated event upon successful account creation. */ event ERC6551AccountCreated( address account, address indexed implementation, bytes32 salt, uint256 chainId, address indexed tokenContract, uint256 indexed tokenId ); /** * @dev The registry MUST revert with AccountCreationFailed error if the create2 operation fails. */ error AccountCreationFailed(); /** * @dev Creates a token bound account for a non-fungible token. If account has already been created, returns the account address without calling create2. Emits ERC6551AccountCreated event. @return account The address of the token bound account */ function createAccount( address implementation, bytes32 salt, uint256 chainId, address tokenContract, uint256 tokenId ) external returns (address account); /** * @dev Returns the computed token bound account address for a non-fungible token. @return account The address of the token bound account */ function account( address implementation, bytes32 salt, uint256 chainId, address tokenContract, uint256 tokenId ) external view returns (address account); } contract ERC6551Registry is IERC6551Registry { function createAccount( address implementation, bytes32 salt, uint256 chainId, address tokenContract, uint256 tokenId ) external returns (address) { assembly { // Memory Layout: // ---- // 0x00 0xff (1 byte) // 0x01 registry (address) (20 bytes) // 0x15 salt (bytes32) (32 bytes) // 0x35 Bytecode Hash (bytes32) (32 bytes) // ---- // 0x55 ERC-1167 Constructor + Header (20 bytes) // 0x69 implementation (address) (20 bytes) // 0x5D ERC-1167 Footer (15 bytes) // 0x8C salt (uint256) (32 bytes) // 0xAC chainId (uint256) (32 bytes) // 0xCC tokenContract (address) (32 bytes) // 0xEC tokenId (uint256) (32 bytes) // Silence unused variable warnings pop(chainId) // Copy bytecode + constant data to memory calldatacopy(0x8c, 0x24, 0x80) // salt, chainId, tokenContract, tokenId mstore(0x6c, 0x5af43d82803e903d91602b57fd5bf3) // ERC-1167 footer mstore(0x5d, implementation) // implementation mstore(0x49, 0x3d60ad80600a3d3981f3363d3d373d3d3d363d73) // ERC-1167 constructor + header // Copy create2 computation data to memory mstore(0x35, keccak256(0x55, 0xb7)) // keccak256(bytecode) mstore(0x15, salt) // salt mstore(0x01, shl(96, address())) // registry address mstore8(0x00, 0xff) // 0xFF // Compute account address let computed := keccak256(0x00, 0x55) // If the account has not yet been deployed if iszero(extcodesize(computed)) { // Deploy account contract let deployed := create2(0, 0x55, 0xb7, salt) // Revert if the deployment fails if iszero(deployed) { mstore(0x00, 0x20188a59) // `AccountCreationFailed()` revert(0x1c, 0x04) } // Store account address in memory before salt and chainId mstore(0x6c, deployed) // Emit the ERC6551AccountCreated event log4( 0x6c, 0x60, // `ERC6551AccountCreated(address,address,bytes32,uint256,address,uint256)` 0x79f19b3655ee38b1ce526556b7731a20c8f218fbda4a3990b6cc4172fdf88722, implementation, tokenContract, tokenId ) // Return the account address return(0x6c, 0x20) } // Otherwise, return the computed account address mstore(0x00, shr(96, shl(96, computed))) return(0x00, 0x20) } } function account( address implementation, bytes32 salt, uint256 chainId, address tokenContract, uint256 tokenId ) external view returns (address) { assembly { // Silence unused variable warnings pop(chainId) pop(tokenContract) pop(tokenId) // Copy bytecode + constant data to memory calldatacopy(0x8c, 0x24, 0x80) // salt, chainId, tokenContract, tokenId mstore(0x6c, 0x5af43d82803e903d91602b57fd5bf3) // ERC-1167 footer mstore(0x5d, implementation) // implementation mstore(0x49, 0x3d60ad80600a3d3981f3363d3d373d3d3d363d73) // ERC-1167 constructor + header // Copy create2 computation data to memory mstore(0x35, keccak256(0x55, 0xb7)) // keccak256(bytecode) mstore(0x15, salt) // salt mstore(0x01, shl(96, address())) // registry address mstore8(0x00, 0xff) // 0xFF // Store computed account address in memory mstore(0x00, shr(96, shl(96, keccak256(0x00, 0x55)))) // Return computed account address return(0x00, 0x20) } } }</code></pre>Security Considerations</h2> Fraud Prevention</h3> In order to enable trustless sales of token bound accounts, decentralized marketplaces will need to implement safeguards against fraudulent behavior by malicious account owners. Consider the following potential scam: Alice owns an ERC-721 token X, which owns token bound account Y.</li> Alice deposits 10ETH into account Y</li> Bob offers to purchase token X for 11ETH via a decentralized marketplace, assuming he will receive the 10ETH stored in account Y along with the token</li> Alice withdraws 10ETH from the token bound account, and immediately accepts Bob's offer</li> Bob receives token X, but account Y is empty</li> </ul> To mitigate fraudulent behavior by malicious account owners, decentralized marketplaces SHOULD implement protection against these sorts of scams at the marketplace level. Contracts which implement this EIP MAY also implement certain protections against fraudulent behavior. Here are a few mitigations strategies to be considered: Attach the current token bound account state to the marketplace order. If the state of the account has changed since the order was placed, consider the offer void. This functionality would need to be supported at the marketplace level.</li> Attach a list of asset commitments to the marketplace order that are expected to remain in the token bound account when the order is fulfilled. If any of the committed assets have been removed from the account since the order was placed, consider the offer void. This would also need to be implemented by the marketplace.</li> Submit the order to the decentralized market via an external smart contract which performs the above logic before validating the order signature. This allows for safe transfers to be implemented without marketplace support.</li> Implement a locking mechanism on the token bound account implementation that prevents malicious owners from extracting assets from the account while locked</li> </ul> Preventing fraud is outside the scope of this proposal. Ownership Cycles</h3> All assets held in a token bound account may be rendered inaccessible if an ownership cycle is created. The simplest example is the case of an ERC-721 token being transferred to its own token bound account. If this occurs, both the ERC-721 token and all of the assets stored in the token bound account would be permanently inaccessible, since the token bound account is incapable of executing a transaction which transfers the ERC-721 token. Ownership cycles can be introduced in any graph of n>0 token bound accounts. On-chain prevention of cycles with depth>1 is difficult to enforce given the infinite search space required, and as such is outside the scope of this proposal. Application clients and account implementations wishing to adopt this proposal are encouraged to implement measures that limit the possibility of ownership cycles. Copyright</h2> Copyright and related rights waived via CC0</a>. Contract clock 2023-01-25T00:00:00+00:00 Abstract</h2> Many contracts rely on some clock for enforcing delays and storing historical data. While some contracts rely on block numbers, others use timestamps. There is currently no easy way to discover which time-tracking function a contract internally uses. This EIP proposes to standardize an interface for contracts to expose their internal clock and thus improve composability and interoperability. Motivation</h2> Many contracts check or store time-related information. For example, timelock contracts enforce a delay before an operation can be executed. Similarly, DAOs enforce a voting period during which stakeholders can approve or reject a proposal. Last but not least, voting tokens often store the history of voting power using timed snapshots. Some contracts do time tracking using timestamps while others use block numbers. In some cases, more exotic functions might be used to track time. There is currently no interface for an external observer to detect which clock a contract uses. This seriously limits interoperability and forces devs to make risky assumptions. 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. Compliant contracts MUST implement the clock</code> and CLOCK_MODE</code> functions as specified below. interface IERC6372 { function clock() external view returns (uint48); function CLOCK_MODE() external view returns (string); }</code></pre>Methods</h3> clock</h4> This function returns the current timepoint according to the mode the contract is operating on. It MUST be a non-decreasing function of the chain, such as block.timestamp</code> or block.number</code>. - name: clock type: function stateMutability: view inputs: [] outputs: - name: timepoint type: uint48</code></pre>CLOCK_MODE</h4> This function returns a machine-readable string description of the clock the contract is operating on. This string MUST be formatted like a URL query string (a.k.a. application/x-www-form-urlencoded</code>), decodable in standard JavaScript with new URLSearchParams(CLOCK_MODE)</code>. If operating using block number: If the block number is that of the NUMBER</code> opcode (0x43</code>), then this function MUST return mode=blocknumber&from=default</code>.</li> If it is any other block number, then this function MUST return mode=blocknumber&from=<CAIP-2-ID></code>, where <CAIP-2-ID></code> is a CAIP-2 Blockchain ID such as eip155:1</code>.</li> </ul> </li> If operating using timestamp, then this function MUST return mode=timestamp</code>.</li> If operating using any other mode, then this function SHOULD return a unique identifier for the encoded mode</code> field.</li> </ul> - name: CLOCK_MODE type: function stateMutability: view inputs: [] outputs: - name: descriptor type: string</code></pre>Expected properties</h3> The clock()</code> function MUST be non-decreasing.</li> </ul> Rationale</h2> clock</code> returns uint48</code> as it is largely sufficient for storing realistic values. In timestamp mode, uint48</code> will be enough until the year 8921556. Even in block number mode, with 10,000 blocks per second, it would be enough until the year 2861. Using a type smaller than uint256</code> allows storage packing of timepoints with other associated values, greatly reducing the cost of writing and reading from storage. Depending on the evolution of the blockchain (particularly layer twos), using a smaller type, such as uint32</code> might cause issues fairly quickly. On the other hand, anything bigger than uint48</code> appears wasteful. In addition to timestamps, it is sometimes necessary to define durations or delays, which are a difference between timestamps. In the general case, we would expect these values to be represented with the same type than timepoints (uint48</code>). However, we believe that in most cases uint32</code> is a good alternative, as it represents over 136 years if the clock operates using seconds. In most cases, we recommend using uint48</code> for storing timepoints and using uint32</code> for storing durations. That recommendation applies to "reasonable" durations (delay for a timelock, voting or vesting duration, ...) when operating with timestamps or block numbers that are more than 1 second apart. Security Considerations</h2> No known security issues. Copyright</h2> Copyright and related rights waived via CC0</a>. Cross-Chain Token States Synchronization 2023-01-17T00:00:00+00:00 Abstract</h2> This ERC standardizes an interface for contract-layer consensus-agnostic verifiable cross-chain bridging, through which we can define a new global token inherited from ERC-20</a>/ERC-721</a> over multi-chains. Figure.1 Architecture</h3> With this ERC, we can create a global token protocol, that leverages smart contracts or similar mechanisms on existing blockchains to record the token states synchronously. The synchronization could be made by trustless off-chain synchronizers. Motivation</h2> The current paradigm of token bridges makes assets fragment.</li> If ETH was transferred to another chain through the current token bridge, if the chain broke down, ETH will be lost for users.</li> </ul> The core of this ERC is synchronization instead of transferring, even if all the other chains break down, as long as Ethereum is still running, user’s assets will not be lost. The fragment problem will be solved.</li> The security of users' multi-chain assets can be greatly enhanced.</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. Omniverse Account</h3> There SHOULD be a global user identifier of this ERC, which is RECOMMENDED to be referred to as Omniverse Account (o-account</code> for short) in this article. The o-account</code> is RECOMMENDED to be expressed as a public key created by the elliptic curve secp256k1</code>. A mapping mechanism</a> is RECOMMENDED for different environments. Data Structure</h3> An Omniverse Transaction (o-transaction</code> for short) MUST be described with the following data structure: /** * @notice Omniverse transaction data structure * @member nonce: The number of the o-transactions. If the current nonce of an omniverse account is `k`, the valid nonce of this o-account in the next o-transaction is `k+1`. * @member chainId: The chain where the o-transaction is initiated * @member initiateSC: The contract address from which the o-transaction is first initiated * @member from: The Omniverse account which signs the o-transaction * @member payload: The encoded business logic data, which is maintained by the developer * @member signature: The signature of the above informations. */ struct ERC6358TransactionData { uint128 nonce; uint32 chainId; bytes initiateSC; bytes from; bytes payload; bytes signature; }</code></pre> The data structure ERC6358TransactionData</code> MUST be defined as above. </li> The member nonce</code> MUST be defined as uint128</code> due to better compatibility for more tech stacks of blockchains. </li> The member chainId</code> MUST be defined as uint32</code>. </li> The member initiateSC</code> MUST be defined as bytes</code>. </li> The member from</code> MUST be defined as bytes</code>. </li> The member payload</code> MUST be defined as bytes</code>. It is encoded from a user-defined data related to the o-transaction. For example: For fungible tokens it is RECOMMENDED as follows: /** * @notice Fungible token data structure, from which the field `payload` in `ERC6358TransactionData` will be encoded @member op: The operation type * NOTE op: 0-31 are reserved values, 32-255 are custom values * op: 0 - omniverse account `from` transfers `amount` tokens to omniverse account `exData`, `from` have at least `amount` tokens * op: 1 - omniverse account `from` mints `amount` tokens to omniverse account `exData` * op: 2 - omniverse account `from` burns `amount` tokens from his own, `from` have at least `amount` tokens * @member exData: The operation data. This sector could be empty and is determined by `op`. For example: when `op` is 0 and 1, `exData` stores the omniverse account that receives. when `op` is 2, `exData` is empty. * @member amount: The amount of tokens being operated */ struct Fungible { uint8 op; bytes exData; uint256 amount; }</code></pre> The related raw data for signature</code> in o-transaction</code> is RECOMMENDED to be the concatenation of the raw bytes of op</code>, exData</code>, and amount</code>.</li> </ul> </li> For non-fungible tokens it is RECOMMENDED as follows: /** * @notice Non-Fungible token data structure, from which the field `payload` in `ERC6358TransactionData` will be encoded @member op: The operation type * NOTE op: 0-31 are reserved values, 32-255 are custom values * op: 0 omniverse account `from` transfers token `tokenId` to omniverse account `exData`, `from` have the token with `tokenId` * op: 1 omniverse account `from` mints token `tokenId` to omniverse account `exData` * op: 2 omniverse account `from` burns token `tokenId`, `from` have the token with `tokenId` * @member exData: The operation data. This sector could be empty and is determined by `op` * when `op` is 0 and 1, `exData` stores the omniverse account that receives. when `op` is 2, `exData` is empty. * @member tokenId: The tokenId of the non-fungible token being operated */ struct NonFungible { uint8 op; bytes exData; uint256 tokenId; }</code></pre> The related raw data for signature</code> in o-transaction</code> is RECOMMENDED to be the concatenation of the raw bytes of op</code>, exData</code>, and tokenId</code>.</li> </ul> </li> </ul> </li> The member signature</code> MUST be defined as bytes</code>. It is RECOMMENDED to be created as follows. It is OPTIONAL that concating the sectors in ERC6358TransactionData</code> as below (take Fungible token for example) and calculate the hash with keccak256</code>: /** * @notice Decode `_data` from bytes to Fungible * @return A `Fungible` instance */ function decodeData(bytes memory _data) internal pure returns (Fungible memory) { (uint8 op, bytes memory exData, uint256 amount) = abi.decode(_data, (uint8, bytes, uint256)); return Fungible(op, exData, amount); } /** * @notice Get the hash of a transaction * @return Hash value of the raw data of an `ERC6358TransactionData` instance */ function getTransactionHash(ERC6358TransactionData memory _data) public pure returns (bytes32) { Fungible memory fungible = decodeData(_data.payload); bytes memory payload = abi.encodePacked(fungible.op, fungible.exData, fungible.amount); bytes memory rawData = abi.encodePacked(_data.nonce, _data.chainId, _data.initiateSC, _data.from, payload); return keccak256(rawData); }</code></pre></li> It is OPTIONAL that encapsulating the sectors in ERC6358TransactionData</code> according to EIP-712</code>. </li> Sign the hash value. </li> </ul> </li> </ul> Smart Contract Interface</h3> Every ERC-6358</a> compliant contract MUST implement the IERC6358</code> /** * @notice Interface of the ERC-6358 */ interface IERC6358 { /** * @notice Emitted when a o-transaction which has nonce `nonce` and was signed by user `pk` is sent by calling {sendOmniverseTransaction} */ event TransactionSent(bytes pk, uint256 nonce); /** * @notice Sends an `o-transaction` * @dev * Note: MUST implement the validation of the `_data.signature` * Note: A map maintaining the `o-account` and the related transaction nonce is RECOMMENDED * Note: MUST implement the validation of the `_data.nonce` according to the current account nonce * Note: MUST implement the validation of the `_data. payload` * Note: This interface is just for sending an `o-transaction`, and the execution MUST NOT be within this interface * Note: The actual execution of an `o-transaction` is RECOMMENDED to be in another function and MAY be delayed for a time * @param _data: the `o-transaction` data with type {ERC6358TransactionData} * See more information in the definition of {ERC6358TransactionData} Emit a {TransactionSent} event */ function sendOmniverseTransaction(ERC6358TransactionData calldata _data) external; /** * @notice Get the number of omniverse transactions sent by user `_pk`, * which is also the valid `nonce` of a new omniverse transactions of user `_pk` * @param _pk: Omniverse account to be queried * @return The number of omniverse transactions sent by user `_pk` */ function getTransactionCount(bytes memory _pk) external view returns (uint256); /** * @notice Get the transaction data `txData` and timestamp `timestamp` of the user `_use` at a specified nonce `_nonce` * @param _user Omniverse account to be queried * @param _nonce The nonce to be queried * @return Returns the transaction data `txData` and timestamp `timestamp` of the user `_use` at a specified nonce `_nonce` */ function getTransactionData(bytes calldata _user, uint256 _nonce) external view returns (ERC6358TransactionData memory, uint256); /** * @notice Get the chain ID * @return Returns the chain ID */ function getChainId() external view returns (uint32); }</code></pre> The sendOmniverseTransaction</code> function MAY be implemented as public</code> or external</code></li> The getTransactionCount</code> function MAY be implemented as public</code> or external</code></li> The getTransactionData</code> function MAY be implemented as public</code> or external</code></li> The getChainId</code> function MAY be implemented as pure</code> or view</code></li> The TransactionSent</code> event MUST be emitted when sendOmniverseTransaction</code> function is called</li> </ul> </li> Optional Extension: Fungible Token // import "{IERC6358.sol}"; /** * @notice Interface of the ERC-6358 fungible token, which inherits {IERC6358} */ interface IERC6358Fungible is IERC6358 { /** * @notice Get the omniverse balance of a user `_pk` * @param _pk `o-account` to be queried * @return Returns the omniverse balance of a user `_pk` */ function omniverseBalanceOf(bytes calldata _pk) external view returns (uint256); }</code></pre> The omniverseBalanceOf</code> function MAY be implemented as public</code> or external</code></li> </ul> </li> Optional Extension: NonFungible Token import "{IERC6358.sol}"; /** * @notice Interface of the ERC-6358 non fungible token, which inherits {IERC6358} */ interface IERC6358NonFungible is IERC6358 { /** * @notice Get the number of omniverse NFTs in account `_pk` * @param _pk `o-account` to be queried * @return Returns the number of omniverse NFTs in account `_pk` */ function omniverseBalanceOf(bytes calldata _pk) external view returns (uint256); /** * @notice Get the owner of an omniverse NFT with `tokenId` * @param _tokenId Omniverse NFT id to be queried * @return Returns the owner of an omniverse NFT with `tokenId` */ function omniverseOwnerOf(uint256 _tokenId) external view returns (bytes memory); }</code></pre> The omniverseBalanceOf</code> function MAY be implemented as public</code> or external</code></li> The omniverseOwnerOf</code> function MAY be implemented as public</code> or external</code></li> </ul> </li> </ul> Rationale</h2> Architecture</h3> As shown in Figure.1</a>, smart contracts deployed on multi-chains execute o-transactions</code> of ERC-6358 tokens synchronously through the trustless off-chain synchronizers. The ERC-6358 smart contracts are referred to as Abstract Nodes. The states recorded by the Abstract Nodes that are deployed on different blockchains respectively could be considered as copies of the global state, and they are ultimately consistent.</li> Synchronizer is an off-chain execution program responsible for carrying published o-transactions</code> from the ERC-6358 smart contracts on one blockchain to the others. The synchronizers work trustless as they just deliver o-transactions</code> with others' signatures, and details could be found in the workflow</a>.</li> </ul> Principle</h3> The o-account</code> has been mentioned above</a>. </li> The synchronization of the o-transactions</code> guarantees the ultimate consistency of token states across all chains. The related data structure is here</a>. A nonce</code> mechanism is brought in to make the states consistent globally.</li> The nonce</code> appears in two places, the one is nonce in o-transaction</code> data structure, and the other is account nonce</code> maintained by on-chain ERC-6358 smart contracts.</li> When synchronizing, the nonce in o-transaction</code> data will be checked by comparing it to the account nonce</code>.</li> </ul> </li> </ul> Workflow</h4> Suppose a common user A</code> and her related operation account nonce</code> is $k$.</li> A</code> initiates an o-transaction</code> on Ethereum by calling IERC6358::sendOmniverseTransaction</code>. The current account nonce</code> of A</code> in the ERC-6358 smart contracts deployed on Ethereum is $k$ so the valid value of nonce in o-transaction</code> needs to be $k+1$.</li> The ERC-6358 smart contracts on Ethereum verify the signature of the o-transaction</code> data. If the verification succeeds, the o-transaction</code> data will be published by the smart contracts on the Ethereum side. The verification includes: whether the balance (FT) or the ownership (NFT) is valid</li> and whether the nonce in o-transaction</code> is $k+1$</li> </ul> </li> The o-transaction</code> SHOULD NOT be executed on Ethereum immediately, but wait for a time.</li> Now, A</code>'s latest submitted nonce in o-transaction</code> on Ethereum is $k+1$, but still $k$ on other chains.</li> The off-chain synchronizers will find a newly published o-transaction</code> on Ethereum but not on other chains.</li> Next synchronizers will rush to deliver this message because of a rewarding mechanism. (The strategy of the reward could be determined by the deployers of ERC-6358 tokens. For example, the reward could come from the service fee or a mining mechanism.)</li> Finally, the ERC-6358 smart contracts deployed on other chains will all receive the o-transaction</code> data, verify the signature and execute it when the waiting time is up.</li> After execution, the account nonce</code> on all chains will add 1. Now all the account nonce</code> of account A</code> will be $k+1$, and the state of the balances of the related account will be the same too.</li> </ul> Reference Implementation</h2> Omniverse Account</h3> An Omniverse Account example: 3092860212ceb90a13e4a288e444b685ae86c63232bcb50a064cb3d25aa2c88a24cd710ea2d553a20b4f2f18d2706b8cc5a9d4ae4a50d475980c2ba83414a796</code> The Omniverse Account is a public key of the elliptic curve secp256k1</code></li> The related private key of the example is: cdfa0e50d672eb73bc5de00cc0799c70f15c5be6b6fca4a1c82c35c7471125b6</code></li> </ul> </li> </ul> Mapping Mechanism for Different Environments</h4> In the simplest implementation, we can just build two mappings to get it. One is like pk based on sece256k1 => account address in the special environment</code>, and the other is the reverse mapping. The Account System</code> on Flow</code> is a typical example. Flow</code> has a built-in mechanism for account address => pk</code>. The public key can be bound to an account (a special built-in data structure) and the public key can be got from the account address</code> directly.</li> A mapping from pk</code> to the account address</code> on Flow can be built by creating a mapping {String: Address}</code>, in which String</code> denotes the data type to express the public key and the Address</code> is the data type of the account address</code> on Flow.</li> </ul> ERC-6358 Token</h3> The ERC-6358 Token could be implemented with the interfaces mentioned above</a>. It can also be used with the combination of ERC-20</a>/ERC-721</a>. The implementation examples of the interfaces can be found at: Interface IERC6358</code></a>, the basic ERC-6358 interface mentioned above</a></li> Interface IERC6358Fungible</code></a>, the interface for ERC-6358 fungible token</li> Interface IERC6358NonFungible</code></a>, the interface for ERC-6358 non-fungible token</li> </ul> </li> The implementation example of some common tools to operate ERC-6358 can be found at: Common Tools</a>.</li> </ul> </li> The implementation examples of ERC-6358 Fungible Token and ERC-6358 Non-Fungible Token can be found at: ERC-6358 Fungible Token Example</a></li> ERC-6358 Non-Fungible Token Example</a></li> </ul> </li> </ul> Security Considerations</h2> Attack Vector Analysis</h3> According to the above, there are two roles: common users are who initiate an o-transaction</code></li> synchronizers are who just carry the o-transaction</code> data if they find differences between different chains.</li> </ul> The two roles might be where the attack happens: Will the synchronizers cheat?</h4> Simply speaking, it's none of the synchronizer's business as they cannot create other users' signatures unless some common users tell him, but at this point, we think it's a problem with the role common user. </li> The synchronizer has no will and cannot do evil because the o-transaction</code> data that they deliver is verified by the related signature of other common users. </li> The synchronizers would be rewarded as long as they submit valid o-transaction</code> data, and valid only means that the signature and the amount are both valid. This will be detailed and explained later when analyzing the role of common user. </li> The synchronizers will do the delivery once they find differences between different chains: If the current account nonce</code> on one chain is smaller than a published nonce in o-transaction</code> on another chain</li> If the transaction data related to a specific nonce in o-transaction</code> on one chain is different from another published o-transaction</code> data with the same nonce in o-transaction</code> on another chain</li> </ul> </li> Conclusion: The synchronizers won't cheat because there are no benefits and no way for them to do so. </li> </ul> Will the common user cheat?</h4> Simply speaking, maybe they will, but fortunately, they can't succeed. </li> Suppose the current account nonce</code> of a common user A</code> is $k$ on all chains. A</code> has 100 token X</code>, which is an instance of the ERC-6358 token. </li> Common user A</code> initiates an o-transaction</code> on a Parachain of Polkadot first, in which A</code> transfers 10</code> X</code>s to an o-account</code> of a common user B</code>. The nonce in o-transaction</code> needs to be $k+1$. After signature and data verification, the o-transaction</code> data(ot-P-ab</code> for short) will be published on Polkadot. </li> At the same time, A</code> initiates an o-transaction</code> with the same nonce $k+1$ but different data(transfer 10</code> X</code>s to another o-account</code> C</code> for example) on Ethereum. This o-transaction</code> (named ot-E-ac</code> for short) will pass the verification on Ethereum first, and be published. </li> At this point, it seems A</code> finished a double spend attack and the states on Polkadot and Ethereum are different. </li> Response strategy: As we mentioned above, the synchronizers will deliver ot-P-ab</code> to Ethereum and deliver ot-E-ac</code> to Polkadot because they are different although with the same nonce. The synchronizer who submits the o-transaction</code> first will be rewarded as the signature is valid.</li> Both the ERC-6358 smart contracts or similar mechanisms on Polkadot and Ethereum will find that A</code> did cheating after they received both ot-E-ac</code> and ot-P-ab</code> respectively as the signature of A</code> is non-deniable.</li> We have mentioned that the execution of an o-transaction</code> will not be done immediately and instead there needs to be a fixed waiting time. So the double spend attack</code> caused by A</code> won't succeed.</li> There will be many synchronizers waiting for delivering o-transactions to get rewards. So although it's almost impossible that a common user can submit two o-transactions</code> to two chains, but none of the synchronizers deliver the o-transactions</code> successfully because of a network problem or something else, we still provide a solution: The synchronizers will connect to several native nodes of every public chain to avoid the malicious native nodes.</li> If it indeed happened that all synchronizers' network break, the o-transactions</code> will be synchronized when the network recovered. If the waiting time is up and the cheating o-transaction</code> has been executed, we are still able to revert it from where the cheating happens according to the nonce in o-transaction</code> and account nonce</code>.</li> </ul> </li> </ul> </li> A</code> couldn't escape punishment in the end (For example, lock his account or something else, and this is about the certain tokenomics determined by developers according to their own situation). </li> Conclusion: The common user maybe cheat but won't succeed. </li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>. ERC-2771 Namespaced Account Abstraction 2023-01-11T00:00:00+00:00 Abstract</h2> ERC-2771</a> is a prevalent standard for handling meta-transactions via trusted forwarders. This EIP proposes an extension to ERC-2771</a> to introduce a namespacing mechanism, facilitating trustless account abstraction through per-forwarder namespaced addresses. 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. The key words "Forwarder" and "Recipient" in this document are to be interpreted as described in ERC-2771</a>. Namespaced Forwarder Interface</h3> pragma solidity ^0.8.0; interface INamespacedForwarder { function isNamespacedTransaction() external view returns (bool); }</code></pre>Determining the Sender and Forwarder</h3> Upon function invocation on a Recipient, the Recipient MUST execute a STATICCALL</code> to the isNamespacedTransaction()</code> method of the caller. If this operation reverts or returns the boolean value false</code>, the transaction MUST proceed normally, identifying the caller as the sender, and the Forwarder as the zero address. However, if the boolean value true</code> is returned, the transaction is acknowledged as a namespaced transaction, with the sender identified using the procedure outlined in ERC-2771</a>, and the Forwarder identified as the caller. Recipient Extensions</h3> Whenever a Recipient contract has a function with one or more function parameters of type address, it MUST also provide a new function, mirroring the name of the original function but appending Namespaced</code> at the end, which accepts two addresses instead. The initial address denotes the Forwarder, while the latter represents the address managed by that Forwarder. If a function accepts multiple address parameters (e.g., ERC-20</a>'s transferFrom</code>), a version of the function accepting two addresses per original address parameter MUST be provided. The original function MUST exhibit identical behavior to the new function when Forwarder addresses are the zero address. For instance, ERC-20</a> would be extended with these functions: function transferNamespaced(address toForwarder, address toAddress, uint256 amount); function approveNamespaced(address spenderForwarder, address spenderAddress, uint256 amount); function transferFromNamespaced(address fromForwarder, address fromAddress, address toForwarder, address toAddress, uint256 amount);</code></pre>ERC-165</a></h4> Recipient contracts MUST implement ERC-165. When an ERC-165 interface ID is registered, a second interface ID corresponding to the XOR of the Namespaced function selectors of the original interface must also be registered. Rationale</h2> The approach of simply augmenting existing EIP functions with new address</code> parameters, rather than crafting new interfaces for the most commonly used EIPs, is employed to ensure broader applicability of this namespacing proposal. Backwards Compatibility</h2> Contracts already deployed cannot not benefit from this namespacing proposal. This limitation also extends to ERC-2771. Using this EIP in standards</h3> When using this EIP in another standard, both the original and the Namespaced interface IDs SHOULD be provided. Interfaces MUST NOT include namespaced versions of functions in their interfaces. Security Considerations</h2> This proposal alters trust dynamics: Forwarders no longer require Recipient trust, but instead require the trust of their users. Copyright</h2> Copyright and related rights waived via CC0</a>. Universal Token Router 2022-12-12T00:00:00+00:00 Abstract</h2> The default transaction behavior of ETH is transfer-and-call, but the widely used ERC-20</a> standard isn't compatible with this pattern. This incompatibility forces applications to use an inefficient and risky two-step approve-then-call process. This approach is costly, creates a poor user experience, and introduces significant security vulnerabilities, as users must approve unaudited and often upgradable contracts. This has led to numerous allowance-related bugs and exploits. The Universal Token Router (UTR) addresses this issue by separating the token allowance from the application logic. This allows any token to be spent in a single contract call, similar to how ETH is handled, without needing to approve individual application contracts. When tokens are approved to the UTR, they can only be spent in transactions signed directly by the token owner. The UTR's transaction data clearly shows key details like token types, amounts, and the recipient. The UTR promotes the security-by-result model over the security-by-process model. By allowing applications to verify the output of a transaction (e.g., checking token balance changes), users' funds can be secure even when interacting with potentially flawed or malicious contracts. The UTR contract is deployed at 0x69c4620b62D99f524c5B4dE45442FE2D7dD59576</code> on all EVM-compatible networks using the EIP-1014</a> SingletonFactory. This allows new token contracts to pre-configure it as a trusted spender, eliminating the need for approval transactions entirely for their interactive usage. Motivation</h2> When users approve their tokens to a contract, they expect that: it only spends the tokens with their permission (from msg.sender</code> or ecrecover</code>)</li> it does not use delegatecall</code> (e.g. upgradable proxies)</li> </ul> The UTR ensures these same security conditions, allowing all interactive applications to share a single, secure token allowance. This saves most approval transactions for existing tokens and all approval transactions for new ones. Before the UTR, users had to blindly trust the front-end code of applications to construct transactions honestly. This made them highly vulnerable to phishing. The UTR's function arguments act as a manifest that wallets can display to users, allowing them to review the expected token behavior before signing, making phishing attacks much easier to detect. Most existing application contracts are already compatible with the UTR and can integrate it to gain several benefits: Securely share a user's token allowance across all applications.</li> Update their own peripheral contracts as often as needed without requiring new user approvals.</li> Save development and security audit costs on their own router contracts.</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. The main interface of the UTR contract: interface IUniversalTokenRouter { function exec( Output[] memory outputs, Action[] memory actions ) payable; }</code></pre>Output Verification</h3> Output</code> defines the expected token balance change for verification. struct Output { address recipient; uint eip; // token standard: 0 for ETH or EIP number address token; // token contract address uint id; // token id for ERC-721 and ERC-1155 uint amountOutMin; }</code></pre> Token balances of the recipient</code> address are recorded at the beginning and the end of the exec</code> function for each item in outputs</code>. Transaction will revert with INSUFFICIENT_OUTPUT_AMOUNT</code> if any of the balance changes are less than its amountOutMin</code>. A special id ERC_721_BALANCE</code> is reserved for ERC-721</a>, which can be used in output actions to verify the total amount of all ids owned by the recipient</code> address. ERC_721_BALANCE = keccak256('UniversalTokenRouter.ERC_721_BALANCE')</code></pre>Action</h3> Action</code> defines the token inputs and the contract call. struct Action { Input[] inputs; address code; // contract code address bytes data; // contract input data }</code></pre> The action code contract MUST implement the NotToken</code> contract or the ERC-165</a> interface with the ID 0x61206120</code> in order to be called by the UTR. This interface check prevents the direct invocation of token allowance-spending functions (e.g., transferFrom</code>) by the UTR. Therefore, new token contracts MUST NOT implement this interface ID. /** * This contract will conflict with the ERC20, ERC721, and ERC1155 standards, * preventing token contracts from accidentally implementing it. */ abstract contract NotToken { function allowance(address, address) external pure returns (string memory) { return "THIS IS NOT A TOKEN"; } function isApprovedForAll(address, address) external pure returns (string memory) { return "THIS IS NOT A TOKEN"; } } contract Application is NotToken { // this contract can be used with the UTR }</code></pre>Input</h3> Input</code> defines the input token to transfer or prepare before the action contract is executed. struct Input { uint mode; address recipient; uint eip; // token standard: 0 for ETH or EIP number address token; // token contract address uint id; // token id for ERC-721 and ERC-1155 uint amountIn; }</code></pre> mode</code> takes one of the following values: PAYMENT = 0</code>: pend a payment for the token to be transferred from msg.sender</code> to the recipient</code> by calling UTR.pay</code> from anywhere in the same transaction.</li> TRANSFER = 1</code>: transfer the token directly from msg.sender</code> to the recipient</code>.</li> CALL_VALUE = 2</code>: record the ETH</code> amount to pass to the action as the call value</code>.</li> </ul> Each input in the inputs</code> argument is processed sequentially. For simplicity, duplicated PAYMENT</code> and CALL_VALUE</code> inputs are valid, but only the last amountIn</code> value is used. Payment Input</h4> PAYMENT</code> is the recommended mode for application contracts that use the transfer-in-callback pattern. E.g., flashloan contracts, Uniswap/v3-core, Derion, etc. For each Input</code> with PAYMENT</code> mode, at most amountIn</code> of the token can be transferred from msg.sender</code> to the recipient</code> by calling UTR.pay</code> from anywhere in the same transaction. UTR | | PAYMENT | (payments pended for UTR.pay) | | Application Contracts action.code.call ---------------------> | | UTR.pay <----------------------- (call) | | | <-------------------------- (return) | | | (clear all pending payments) | END</code></pre> Token's allowance and PAYMENT</code> are essentially different as: allowance: allow a specific spender</code> to transfer the token to anyone at any time.</li> PAYMENT</code>: allow anyone to transfer the token to a specific recipient</code> only in that transaction.</li> </ul> Spend Payment</h5> interface IUniversalTokenRouter { function pay(bytes memory payment, uint amount); }</code></pre> To call pay</code>, the payment</code> param must be encoded as follows: payment = abi.encode( payer, // address recipient, // address eip, // uint256 token, // address id // uint256 );</code></pre> The payment</code> bytes can also be used by adapter UTR contracts to pass contexts and payloads for performing custom payment logic. Discard Payment</h5> Sometimes, it's useful to discard the payment instead of performing the transfer, for example, when the application contract wants to burn its own token from payment.payer</code>. The following function can be used to verify the payment to the caller's address and discard a portion of it. interface IUniversalTokenRouter { function discard(bytes memory payment, uint amount); }</code></pre> Please refer to the Discard Payment</a> section in the Security Considerations for an important security note. Sender Authentication</h5> Discarding payment also makes sender authentication possible with a router, which is never achievable with regular routers. By inputting a pseudo payment (not a token payment), the UTR allows the target contract to verify the sender's address for authentication, along with normal token transfers and payments. contract AuthChecker is NotToken { // must be trusted with a proper implementation of discard function address immutable UTR; function actionMustSentBySender(address sender) external { bytes memory payment = abi.encode(sender, address(this), 0, address(0), 0); IUniversalTokenRouter(UTR).discard(payment, 1); } }</code></pre>await utr.exec([], [{ inputs: [{ mode: PAYMENT, eip: 0, token: AddressZero, id: 0, amountIn: 1, recipient: paymentTest.address, }], code: authChecker.address, data: (await authChecker.populateTransaction.actionMustSentBySender(owner.address)).data, }])</code></pre> Please refer to the Discard Payment</a> section in the Security Considerations for an important security note. Payment Lifetime</h5> Payments are recorded in the UTR storage and intended to be spent by input.action</code> external calls only within that transaction. All payment storages will be cleared before the UTR.exec</code> ends. Native Token Tranfer</h3> The UTR</code> SHOULD have a receive()</code> function for user execution logic that requires transferring ETH in. The msg.value</code> transferred into the router can be spent in multiple inputs across different actions. While the caller takes full responsibility for the movement of ETH</code> in and out of the router, the exec</code> function SHOULD refund any remaining ETH</code> before the function ends. Please refer to the Reentrancy</a> section in the Security Considerations for information on reentrancy risks and mitigation. Usage Examples</h3> Uniswap V2 Router</h4> Legacy function: UniswapV2Router01.swapExactTokensForTokens( uint amountIn, uint amountOutMin, address[] calldata path, address to, uint deadline )</code></pre> UniswapV2Helper01.swapExactTokensForTokens</code> is a modified version of it without the token transfer part. This transaction is signed by users to execute the swap instead of the legacy function: UniversalTokenRouter.exec([{ recipient: to, eip: 20, token: path[path.length-1], id: 0, amountOutMin, }], [{ inputs: [{ mode: TRANSFER, recipient: UniswapV2Library.pairFor(factory, path[0], path[1]), eip: 20, token: path[0], id: 0, amountIn: amountIn, }], code: UniswapV2Helper01.address, data: encodeFunctionData("swapExactTokensForTokens", [ amountIn, amountOutMin, path, to, deadline, ]), }])</code></pre>Uniswap V3 Router</h4> Legacy router contract: contract SwapRouter { // this function is called by pool to pay the input tokens function pay( address token, address payer, address recipient, uint256 value ) internal { ... // pull payment TransferHelper.safeTransferFrom(token, payer, recipient, value); } }</code></pre> The helper contract to use with the UTR</code>: contract SwapHelper { // this function is called by pool to pay the input tokens function pay( address token, address payer, address recipient, uint256 value ) internal { ... // pull payment bytes memory payment = abi.encode(payer, recipient, 20, token, 0); UTR.pay(payment, value); } }</code></pre> This transaction is signed by users to execute the exactInput</code> functionality using PAYMENT</code> mode: UniversalTokenRouter.exec([{ eip: 20, token: tokenOut, id: 0, amountOutMin: 1, recipient: to, }], [{ inputs: [{ mode: PAYMENT, eip: 20, token: tokenIn, id: 0, amountIn: amountIn, recipient: pool.address, }], code: SwapHelper.address, data: encodeFunctionData("exactInput", [...]), }])</code></pre>Allowance Adapter</h4> A simple non-reentrancy ERC-20 adapter for aplication and router contracts that use direct allowance. contract AllowanceAdapter is ReentrancyGuard { struct Input { address token; uint amountIn; } function approveAndCall( Input[] memory inputs, address spender, bytes memory data, address leftOverRecipient ) external payable nonReentrant { for (uint i = 0; i < inputs.length; ++i) { Input memory input = inputs[i]; IERC20(input.token).approve(spender, input.amountIn); } (bool success, bytes memory result) = spender.call{value: msg.value}(data); if (!success) { assembly { revert(add(result, 32), mload(result)) } } for (uint i = 0; i < inputs.length; ++i) { Input memory input = inputs[i]; // clear all allowance IERC20(input.token).approve(spender, 0); uint leftOver = IERC20(input.token).balanceOf(address(this)); if (leftOver > 0) { TransferHelper.safeTransfer(input.token, leftOverRecipient, leftOver); } } } }</code></pre> This transaction is constructed to utilize the UTR</code> to interact with Uniswap V2 Router without approving any token to it: const { data: routerData } = await uniswapRouter.populateTransaction.swapExactTokensForTokens( amountIn, amountOutMin, path, to, deadline, ) const { data: adapterData } = await adapter.populateTransaction.approveAndCall( [{ token: path[0], amountIn, }], uniswapRouter.address, routerData, leftOverRecipient, ) await utr.exec([], [{ inputs: [{ mode: TRANSFER, recipient: adapter.address, eip: 20, token: path[0], id: 0, amountIn, }], code: adapter.address, data: adapterData, }])</code></pre>Rationale</h2> The Permit</code> type signature is not supported since the purpose of the Universal Token Router is to eliminate all interactive approve</code> signatures for new tokens, and most for old tokens. Backwards Compatibility</h2> Tokens</h3> Old token contracts (ERC-20, ERC-721 and ERC-1155</a>) require approval for the Universal Token Router once for each account. New token contracts can pre-configure the Universal Token Router as a trusted spender, and no approval transaction is required for interactive usage. import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; /** * @dev Implementation of the {ERC20} token standard that support a trusted ERC6120 contract as an unlimited spender. */ contract ERC20WithUTR is ERC20 { address immutable UTR; /** * @dev Sets the values for {name}, {symbol} and ERC6120's {utr} address. All three of these values are immutable: they can only be set once during * construction. @param utr can be zero to disable trusted ERC6120 support. */ constructor(string memory name, string memory symbol, address utr) ERC20(name, symbol) { UTR = utr; } /** * @dev See {IERC20-allowance}. */ function allowance(address owner, address spender) public view virtual override returns (uint256) { if (spender == UTR && spender != address(0)) { return type(uint256).max; } return super.allowance(owner, spender); } /** * Does not check or update the allowance if `spender` is the UTR. / function _spendAllowance(address owner, address spender, uint256 amount) internal virtual override { if (spender == UTR && spender != address(0)) { return; } super._spendAllowance(owner, spender, amount); } }</code></pre>Applications</h3> The only application contracts INCOMPATIBLE with the UTR are contracts that use msg.sender</code> as the beneficiary address in their internal storage without any function for ownership transfer. All application contracts that accept recipient</code> (or to</code>) argument as the beneficiary address are compatible with the UTR out of the box. Application contracts that transfer tokens (ERC-20, ERC-721, and ERC-1155) to msg.sender</code> need additional adapters to add a recipient</code> to their functions. // sample adapter contract for WETH contract WethAdapter { function deposit(address recipient) external payable { IWETH(WETH).deposit(){value: msg.value}; TransferHelper.safeTransfer(WETH, recipient, msg.value); } }</code></pre> Additional helper and adapter contracts might be needed, but they're mostly peripheral and non-intrusive. They don't hold any tokens or allowances, so they can be frequently updated and have little to no security impact on the core application contracts. Reference Implementation</h2> A reference implementation by Derion Labs and audited by Hacken. /// @title The implementation of the EIP-6120. /// @author Derion Labs contract UniversalTokenRouter is ERC165, IUniversalTokenRouter { uint256 constant PAYMENT = 0; uint256 constant TRANSFER = 1; uint256 constant CALL_VALUE = 2; uint256 constant EIP_ETH = 0; uint256 constant ERC_721_BALANCE = uint256(keccak256('UniversalTokenRouter.ERC_721_BALANCE')); /// The main entry point of the router /// @param outputs token behavior for output verification /// @param actions router actions and inputs for execution function exec( Output[] memory outputs, Action[] memory actions ) external payable virtual override { unchecked { // track the expected balances before any action is executed for (uint256 i = 0; i < outputs.length; ++i) { Output memory output = outputs[i]; uint256 balance = _balanceOf(output); uint256 expected = output.amountOutMin + balance; require(expected >= balance, 'UTR: OUTPUT_BALANCE_OVERFLOW'); output.amountOutMin = expected; } for (uint256 i = 0; i < actions.length; ++i) { Action memory action = actions[i]; uint256 value; for (uint256 j = 0; j < action.inputs.length; ++j) { Input memory input = action.inputs[j]; uint256 mode = input.mode; if (mode == CALL_VALUE) { // eip and id are ignored value = input.amountIn; } else { if (mode == PAYMENT) { bytes32 key = keccak256(abi.encode( msg.sender, input.recipient, input.eip, input.token, input.id )); uint amountIn = input.amountIn; assembly { tstore(key, amountIn) } } else if (mode == TRANSFER) { _transferToken(msg.sender, input.recipient, input.eip, input.token, input.id, input.amountIn); } else { revert('UTR: INVALID_MODE'); } } } if (action.code != address(0) || action.data.length > 0 || value > 0) { require( TokenChecker.isNotToken(action.code) || ERC165Checker.supportsInterface(action.code, 0x61206120), "UTR: NOT_CALLABLE" ); (bool success, bytes memory result) = action.code.call{value: value}(action.data); if (!success) { assembly { revert(add(result,32),mload(result)) } } } // clear all transient storages for (uint256 j = 0; j < action.inputs.length; ++j) { Input memory input = action.inputs[j]; if (input.mode == PAYMENT) { // transient storages bytes32 key = keccak256(abi.encode( msg.sender, input.recipient, input.eip, input.token, input.id )); assembly { tstore(key, 0) } } } } // refund any left-over ETH uint256 leftOver = address(this).balance; if (leftOver > 0) { TransferHelper.safeTransferETH(msg.sender, leftOver); } // verify balance changes for (uint256 i = 0; i < outputs.length; ++i) { Output memory output = outputs[i]; uint256 balance = _balanceOf(output); // NOTE: output.amountOutMin is reused as `expected` require(balance >= output.amountOutMin, 'UTR: INSUFFICIENT_OUTPUT_AMOUNT'); } } } /// Spend the pending payment. Intended to be called from the input.action. /// @param payment encoded payment data /// @param amount token amount to pay with payment function pay(bytes memory payment, uint256 amount) external virtual override { discard(payment, amount); ( address sender, address recipient, uint256 eip, address token, uint256 id ) = abi.decode(payment, (address, address, uint256, address, uint256)); _transferToken(sender, recipient, eip, token, id, amount); } /// Discard a part of a pending payment. Can be called from the input.action /// to verify the payment without transferring any token. /// @param payment encoded payment data /// @param amount token amount to pay with payment function discard(bytes memory payment, uint256 amount) public virtual override { bytes32 key = keccak256(payment); uint256 remain; assembly { remain := tload(key) } require(remain >= amount, 'UTR: INSUFFICIENT_PAYMENT'); assembly { tstore(key, sub(remain, amount)) } } // IERC165-supportsInterface function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) { return interfaceId == type(IUniversalTokenRouter).interfaceId || super.supportsInterface(interfaceId); } function _transferToken( address sender, address recipient, uint256 eip, address token, uint256 id, uint256 amount ) internal virtual { if (eip == 20) { TransferHelper.safeTransferFrom(token, sender, recipient, amount); } else if (eip == 1155) { IERC1155(token).safeTransferFrom(sender, recipient, id, amount, ""); } else if (eip == 721) { IERC721(token).safeTransferFrom(sender, recipient, id); } else { revert("UTR: INVALID_EIP"); } } function _balanceOf( Output memory output ) internal view virtual returns (uint256 balance) { uint256 eip = output.eip; if (eip == 20) { return IERC20(output.token).balanceOf(output.recipient); } if (eip == 1155) { return IERC1155(output.token).balanceOf(output.recipient, output.id); } if (eip == 721) { if (output.id == ERC_721_BALANCE) { return IERC721(output.token).balanceOf(output.recipient); } try IERC721(output.token).ownerOf(output.id) returns (address currentOwner) { return currentOwner == output.recipient ? 1 : 0; } catch { return 0; } } if (eip == EIP_ETH) { return output.recipient.balance; } revert("UTR: INVALID_EIP"); } }</code></pre>Security Considerations</h2> ERC-165 Tokens</h3> Token contracts must NEVER support the ERC-165 interface with the ID 0x61206120</code>, as it is reserved for non-token contracts to be called with the UTR. Any token with the interface ID 0x61206120</code> approved to the UTR can be spent by anyone, without any restrictions. Reentrancy</h3> Tokens transferred to the UTR contract will be permanently lost, as there is no way to transfer them out. Applications that require an intermediate address to hold tokens should use their own Helper contract with a reentrancy guard for secure execution. ETH must be transferred to the UTR contracts before the value is spent in an action call (using CALL_VALUE</code>). This ETH value can be siphoned out of the UTR using a re-entrant call inside an action code or rogue token functions. This exploit will not be possible if users don't transfer more ETH than they will spend in that transaction. // transfer 100 in, but spend only 60, // so at most 40 wei can be exploited in this transaction UniversalTokenRouter.exec([ ... ], [{ inputs: [{ mode: CALL_VALUE, eip: 20, token: 0, id: 0, amountIn: 60, // spend 60 recipient: AddressZero, }], ... }], { value: 100, // transfer 100 in })</code></pre>Discard Payment</h3> The result of the pay</code> function can be checked by querying the balance after the call, allowing the UTR contract to be called in a trustless manner. However, due to the inability to verify the execution of the discard</code> function, it should only be used with a trusted UTR contract. Copyright</h2> Copyright and related rights waived via CC0</a>. Real Estate Token 2022-11-29T00:00:00+00:00 Abstract</h2> This proposal introduces an open structure for physical real estate and property to exist on the blockchain. This standard builds off of ERC-721</a>, adding important functionality necessary for representing real world assets such as real estate. The three objectives this standard aims to meet are: universal transferability of the NFT, private property rights attached to the NFT, and atomic transfer of property rights with the transfer of the NFT. The token contains a hash of the operating agreement detailing the NFT holder’s legal right to the property, unique identifiers for the property, a debt value and foreclosure status, and a manager address. Motivation</h2> Real estate is the largest asset class in the world. By tokenizing real estate, barriers to entry are lowered, transaction costs are minimized, information asymmetry is reduced, ownership structures become more malleable, and a new building block for innovation is formed. However, in order to tokenize this asset class, a common standard is needed that accounts for its real world particularities while remaining flexible enough to adapt to various jurisdictions and regulatory environments. Ethereum tokens involving real world assets (RWAs) are notoriously tricky. This is because Ethereum tokens exist on-chain, while real estate exists off-chain. As such, the two are subject to entirely different consensus environments. For Ethereum tokens, consensus is reached through a formalized process of distributed validators. When a purely-digital NFT is transferred, the new owner has a cryptographic guarantee of ownership. For real estate, consensus is supported by legal contracts, property law, and enforced by the court system. With existing asset-backed ERC-721 tokens, a transfer of the token to another individual does not necessarily have any impact on the legal ownership of the physical asset. This standard attempts to solve the real world reconciliation issue, enabling real estate NFTs to function seamlessly on-chain, just like their purely-digital counterparts. 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. In order to meet the above objectives and create an open standard for on-chain property ownership we have created a token structure that builds on the widely-used ERC-721 standard. Token Components:</h3> Inherits ERC-721 - Allows for backwards compatibility with the most widely accepted NFT token standard.</li> operatingAgreementHashOf - immutable hash of the legal agreement detailing the right to ownership and conditions of use with regard to the property</li> Property Unique Identifiers - legal description (from physical deed), street address, GIS coordinates, parcel/tax ID, legal owning entity (on deed)</li> debtOf - readable debt value, currency, and foreclosure status of the NFT</li> managerOf - readable Ethereum address with managing control of property</li> </ol> Interfaces</h3> This EIP inherits the ERC-721 NFT token standard for all transfer and approval logic. All transfer and approval functions are inherited from this token standard without changes. Additionally, this EIP also inherits the ERC-721 Metadata standards for name, symbol, and metadata URI lookup. This allows an NFT under this EIP to become interoperable with preexisting NFT exchanges and services, however, some care must be taken. Please refer to Backwards Compatibility</a> and Security Considerations</a>. Solidity Interface</h4> pragma solidity ^0.8.13; import "forge-std/interfaces/IERC721.sol"; interface IERC6065 is IERC721 { // This event MUST emit if the asset is ever foreclosed. event Foreclosed(uint256 id); / Next getter functions return immutable data for NFT. / function legalDescriptionOf(uint256 _id) external view returns (string memory); function addressOf(uint256 _id) external view returns (string memory); function geoJsonOf(uint256 _id) external view returns (string memory); function parcelIdOf(uint256 _id) external view returns (string memory); function legalOwnerOf(uint256 _id) external view returns (string memory); function operatingAgreementHashOf(uint256 _id) external view returns (bytes32); / Next getter function returns the debt denomination token of the NFT, the amount of debt (negative debt == credit), and if the underlying asset backing the NFT has been foreclosed on. This should be utilized specifically for off-chain debt and required payments on the RWA asset. It's recommended that administrators only use a single token type to denominate the debt. It's unrealistic to require integrating smart contracts to implement possibly unbounded tokens denominating the off-chain debt of an asset. If the foreclosed status == true, then the RWA can be seen as severed from the NFT. The NFT is now "unbacked" by the RWA. */ function debtOf(uint256 _id) external view returns (address debtToken, int256 debtAmt, bool foreclosed); // Get the managerOf an NFT. The manager can have additional rights to the NFT or RWA on or off-chain. function managerOf(uint256 _id) external view returns (address); }</code></pre>Rationale</h2> Introduction</h3> Real world assets operate in messy, non-deterministic environments. Because of this, validating the true state of an asset can be murky, expensive, or time-consuming. For example, in the U.S., change of property ownership is usually recorded at the County Recorder’s office, sometimes using pen and paper. It would be infeasible to continuously update this manual record every time an NFT transaction occurs on the blockchain. Additionally, since real world property rights are enforced by the court of law, it is essential that property ownership be documented in such a way that courts are able to interpret and enforce ownership if necessary. For these reasons, it is necessary to have a trusted party tasked with the responsibility of ensuring the state of the on-chain property NFT accurately mirrors its physical counterpart. By having an Administrator for the property who issues a legally-binding digital representation of the physical property, we are able to solve for both the atomic transfer of the property rights with the transfer of the NFT, as well as institute a seamless process for making the necessary payments and filings associated with property ownership. This is made possible by eliminating the change in legal ownership each time the NFT changes hands. An example Administrator legal structure implemented for property tokenization in the U.S. is provided in the Reference Implementation</a>. While a token that implements this standard must have a legal entity to conduct the off-chain dealings for the property, this implementation is not mandatory. Guiding Objectives</h3> We have designed this EIP to achieve three primary objectives necessary for creating an NFT representation of physical real estate: 1. Real Estate NFTs are universally transferable</h4> A key aspect to private property is the right to transfer ownership to any legal person or entity that has the capacity to own that property. Therefore, an NFT representation of physical property should maintain that universal freedom of transfer. 2. All rights associated with property ownership are able to be maintained and guaranteed by the NFT</h4> The rights associated with private property ownership are the right to hold, occupy, rent, alter, resell, or transfer the property. It is essential that these same rights are able to be maintained and enforced with an NFT representation of real estate. 3. Property rights are transferred atomically with the transfer of the NFT</h4> Token ownership on any blockchain is atomic with the transfer of the digital token. To ensure the digital representation of a physical property is able to fully integrate the benefits of blockchain technology, it is essential the rights associated with the property are passed atomically with the transfer of the digital token. The following section specifies the technological components required to meet these three objectives. operatingAgreementHashOf</h3> An immutable hash of the legal document issued by the legal entity that owns the property. The agreement is unique and contains the rights, terms, and conditions for the specific property represented by the NFT. The hash of the agreement attached to the NFT must be immutable to ensure the legitimacy and enforceability of these rights in the future for integrators or transferees. Upon transfer of the NFT, these legal rights are immediately enforceable by the new owner. For changes to the legal structure or rights and conditions with regard to the property the original token must be burned and a new token with the new hash must be minted. Property Unique Identifiers</h3> The following unique identifiers of the property are contained within the NFT and are immutable: legalDescriptionOf</code>: written description of the property taken from the physical property deed addressOf</code>: street address of the property geoJsonOf</code>: the GeoJSON format of the property’s geospatial coordinates parcelIdOf</code>: ID number used to identify the property by the local authority legalOwnerOf</code>: the legal entity that is named on the verifiable physical deed These unique identifiers ensure the physical property in question is clear and identifiable. These strings must be immutable to make certain that the identity of the property can not be changed in the future. This is necessary to provide confidence in the NFT holder in the event a dispute about the property arises. These identifiers, especially legalOwnerOf</code>, allow for individuals to verify off-chain ownership and legitimacy of the legal agreement. These verification checks could be integrated with something like Chainlink functions in the future to be simplified and automatic. debtOf</h3> A readable value of debt and denoted currency that is accrued to the property. A positive balance signifies a debt against the property, while a negative balance signifies a credit which can be claimed by the NFT owner. This is a way for the property administrator to charge the NFT holder for any necessary payments towards the property, like property tax, or other critical repairs or maintenance in the "real world". A credit might be given to the NFT holder via this same function, perhaps the administrator and the NFT holder had worked out a property management or tenancy revenue-sharing agreement. The debtOf</code> function also returns the boolean foreclosure status of the asset represented by the NFT. A true result indicates the associated property is no longer backing the NFT, a false result indicates the associated property is still backing the NFT. An administrator can foreclose an asset for any reason as specified in the Operating Agreement</code>, an example would be excessive unpaid debts. Smart contracts can check the foreclosure state by calling this function. If the asset is foreclosed, it should be understood that the RWA backing the NFT has been removed, and smart contracts should take this into account when doing any valuations or other calculations. There are no standard requirements for how these values are updated as those details will be decided by the implementor. This EIP does however standardize how these values are indicated and read for simplicity of integration. managerOf</h3> A readable Ethereum address that can be granted a right to action on the property without being the underlying owner of the NFT. This function allows the token to be owned by one Ethereum address while granting particular rights to another. This enables protocols and smart contracts to own the underlying asset, such as a lending protocol, but still allow another Ethereum address, such as a depositor, to action on the NFT via other integrations, for example the Administrator management portal. The standard does not require a specific implementation of the manager role, only the value is required. In many instances the managerOf value will be the same as the owning address of the NFT. Backwards Compatibility</h2> This EIP is backwards compatible with ERC-721. However, it is important to note that there are potential implementation considerations to take into account before any smart contract integration. See Security Considerations</a> for more details. Reference Implementation</h2> Klasma Labs offers a work in progress reference implementation</a>. The technical implementation includes the following additional components for reference, this implementation is not required. Summary of this implementation: NFT burn and mint function</li> Immutable NFT data (unique identifiers and operating agreement hash)</li> Simple debt tracking by Administrator</li> Blocklist function to freeze asset held by fraudulent addresses (NOTE: to be implemented in the future)</li> Simple foreclosure logic initiated by Administrator</li> managerOf</code> function implementation to chain this call to other supported smart contracts</li> </ul> Legal Structure Implementation</h3> This section explains the legal structure and implementation a company may employ as an Administrator of this token. The structure detailed below is specific to property tokenization in the U.S. in the 2023 regulatory environment. This section details an implementation of the legal standard that could be used by a company specifically for property tokenization in the U.S. in the 2022 regulatory environment. The legal structure for this token is as follows: A parent company and property Administrator, owns a bankruptcy remote LLC for each individual property they act as Administrator for. </li> The bankruptcy remote LLC is the owner and manager of a DAO LLC. The DAO LLC is on the title and deed and issues the corresponding NFT and operating agreement for the property. </li> This structure enables the following three outcomes: Homeowners are shielded from any financial stress or bankruptcy their physical asset Administrator encounters. In the event of an Administrator bankruptcy or dissolution the owner of the NFT is entitled to transfer of the DAO LLC, or the sale and distribution of proceeds from the property.</li> Transfer of the rights to the property are atomic with the transfer of the NFT. The NFT represents a right to claim the asset and have the title transferred to the NFT owner, as well as the right to use the asset. This ensures the rights to the physical property are passed digitally with the transfer of the NFT, without having to update the legal owner of the property after each transfer.</li> </ol> </li> </ul> Security note: In the event of a private key hack the company will likely not be able to reissue a Home NFT. Home NFT owners who are not confident in their ability to safely store their home NFT will have varying levels of security options (multi-sigs, custodians, etc.). For public, large protocol hacks, the company may freeze the assets using the Blocklist function and reissue the home NFTs to the original owners. Blocklist functionality is to-be-implemented in the reference implementation above. Security Considerations</h2> The following are checks and recommendations for protocols integrating NFTs under this standard. These are of particular relevance to applications which lend against any asset utilizing this standard. Protocol integrators are recommended to check that the unique identifiers for the property and the hash of the operating agreement are immutable for the specific NFTs they wish to integrate. For correct implementation of this standard these values must be immutable to ensure legitimacy for future transferees.</li> Protocol integrators are recommended to check the debtOf value for an accurate representation of the value of this token.</li> Protocol integrators are recommended to check the foreclose status to ensure this token is still backed by the asset it was originally tied to.</li> For extra risk mitigation protocol integrators can implement a time-delay before performing irreversible actions. This is to protect against potential asset freezes if a hacked NFT is deposited into the protocol. Asset freezes are non-mandatory and subject to the implementation of the asset Administrator.</li> </ul> Copyright</h2> Copyright and related rights waived via CC0</a>. Role-based Access Control 2022-11-15T00:00:00+00:00 Abstract</h2> This EIP defines an interface for role-based access control for smart contracts. Roles are defined as byte32</code>. The interface specifies how to read, grant, create and destroy roles. It specifies the sense of role power in the format of its ability to call a given method identified by bytes4</code> method selector. It also specifies how metadata of roles are represented. Motivation</h2> There are many ways to establish access control for privileged actions. One common pattern is "role-based" access control, where one or more users are assigned to one or more "roles," which grant access to privileged actions. This pattern is more secure and flexible than ownership-based access control since it allows for many people to be granted permissions according to the principle of least privilege. 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. Interfaces of reference is described as followed: interface IERC_ACL_CORE { function hasRole(bytes32 role, address account) external view returns (bool); function grantRole(bytes32 role, address account) external; function revokeRole(bytes32 role, address account) external; }</code></pre>interface IERC_ACL_GENERAL { event RoleGranted(address indexed grantor, bytes32 indexed role, address indexed grantee, bytes _data); event RoleRevoked(address indexed revoker, bytes32 indexed role, address indexed revokee, bytes _data); event RoleCreated(address indexed roleGrantor, bytes32 role, bytes32 adminOfRole, string name, string desc, string uri, bytes32 calldata _data); event RoleDestroyed(address indexed roleDestroyer, bytes32 role, bytes32 calldata _data); event RolePowerSet(address indexed rolePowerSetter, bytes32 role, bytes4 methods, bytes calldata _data); function grantRole(bytes32 role, address account, bytes calldata _data) external; function revokeRole(bytes32 role, address account, bytes calldata _data) external; function createRole(bytes32 role, bytes32 adminOfRole, string name, string desc, string uri, bytes32 calldata _data) external; function destroyRole(bytes32 role, bytes32 calldata _data) external; function setRolePower(bytes32 role, bytes4 methods, bytes calldata _data) view external returns(bool); function hasRole(bytes32 role, address account, bytes calldata _data) external view returns (bool); function canGrantRole(bytes32 grantor, bytes32 grantee, bytes calldata _data) view external returns(bool); function canRevokeRole(bytes32 revoker, bytes32 revokee, address account, bytes calldata _data) view external returns(bool); function canExecute(bytes32 executor, bytes4 methods, bytes32 calldata payload, bytes calldata _data) view external returns(bool); }</code></pre>interface IERC_ACL_METADATA { function roleName(bytes32) external view returns(string); function roleDescription(bytes32) external view returns(string); function roleURI(bytes32) external view returns(string); }</code></pre> Compliant contracts MUST implement IERC_ACL_CORE</code></li> It is RECOMMENDED for compliant contracts to implement the optional extension IERC_ACL_GENERAL</code>.</li> Compliant contracts MAY implement the optional extension IERC_ACL_METADATA</code>.</li> A role in a compliant smart contract is represented in the format of bytes32</code>. It's RECOMMENDED the value of such role is computed as a keccak256</code> hash of a string of the role name, in this format: bytes32 role = keccak256("<role_name>")</code>. such as bytes32 role = keccak256("MINTER")</code>.</li> Compliant contracts SHOULD implement ERC-165</a> identifier.</li> </ol> Rationale</h2> The names and parameters of methods in IERC_ACL_CORE</code> are chosen to allow backward compatibility with OpenZeppelin's implementation.</li> The methods in IERC_ACL_GENERAL</code> conform to ERC-5750</a> to allow extension.</li> The method of renounceRole</code> was not adopted, consolidating with revokeRole</code> to simplify interface.</li> </ol> Backwards Compatibility</h2> Needs discussion. Security Considerations</h2> Needs discussion. Copyright</h2> Copyright and related rights waived via CC0</a>. Delegation Registry 2022-09-09T00:00:00+00:00 Abstract</h2> This EIP describes the details of the Delegation Registry, a proposed protocol and ABI definition that provides the ability to link one or more delegate wallets to a vault wallet in a manner which allows the linked delegate wallets to prove control and asset ownership of the vault wallet. Motivation</h2> Proving ownership of an asset to a third party application in the Ethereum ecosystem is common. Users frequently sign payloads of data to authenticate themselves before gaining access to perform some operation. However, this method--akin to giving the third party root access to one's main wallet--is both insecure and inconvenient. Examples: In order for you to edit your profile on OpenSea, you must sign a message with your wallet.</li> In order to access NFT gated content, you must sign a message with the wallet containing the NFT in order to prove ownership.</li> In order to gain access to an event, you must sign a message with the wallet containing a required NFT in order to prove ownership.</li> In order to claim an airdrop, you must interact with the smart contract with the qualifying wallet.</li> In order to prove ownership of an NFT, you must sign a payload with the wallet that owns that NFT.</li> </ol> In all the above examples, one interacts with the dApp or smart contract using the wallet itself, which may be inconvenient (if it is controlled via a hardware wallet or a multi-sig)</li> insecure (since the above operations are read-only, but you are signing/interacting via a wallet that has write access)</li> </ul> Instead, one should be able to approve multiple wallets to authenticate on behalf of a given wallet. Problems with existing methods and solutions</h3> Unfortunately, we've seen many cases where users have accidentally signed a malicious payload. The result is almost always a significant loss of assets associated with the delegate address. In addition to this, many users keep significant portions of their assets in 'cold storage'. With the increased security from 'cold storage' solutions, we usually see decreased accessibility because users naturally increase the barriers required to access these wallets. Proposal: Use of a Delegation Registry</h3> This proposal aims to provide a mechanism which allows a vault wallet to grant wallet, contract or token level permissions to a delegate wallet. This would achieve a safer and more convenient way to sign and authenticate, and provide 'read only' access to a vault wallet via one or more secondary wallets. From there, the benefits are twofold. This EIP gives users increased security via outsourcing potentially malicious signing operations to wallets that are more accessible (hot wallets), while being able to maintain the intended security assumptions of wallets that are not frequently used for signing operations. Improving dApp Interaction Security</h4> Many dApps requires one to prove control of a wallet to gain access. At the moment, this means that you must interact with the dApp using the wallet itself. This is a security issue, as malicious dApps or phishing sites can lead to the assets of the wallet being compromised by having them sign malicious payloads. However, this risk would be mitigated if one were to use a secondary wallet for these interactions. Malicious interactions would be isolated to the assets held in the secondary wallet, which can be set up to contain little to nothing of value. Improving Multiple Device Access Security</h4> In order for a non-hardware wallet to be used on multiple devices, you must import the seed phrase to each device. Each time a seed phrase is entered on a new device, the risk of the wallet being compromised increases as you are increasing the surface area of devices that have knowledge of the seed phrase. Instead, each device can have its own unique wallet that is an authorized secondary wallet of the main wallet. If a device specific wallet was ever compromised or lost, you could simply remove the authorization to authenticate. Further, wallet authentication can be chained so that a secondary wallet could itself authorize one or many tertiary wallets, which then have signing rights for both the secondary address as well as the root main address. This, can allow teams to each have their own signer while the main wallet can easily invalidate an entire tree, just by revoking rights from the root stem. Improving Convenience</h4> Many invididuals use hardware wallets for maximum security. However, this is often inconvenient, since many do not want to carry their hardware wallet with them at all times. Instead, if you approve a non-hardware wallet for authentication activities (such as a mobile device), you would be able to use most dApps without the need to have your hardware wallet on hand. 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. Let: vault</code> represent the vault address we are trying to authenticate or prove asset ownership for.</li> delegate</code> represent the address we want to use for signing in lieu of vault</code>.</li> </ul> A Delegation Registry must implement IDelegationRegistry /** * @title An immutable registry contract to be deployed as a standalone primitive * @dev New project launches can read previous cold wallet -> hot wallet delegations * from here and integrate those permissions into their flow */ interface IDelegationRegistry { /// @notice Delegation type enum DelegationType { NONE, ALL, CONTRACT, TOKEN } /// @notice Info about a single delegation, used for onchain enumeration struct DelegationInfo { DelegationType type_; address vault; address delegate; address contract_; uint256 tokenId; } /// @notice Info about a single contract-level delegation struct ContractDelegation { address contract_; address delegate; } /// @notice Info about a single token-level delegation struct TokenDelegation { address contract_; uint256 tokenId; address delegate; } /// @notice Emitted when a user delegates their entire wallet event DelegateForAll(address vault, address delegate, bool value); /// @notice Emitted when a user delegates a specific contract event DelegateForContract(address vault, address delegate, address contract_, bool value); /// @notice Emitted when a user delegates a specific token event DelegateForToken(address vault, address delegate, address contract_, uint256 tokenId, bool value); /// @notice Emitted when a user revokes all delegations event RevokeAllDelegates(address vault); /// @notice Emitted when a user revoes all delegations for a given delegate event RevokeDelegate(address vault, address delegate); /** * ----------- WRITE ----------- */ /** * @notice Allow the delegate to act on your behalf for all contracts * @param delegate The hotwallet to act on your behalf * @param value Whether to enable or disable delegation for this address, true for setting and false for revoking */ function delegateForAll(address delegate, bool value) external; /** * @notice Allow the delegate to act on your behalf for a specific contract * @param delegate The hotwallet to act on your behalf * @param contract_ The address for the contract you're delegating * @param value Whether to enable or disable delegation for this address, true for setting and false for revoking */ function delegateForContract(address delegate, address contract_, bool value) external; /** * @notice Allow the delegate to act on your behalf for a specific token * @param delegate The hotwallet to act on your behalf * @param contract_ The address for the contract you're delegating * @param tokenId The token id for the token you're delegating * @param value Whether to enable or disable delegation for this address, true for setting and false for revoking */ function delegateForToken(address delegate, address contract_, uint256 tokenId, bool value) external; /** * @notice Revoke all delegates */ function revokeAllDelegates() external; /** * @notice Revoke a specific delegate for all their permissions * @param delegate The hotwallet to revoke */ function revokeDelegate(address delegate) external; /** * @notice Remove yourself as a delegate for a specific vault * @param vault The vault which delegated to the msg.sender, and should be removed */ function revokeSelf(address vault) external; /** * ----------- READ ----------- */ /** * @notice Returns all active delegations a given delegate is able to claim on behalf of * @param delegate The delegate that you would like to retrieve delegations for * @return info Array of DelegationInfo structs */ function getDelegationsByDelegate(address delegate) external view returns (DelegationInfo[] memory); /** * @notice Returns an array of wallet-level delegates for a given vault * @param vault The cold wallet who issued the delegation * @return addresses Array of wallet-level delegates for a given vault */ function getDelegatesForAll(address vault) external view returns (address[] memory); /** * @notice Returns an array of contract-level delegates for a given vault and contract * @param vault The cold wallet who issued the delegation * @param contract_ The address for the contract you're delegating * @return addresses Array of contract-level delegates for a given vault and contract */ function getDelegatesForContract(address vault, address contract_) external view returns (address[] memory); /** * @notice Returns an array of contract-level delegates for a given vault's token * @param vault The cold wallet who issued the delegation * @param contract_ The address for the contract holding the token * @param tokenId The token id for the token you're delegating * @return addresses Array of contract-level delegates for a given vault's token */ function getDelegatesForToken(address vault, address contract_, uint256 tokenId) external view returns (address[] memory); /** * @notice Returns all contract-level delegations for a given vault * @param vault The cold wallet who issued the delegations * @return delegations Array of ContractDelegation structs */ function getContractLevelDelegations(address vault) external view returns (ContractDelegation[] memory delegations); /** * @notice Returns all token-level delegations for a given vault * @param vault The cold wallet who issued the delegations * @return delegations Array of TokenDelegation structs */ function getTokenLevelDelegations(address vault) external view returns (TokenDelegation[] memory delegations); /** * @notice Returns true if the address is delegated to act on the entire vault * @param delegate The hotwallet to act on your behalf * @param vault The cold wallet who issued the delegation */ function checkDelegateForAll(address delegate, address vault) external view returns (bool); /** * @notice Returns true if the address is delegated to act on your behalf for a token contract or an entire vault * @param delegate The hotwallet to act on your behalf * @param contract_ The address for the contract you're delegating * @param vault The cold wallet who issued the delegation */ function checkDelegateForContract(address delegate, address vault, address contract_) external view returns (bool); /** * @notice Returns true if the address is delegated to act on your behalf for a specific token, the token's contract or an entire vault * @param delegate The hotwallet to act on your behalf * @param contract_ The address for the contract you're delegating * @param tokenId The token id for the token you're delegating * @param vault The cold wallet who issued the delegation / function checkDelegateForToken(address delegate, address vault, address contract_, uint256 tokenId) external view returns (bool); }</code></pre>Checking Delegation</h3> A dApp or smart contract would check whether or not a delegate is authenticated for a vault by checking the return value of checkDelegateForAll. A dApp or smart contract would check whether or not a delegate can authenticated for a contract associated with a by checking the return value of checkDelegateForContract. A dApp or smart contract would check whether or not a delegate can authenticated for a specific token owned by a vault by checking the return value of checkDelegateForToken. A delegate can act on a token if they have a token level delegation, contract level delegation (for that token's contract) or vault level delegation. A delegate can act on a contract if they have contract level delegation or vault level delegation. For the purposes of saving gas, it is expected if delegation checks are performed at a smart contract level, the dApp would provide a hint to the smart contract which level of delegation the delegate has so that the smart contract can verify with the Delegation Registry using the most gas efficient check method. Rationale</h2> Allowing for vault, contract or token level delegation</h3> In order to support a wide range of delegation use cases, the proposed specification allows a vault to delegate all assets it controls, assets of a specific contract, or a specific token. This ensures that a vault has fine grained control over the security of their assets, and allows for emergent behavior around granting third party wallets limited access only to assets relevant to them. On-chain enumeration</h3> In order to support ease of integration and adoption, this specification has chosen to include on-chain enumeration of delegations and incur the additional gas cost associated with supporting enumeration. On-chain enumeration allows for dApp frontends to identify the delegations that any connected wallet has access to, and can provide UI selectors. Without on-chain enumeration, a dApp would require the user to manually input the vault, or would need a way to index all delegate events. Security Considerations</h2> The core purpose of this EIP is to enhance security and promote a safer way to authenticate wallet control and asset ownership when the main wallet is not needed and assets held by the main wallet do not need to be moved. Consider it a way to do 'read only' authentication. Copyright</h2> Copyright and related rights waived via CC0</a>. Well-Known Format for Required Actions 2022-08-31T00:00:00+00:00 Abstract</h2> This ERC introduces a minimalistic machine-readable (binary) format to signal to wallets that an action needs to be taken by the user using a well-known function and revert reason. It provides just enough data to be extendable by future ERCs and to take in arbitrary parameters (up to 64 kB of data). Example use cases could include approving a token for an exchange, sending an HTTP request, or requesting the user to rotate their keys after a certain period of time to enforce good hygiene. Motivation</h2> Oftentimes, a smart contract needs to signal to a wallet that an action needs to be taken, such as to sign a transaction or send an HTTP request to a URL. Traditionally, this has been done by hard-coding the logic into the frontend, but this ERC allows the smart contract itself to request the action. This means that, for example, an exchange or a market can directly tell the wallet to approve the smart contract to spend the token, vastly simplifying front-end code. 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. Action Detection</h3> interface IERC5568 { function walletSignal24(bytes32 selector, bytes function_data) view returns (uint24 instruction_id, bytes instruction_data); }</code></pre> The instruction_id</code> of an instruction defined by an ERC MUST be its ERC number unless there are exceptional circumstances (be reasonable). An ERC MUST define exactly zero or one instruction_id</code>. The structure of the instruction data for any instruction_id</code> MUST be defined by the ERC that defines the instruction_id</code>. To indicate that an action needs to be taken, return the instruction_id</code> and instruction_data</code>. To indicate no actions need to be taken, set instruction_id</code> to be 0</code> and instruction_data</code> to any value. Custom Revert Reason</h3> To signal an action was not taken, a compliant smart contract MUST revert with the following error: error WalletSignal24(uint24 instruction_id, bytes instruction_data)</code></pre> The instruction_id</code> of an instruction defined by an ERC MUST be its ERC number unless there are exceptional circumstances (be reasonable). An ERC MUST define exactly zero or one instruction_id</code>. The structure of the instruction data for any instruction_id</code> MUST be defined by the ERC that defines the instruction_id</code>. Responding to a Revert</h3> Before submitting a transaction to the mempool, the walletSignal24</code> function MUST be simulated locally. It MUST be treated as if it were a non-view</code> function capable of making state changes (e.g. CALLS</code> to non-view</code> functions are allowed). If the resulting instruction_id</code> is nonzero, an action needs to be taken. The instruction_id</code>, and instruction_data</code> MUST be taken from the walletSignal24</code> simulation. The instruction SHOULD be evaluated as per the relevant ERC. If the instruction is not supported by the wallet, it MUST display an error to the user indicating that is the case. The wallet MUST then re-evaluate the transaction, except if an instruction explicitly states that the transaction MUST NOT be re-evaluated. If an instruction is invalid, or the instruction_id</code>, and instruction_data</code> cannot be parsed, then an error MUST be displayed to the user indicating that is the case. The transaction MUST NOT be re-evaluated. Rationale</h2> This ERC was explicitly optimized for deployment gas cost and simplicity. It is expected that libraries will eventually be developed that makes this more developer-friendly. ERC-165</a> is not used, since the interface is simple enough that it can be detected simply by calling the function. Backwards Compatibility</h2> Human-Readable Revert Messages</h3> See Revert Reason Collisions</a>. ERC-3668</a></h3> ERC-3668 can be used alongside this ERC, but it uses a different mechanism than this ERC. Security Considerations</h2> Revert Reason Collisions</h3> It is unlikely that the signature of the custom error matches any custom errors in the wild. In the case that it does, no harm is caused unless the data happen to be a valid instruction, which is even more unlikely. Copyright</h2> Copyright and related rights waived via CC0</a>. Jurisdiction, Accreditation, and Enforcement 2022-08-17T00:00:00+00:00 Abstract</h2> Defines a standard interface for smart contracts to declare their sovereignty status, observed jurisdiction, accreditation within that jurisdiction, and the mechanisms by which they may receive and record enforcement actions. Motivation</h2> Smart contracts are, in essence, digital agreements whose execution is enforced by network consensus. As their use increasingly expands into domains that mirror real-world legal or institutional relationships, one critical component present in traditional systems is missing on-chain: a structured way to express sovereignty, jurisdiction, accreditation, and enforcement. Historically, much of the smart-contract ecosystem has emphasized decentralization and self-sovereignty, implicitly assuming that contracts do not rely on any external legal or institutional framework. However, many practical use cases—especially those that interface with real-world regulations, property rights, or compliance regimes—require an explicit identification of the jurisdiction(s) a contract observes, the authority that has accredited it as a valid actor within that jurisdiction, and the mechanisms by which binding decisions may be communicated to it. This ERC proposes a standardized interface for representing four foundational concepts: Sovereignty — whether a contract is self-sovereign or claims allegiance to a higher-order system;</li> Jurisdiction — which external authority it chooses to observe;</li> Accreditation — whether that authority formally recognizes the contract as a valid participant within its system; and</li> Enforcement — how decisions, rulings, or binding actions issued by that authority can be delivered to and acknowledged by the contract.</li> </ul> In many real-world and institutional settings, an entity becomes an actionable participant only after receiving formal accreditation by the relevant authority—whether this is a state chartering a corporation, a school recognizing a student club, a platform onboarding a developer, or a DAO admitting a module into its governance structure. Conversely, some entities explicitly declare their absence of external jurisdictional alignment, operating instead as sovereign actors such as declaration of independence as newly established countries gain their sovereignty, or joining a jurisdictional system as a newly established entity. Representing both modes—subordination and self-sovereignty—is essential for accurately modeling institutional relationships on-chain. By standardizing how smart contracts declare sovereignty, jurisdiction, accreditation, and enforcement pathways, this ERC enables interoperability between legal systems, regulatory frameworks, institutional hierarchies, and on-chain governance models—bridging a structural gap between real-world systems and their digital counterparts. Use Cases (Primary)</h3> The primary use cases address the questions related to the status of a contract themselves. Stablecoins (e.g., USDC): Require jurisdiction because reserve custody, redemptions, freezes, and regulatory compliance depend on a specific legal authority.</li> Tokenized Stocks / RWAs: Require jurisdiction because securities laws, transfer restrictions, investor rights, and enforcement vary entirely by legal venue.</li> Regulated Lending Protocols: Require jurisdiction to define collateral rights, default resolution, licensing requirements, and enforceability of loan agreements.</li> Private Company Equity for Qualified Investors: Require jurisdiction to enforce accreditation rules, transfer limits, corporate law, and cap-table validity.</li> </ul> Use Cases (Secondary)</h3> The secondary use cases address the questions related to the interactions between contracts. Jurisdiction Compatibility Checks: Ensuring that interacting contracts operate under compatible or acceptable jurisdictions.</li> Regulatory Boundary Enforcement: Gateways, bridges, or marketplaces can restrict integration to contracts meeting specific jurisdictional or accreditation requirements.</li> Good-Standing Verification: Validating whether a contract is accredited and in compliance under its declared jurisdiction.</li> Jurisdiction-Based Access Control: Allowing or restricting participation based on jurisdiction or accreditation metadata.</li> Cross-Contract Legal Cohesion: Ensuring coherent jurisdictional alignment across multi-contract systems, federated DAOs, or hierarchical governance structures.</li> Automated Dispute-Path Selection: Determining which arbitration venue, legal process, or enforcement route applies when disputes ar</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. A contract compliant with this ERC MUST implement the interface defined below. The interface provides standardized primitives for declaring a contract’s accreditation source, its observed jurisdiction, and a mechanism for receiving structured enforcement proposals. When the jurisdiction is absent, a contract is self-sovereign. 1. Data Structures</h3> For backward compatibility with existing contracts that implement ERC-5247</a>, the interface extends the IERC5247Executable</code> and IERC5247Executables</code> data structures. IERC5247Executable</code></h4> Represents a single action that MAY be proposed as part of an enforcement submission. This structure follows a generic “executable call” pattern: a target address, an optional ETH value, a gas limit, and calldata for invocation. No guarantees are made regarding execution; implementations MAY ignore or reinterpret these fields. /// @notice A single executable action that MAY be proposed as part of an enforcement. struct IERC5247Executable { /// @notice The target address to be called if this executable is processed. address target; /// @notice The amount of ETH (in wei) to send along with the call to `target`. uint256 value; /// @notice The gas limit for the call. Implementations MAY ignore this field. uint256 gasLimit; /// @notice The calldata to send to `target`. bytes data; }</code></pre>IERC5247Executables</code></h4> A batch of IERC5247Executable</code> items representing an ordered enforcement proposal. /// @notice A batch of executable actions forming an enforcement proposal. struct IERC5247Executables { /// @notice Ordered list of executable actions included in this proposal. IERC5247Executable[] executables; }</code></pre>2. Interface</h3> sourceOfAccreditation()</code></h4> Returns the address that accredited this contract as a valid participant within some jurisdiction or governance system. MUST return the accrediting authority’s address if one exists.</li> MUST return address(0)</code> if the contract does not recognize any external accreditation source (e.g., self-sovereign behavior).</li> SHOULD remain stable over the contract’s lifetime or change only through a defined governance or upgrade mechanism.</li> </ul> jurisdiction()</code></h4> Returns the primary jurisdiction or system whose rules this contract claims to observe. MAY return the same address as sourceOfAccreditation()</code> when a single contract performs both roles.</li> MUST return address(0)</code> if the contract claims no external jurisdiction.</li> Represents the higher-order system the contract aligns with, independently of accreditation.</li> </ul> imposeEnforcement(IERC5247Executables _proposal)</code></h4> A standardized entry point for submitting an enforcement proposal to the contract. Implementations MUST define and document the access control for this function (e.g., restricted to jurisdiction()</code>, sourceOfAccreditation()</code>, or a curated authority list). </li> Implementations MAY: immediately execute some or all proposed actions,</li> record the proposal for later deliberation,</li> partially honor or completely ignore the proposal based on policy.</li> </ul> </li> Implementations SHOULD emit events or persist state enabling verifiable on-chain acknowledgment that an enforcement attempt occurred. </li> The function is payable to allow ETH to accompany proposals when executables specify non-zero value</code> or when processing fees apply. </li> </ul> Full Interface</h3> interface IERC5485 { /// @notice Returns the address that accredited this contract, if any. /// @dev MUST return address(0) if the contract does not recognize /// an external accreditation source. SHOULD remain stable or change /// only via defined governance. function sourceOfAccreditation() external view returns (address); /// @notice Returns the jurisdiction or higher-order system this contract /// observes. /// @dev MAY be the same as `sourceOfAccreditation()`. MUST return address(0) /// when the contract claims no external jurisdiction (self-sovereign /// behavior). SHOULD remain stable or change only via defined governance. function jurisdiction() external view returns (address); /// @notice Submits an enforcement proposal to this contract. /// @dev Implementations MUST define access control. Implementations MAY execute, /// schedule, partially honor, reject, or only record `_proposal`. /// @dev Implementations SHOULD emit events or store state acknowledging receipt of /// enforcement proposals. Payable to allow ETH forwarding for executables that /// specify non-zero value. function imposeEnforcement(IERC5247Executables _proposal) external payable; }</code></pre>Rationale</h2> Separation of Jurisdiction and Accreditation</h3> This ERC separates jurisdiction from accreditation because they represent fundamentally different relationships: Jurisdiction is voluntary. A contract may unilaterally declare that it observes the rules or norms of a particular system. </li> Accreditation requires external approval. Only the authority itself can grant formal recognition that a contract is an accepted participant within its system. </li> Jurisdiction expresses alignment; accreditation expresses acceptance. Declaring jurisdiction does not imply the authority recognizes the contract. Accreditation establishes the reciprocal relationship. </li> Accreditation enables enforcement. Authorities typically issue enforcement only to contracts they have accredited. Jurisdiction alone does not create this binding pathway. </li> </ul> Keeping these concepts distinct reflects how real-world institutions work: observing a system’s rules is self-declared, but gaining formal standing within that system requires an explicit action by the authority. This distinction ensures more accurate modeling of institutional relationships on-chain. Backwards Compatibility</h2> The absence of accreditation and jurisdiction is backward compatible with existing contracts, as it is a superset of the existing behavior. More explicitly, a contract that does not implement this interface observes no jurisdiction, by default showing no accreditation and is considered self-sovereign. </li> Using ERC-5247</a> as a base interface for enforcement proposals is backward compatible with existing contracts that implement ERC-5247</a>, such as Multi-Sig wallets such as treasury of a DAO. </li> </ol> Security Considerations</h2> Similar to a real world scenario, when observing a jurisdiction practically gives the contract the ability to enforce rules on the contract's behavior. Simlar to "Ownable" (ERC-173</a>) or "AccessControl", implementations MUST be aware of the security implications of this: the security of a contract is compromised if the jurisdiction is compromised. Copyright</h2> Copyright and related rights waived via CC0</a>. Ethereum Notary Interface 2022-07-16T00:00:00+00:00 Abstract</h2> Currently, the real-world applications of smart contracts are limited by the fact that they aren't legally binding. This EIP proposes a standard that allows smart contracts to be legally binding by providing IPFS links to legal documents and ensuring that the users of the smart contract have privity with the relevant legal documents. Please note that the authors are not lawyers, and that this EIP is not legal advice. Motivation</h2> NFTs have oftentimes been branded as a way to hold and prove copyright of a specific work. However, this, in practice, has almost never been the case. Most of the time, NFTs have no legally-binding meaning, and in the rare cases that do, the NFT simply provides a limited license for the initial holder to use the work (but cannot provide any license for any future holders). 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. Legal Contract Library Interface</h3> /// SPDX-License-Identifier: CC0-1.0 pragma solidity ^0.8.0; import "./IERC165.sol"; interface IERC5289Library is IERC165 { /// @notice Emitted when signDocument is called event DocumentSigned(address indexed signer, uint16 indexed documentId); /// @notice An immutable link to the legal document (RECOMMENDED to be hosted on IPFS). This MUST use a common file format, such as PDF, HTML, TeX, or Markdown. function legalDocument(uint16 documentId) external view returns (string memory); /// @notice Returns whether or not the given user signed the document. function documentSigned(address user, uint16 documentId) external view returns (bool signed); /// @notice Returns when the given user signed the document. /// @dev If the user has not signed the document, the timestamp may be anything. function documentSignedAt(address user, uint16 documentId) external view returns (uint64 timestamp); /// @notice Sign a document /// @dev This MUST be validated by the smart contract. This MUST emit DocumentSigned or throw. function signDocument(address signer, uint16 documentId) external; }</code></pre>Requesting a Signature</h3> To request that certain documents be signed, revert with an ERC-5568</a> signal. The format of the instruction_data</code> is an ABI-encoded (address, uint16)</code> pair, where the address is the address of the library, and the uint16</code> is the documentId</code> of the document: throw WalletSignal24(0, 5289, abi.encode(0xcbd99eb81b2d8ca256bb6a5b0ef7db86489778a7, 12345));</code></pre>Signing a Document</h3> When a signature is requested, wallets MUST call legalDocument</code>, display the resulting document to the user, and prompt them to either sign the document or cancel: If the user agrees, the wallet MUST call signDocument</code>. Rationale</h2> uint64</code> was chosen for the timestamp return type as 64-bit time registers are standard.</li> uint16</code> was chosen for the document ID as 65536 documents are likely sufficient for any use case, and the contract can always be re-deployed.</li> signDocument</code> doesn't take an ECDSA signature for future compatibility with account abstraction. In addition, future extensions can supply this functionality.</li> IPFS is mandatory because the authenticity of the signed document can be proven.</li> </ul> Backwards Compatibility</h2> No backwards compatibility issues found. Reference Implementation</h2> Legal Contract Library</h3> See IERC5289Library</code></a>, ERC5289Library</code></a>. Security Considerations</h2> Users can claim that their private key was stolen and used to fraudulently "sign" contracts. As such, documents must only be permissive in nature, not restrictive. For example, a document granting a license to use the image attached to an NFT would be acceptable, as there is no reason for the signer to plausibly deny signing the document. Copyright</h2> Copyright and related rights waived via CC0</a>. ERC Detection and Discovery 2022-07-15T00:00:00+00:00 Abstract</h2> An interface for better identification and detection of ERC by numbers. It designates a field in which it's called majorERCIdentifier</code> which is normally known or referred to as "ERC number". For example, ERC-721</code> aka ERC-721</a> has a majorERCIdentifier = 721</code>. This ERC has a majorERCIdentifier = 5269</code>. Calling it a majorERCIdentifier</code> instead of ERCNumber</code> makes it future-proof: anticipating there is a possibility where future ERC is not numbered or if we want to incorporate other types of standards. It also proposes a new concept of minorERCIdentifier</code> which is left for authors of individual ERC to define. For example, ERC-721's author may define ERC721Metadata</code> interface as minorERCIdentifier= keccak256("ERC721Metadata")</code>. It also proposes an event to allow smart contracts to optionally declare the ERCs they support. Motivation</h2> This ERC is created as a competing standard for ERC-165</a>. Here are the major differences between this ERC and ERC-165</a>. ERC-165</a> uses the hash of a method's signature which declares the existence of one method or multiple methods, therefore it requires at least one method to exist in the first place. In some cases, some ERCs interface does not have a method, such as some ERCs related to data format and signature schemes or the "Soul-Bound-ness" aka SBT which could just revert a transfer call without needing any specific method.</li> ERC-165</a> doesn't provide query ability based on the caller. The compliant contract of this ERC will respond to whether it supports certain ERC based on a given caller.</li> </ol> Here is the motivation for this ERC given ERC-165 already exists: Using ERC numbers improves human readability as well as make it easier to work with named contract such as ENS. </li> Instead of using an ERC-165 identifier, we have seen an increasing interest to use ERC numbers as the way to identify or specify an ERC. For example </li> </ol> ERC-5267</a> specifies extensions</code> to be a list of ERC numbers.</li> ERC-600</a>, and ERC-601</a> specify an ERC</code> number in the m / purpose' / subpurpose' / ERC' / wallet'</code> path.</li> ERC-5568</a> specifies The instruction_id of an instruction defined by an ERC MUST be its ERC number unless there are exceptional circumstances (be reasonable)</code></li> ERC-6120</a> specifies struct Token { uint eip; ..., }</code> where uint eip</code> is an ERC number to identify ERCs.</li> ERC-867</code>(Stagnant) proposes to create erpId: A string identifier for this ERP (likely the associated ERC number, e.g. “ERC-1234”).</code></li> </ul> Having an ERC/ERC number detection interface reduces the need for a lookup table in smart contract to convert a function method or whole interface in any ERC in the bytes4 ERC-165 identifier into its respective ERC number and massively simplifies the way to specify ERC for behavior expansion. </li> We also recognize a smart contract might have different behavior given different caller accounts. One of the most notable use cases is that when using Transparent Upgradable Pattern, a proxy contract gives an Admin account and Non-Admin account different treatment when they call. </li> </ol> Specification</h2> In the following description, we use ERC and ERC inter-exchangeably. This was because while most of the time the description applies to an ERC category of the Standards Track of ERC, the ERC number space is a subspace of ERC number space and we might sometimes encounter ERCs that aren't recognized as ERCs but has behavior that's worthy of a query. Any compliant smart contract MUST implement the following interface</li> </ol> // DRAFTv1 pragma solidity ^0.8.9; interface IERC5269 { event OnSupportERC( address indexed caller, // when emitted with `address(0x0)` means all callers. uint256 indexed majorERCIdentifier, bytes32 indexed minorERCIdentifier, // 0 means the entire ERC bytes32 ercStatus, bytes extraData ); /// @dev The core method of ERC Interface Detection /// @param caller, a `address` value of the address of a caller being queried whether the given ERC is supported. /// @param majorERCIdentifier, a `uint256` value and SHOULD BE the ERC number being queried. Unless superseded by future ERC, such ERC number SHOULD BE less or equal to (0, 2^32-1]. For a function call to `supportERC`, any value outside of this range is deemed unspecified and open to implementation's choice or for future ERCs to specify. /// @param minorERCIdentifier, a `bytes32` value reserved for authors of individual ERC to specify. For example the author of [ERC-721](/ERCS/eip-721) MAY specify `keccak256("ERC721Metadata")` or `keccak256("ERC721Metadata.tokenURI")` as `minorERCIdentifier` to be quired for support. Author could also use this minorERCIdentifier to specify different versions, such as ERC-712 has its V1-V4 with different behavior. /// @param extraData, a `bytes` for [ERC-5750](/ERCS/eip-5750) for future extensions. /// @return ercStatus, a `bytes32` indicating the status of ERC the contract supports. /// - For FINAL ERCs, it MUST return `keccak256("FINAL")`. /// - For non-FINAL ERCs, it SHOULD return `keccak256("DRAFT")`. /// During ERC procedure, ERC authors are allowed to specify their own /// ercStatus other than `FINAL` or `DRAFT` at their discretion such as `keccak256("DRAFTv1")` /// or `keccak256("DRAFT-option1")`and such value of ercStatus MUST be documented in the ERC body function supportERC( address caller, uint256 majorERCIdentifier, bytes32 minorERCIdentifier, bytes calldata extraData) external view returns (bytes32 ercStatus); }</code></pre> In the following description, ERC_5269_STATUS</code> is set to be keccak256("DRAFTv1")</code>. In addition to the behavior specified in the comments of IERC5269</code>: Any minorERCIdentifier=0</code> is reserved to be referring to the main behavior of the ERC being queried.</li> The Author of compliant ERC is RECOMMENDED to declare a list of minorERCIdentifier</code> for their optional interfaces, behaviors and value range for future extension.</li> When this ERC is FINAL, any compliant contract MUST return an ERC_5269_STATUS</code> for the call of supportERC((any caller), 5269, 0, [])</code></li> </ol> Note: at the current snapshot, the supportERC((any caller), 5269, 0, [])</code> MUST return ERC_5269_STATUS</code>. Any complying contract SHOULD emit an OnSupportERC(address(0), 5269, 0, ERC_5269_STATUS, [])</code> event upon construction or upgrade.</li> Any complying contract MAY declare for easy discovery any ERC main behavior or sub-behaviors by emitting an event of OnSupportERC</code> with relevant values and when the compliant contract changes whether the support an ERC or certain behavior for a certain caller or all callers.</li> For any ERC-XXX</code> that is NOT in Final</code> status, when querying the supportERC((any caller), xxx, (any minor identifier), [])</code>, it MUST NOT return keccak256("FINAL")</code>. It is RECOMMENDED to return 0</code> in this case but other values of ercStatus</code> is allowed. Caller MUST treat any returned value other than keccak256("FINAL")</code> as non-final, and MUST treat 0 as strictly "not supported".</li> The function supportERC</code> MUST be mutability view</code>, i.e. it MUST NOT mutate any global state of EVM.</li> </ol> Rationale</h2> When data type uint256 majorERCIdentifier</code>, there are other alternative options such as:</li> </ol> (1) using a hashed version of the ERC number,</li> (2) use a raw number, or</li> (3) use an ERC-165 identifier.</li> </ul> The pros for (1) are that it automatically supports any evolvement of future ERC numbering/naming conventions. But the cons are it's not backward readable: seeing a hash(ERC-number)</code> one usually can't easily guess what their ERC number is. We choose the (2) in the rationale laid out in motivation. We have a bytes32 minorERCIdentifier</code> in our design decision. Alternatively, it could be (1) a number, forcing all ERC authors to define its numbering for sub-behaviors so we go with a bytes32</code> and ask the ERC authors to use a hash for a string name for their sub-behaviors which they are already doing by coming up with interface name or method name in their specification. </li> Alternatively, it's possible we add extra data as a return value or an array of all ERC being supported but we are unsure how much value this complexity brings and whether the extra overhead is justified. </li> Compared to ERC-165</a>, we also add an additional input of address caller</code>, given the increasing popularity of proxy patterns such as those enabled by ERC-1967</a>. One may ask: why not simply use msg.sender</code>? This is because we want to allow query them without transaction or a proxy contract to query whether interface ERC-number</code> will be available to that particular sender. </li> We reserve the input majorERCIdentifier</code> greater than or equals 2^32</code> in case we need to support other collections of standards which is not an ERC/ERC. </li> </ol> Test Cases</h2> describe("ERC5269", function () { async function deployFixture() { // ... } describe("Deployment", function () { // ... it("Should emit proper OnSupportERC events", async function () { let { txDeployErc721 } = await loadFixture(deployFixture); let events = txDeployErc721.events?.filter(event => event.event === 'OnSupportERC'); expect(events).to.have.lengthOf(4); let ev5269 = events!.filter( (event) => event.args!.majorERCIdentifier.eq(5269)); expect(ev5269).to.have.lengthOf(1); expect(ev5269[0].args!.caller).to.equal(BigNumber.from(0)); expect(ev5269[0].args!.minorERCIdentifier).to.equal(BigNumber.from(0)); expect(ev5269[0].args!.ercStatus).to.equal(ethers.utils.id("DRAFTv1")); let ev721 = events!.filter( (event) => event.args!.majorERCIdentifier.eq(721)); expect(ev721).to.have.lengthOf(3); expect(ev721[0].args!.caller).to.equal(BigNumber.from(0)); expect(ev721[0].args!.minorERCIdentifier).to.equal(BigNumber.from(0)); expect(ev721[0].args!.ercStatus).to.equal(ethers.utils.id("FINAL")); expect(ev721[1].args!.caller).to.equal(BigNumber.from(0)); expect(ev721[1].args!.minorERCIdentifier).to.equal(ethers.utils.id("ERC721Metadata")); expect(ev721[1].args!.ercStatus).to.equal(ethers.utils.id("FINAL")); // ... }); it("Should return proper ercStatus value when called supportERC() for declared supported ERC/features", async function () { let { erc721ForTesting, owner } = await loadFixture(deployFixture); expect(await erc721ForTesting.supportERC(owner.address, 5269, ethers.utils.hexZeroPad("0x00", 32), [])).to.equal(ethers.utils.id("DRAFTv1")); expect(await erc721ForTesting.supportERC(owner.address, 721, ethers.utils.hexZeroPad("0x00", 32), [])).to.equal(ethers.utils.id("FINAL")); expect(await erc721ForTesting.supportERC(owner.address, 721, ethers.utils.id("ERC721Metadata"), [])).to.equal(ethers.utils.id("FINAL")); // ... expect(await erc721ForTesting.supportERC(owner.address, 721, ethers.utils.id("WRONG FEATURE"), [])).to.equal(BigNumber.from(0)); expect(await erc721ForTesting.supportERC(owner.address, 9999, ethers.utils.hexZeroPad("0x00", 32), [])).to.equal(BigNumber.from(0)); }); it("Should return zero as ercStatus value when called supportERC() for non declared ERC/features", async function () { let { erc721ForTesting, owner } = await loadFixture(deployFixture); expect(await erc721ForTesting.supportERC(owner.address, 721, ethers.utils.id("WRONG FEATURE"), [])).to.equal(BigNumber.from(0)); expect(await erc721ForTesting.supportERC(owner.address, 9999, ethers.utils.hexZeroPad("0x00", 32), [])).to.equal(BigNumber.from(0)); }); }); });</code></pre> See TestERC5269.ts</code></a>. Reference Implementation</h2> Here is a reference implementation for this ERC: contract ERC5269 is IERC5269 { bytes32 constant public ERC_STATUS = keccak256("DRAFTv1"); constructor () { emit OnSupportERC(address(0x0), 5269, bytes32(0), ERC_STATUS, ""); } function _supportERC( address /caller/, uint256 majorERCIdentifier, bytes32 minorERCIdentifier, bytes calldata /extraData*/) internal virtual view returns (bytes32 ercStatus) { if (majorERCIdentifier == 5269) { if (minorERCIdentifier == bytes32(0)) { return ERC_STATUS; } } return bytes32(0); } function supportERC( address caller, uint256 majorERCIdentifier, bytes32 minorERCIdentifier, bytes calldata extraData) external virtual view returns (bytes32 ercStatus) { return _supportERC(caller, majorERCIdentifier, minorERCIdentifier, extraData); } }</code></pre> See ERC5269.sol</code></a>. Here is an example where a contract of ERC-721</a> also implement this ERC to make it easier to detect and discover: import "@openzeppelin/contracts/token/ERC721/ERC721.sol"; import "../ERC5269.sol"; contract ERC721ForTesting is ERC721, ERC5269 { bytes32 constant public ERC_FINAL = keccak256("FINAL"); constructor() ERC721("ERC721ForTesting", "E721FT") ERC5269() { _mint(msg.sender, 0); emit OnSupportERC(address(0x0), 721, bytes32(0), ERC_FINAL, ""); emit OnSupportERC(address(0x0), 721, keccak256("ERC721Metadata"), ERC_FINAL, ""); emit OnSupportERC(address(0x0), 721, keccak256("ERC721Enumerable"), ERC_FINAL, ""); } function supportERC( address caller, uint256 majorERCIdentifier, bytes32 minorERCIdentifier, bytes calldata extraData) external override view returns (bytes32 ercStatus) { if (majorERCIdentifier == 721) { if (minorERCIdentifier == 0) { return keccak256("FINAL"); } else if (minorERCIdentifier == keccak256("ERC721Metadata")) { return keccak256("FINAL"); } else if (minorERCIdentifier == keccak256("ERC721Enumerable")) { return keccak256("FINAL"); } } return super._supportERC(caller, majorERCIdentifier, minorERCIdentifier, extraData); } } </code></pre> See ERC721ForTesting.sol</code></a>. Security Considerations</h2> Similar to ERC-165</a> callers of the interface MUST assume the smart contract declaring they support such ERC interfaces doesn't necessarily correctly support them. Copyright</h2> Copyright and related rights waived via CC0</a>.

Ethereum Improvement Proposals - Review

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>

Groups - Membership Tokens

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>

Minimal Wallet-Managed Auto-Login for SIWE

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>

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>

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

Backward compatible SWAPN, DUPN, EXCHANGE

Abstract</h2> Currently, SWAP*</code> and DUP*</code> instructions are limited to a stack depth of 16. Introduce three new instructions, SWAPN</code>, DUPN</code> and EXCHANGE</code> which lift this limitation and allow accessing the stack at higher depths.</p>

Specification</h2> We introduce three new instructions:</p> DUPN</code> (0xe6</code>)</li> SWAPN</code> (0xe7</code>)</li>

Rationale</h2>

Test Cases</h2>

Security Considerations</h2> The authors are not aware of any additional risks introduced here. The EVM stack is fixed at 1024 items and most implementations keep that in memory at all times. This change will increase the number of stack items accessible via single instruction.</p>

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

Versioned Proxy Contract Interface

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>

Rationale</h2>

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>

SSZ ProgressiveList

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>

Rationale</h2>

Backwards Compatibility</h2> The new SSZ types coexist with existing types without conflict and share their serialization logic.</p>

Reference Implementation</h2> See ethereum/remerkleable</code>.</p>

EOF - EXTCODEADDRESS instruction

Abstract</h2> Add an instruction to EOF that reads code delegation designations from an account without requiring code introspection.</p>

Max blob flag for local builders

Abstract</h2> This EIP adds a flag to the block builder in order to allow them to include a client configured maximum amount of blobs. This is an execution layer only change.</p>

Motivation</h2> Currently a builder will include all blobs in their local mempool, up to the maximum amount that the protocol requires. If a builder has low bandwidth, they may include too many blobs and subsequently end up not being able to convince the network that the blobs are available.</p>

Specification</h2> Create a parameter in block builder's configuration called USER_CONFIGURED_MAX_BLOBS_PER_BLOCK</code></li> Take the minimum out of the MAX_BLOB_GAS_PER_BLOCK</code> and the USER_CONFIGURED_MAX_BLOBS_PER_BLOCK</code></li> If the minimum is zero, set the minimum to one.</li>

Backwards Compatibility</h2> No backward compatibility issues found.</p>

Security Considerations</h2> N/A</p>

Decentralised User Profiles

Specification</h2>

Backwards Compatibility</h2> The Decentralised Profile system is designed to ensure smooth integration with existing decentralized applications (dApps) and platforms, while offering an upgrade path for future enhancements. Below are key considerations for backwards compatibility:</p>

Separate Metadata Section for EOF

Abstract</h2> Introduce a new separate metadata section to the Ethereum Object Format (EOF) that is unreachable by the code, and any changes to which does not affect the code.</p>

Data Asset NFT

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>

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>

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

Abstract</h2>
Currently, `SWAP</code> and DUP</code> instructions are limited to a stack depth of 16. Introduce three new instructions, SWAPN</code>, DUPN</code> and EXCHANGE</code> which lift this limitation and allow accessing the stack at higher depths.</p>`

Security Considerations</h2>
The authors are not aware of any additional risks introduced here. The EVM stack is fixed at 1024 items and most implementations keep that in memory at all times. This change will increase the number of stack items accessible via single instruction.</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", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.</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>

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>

Backwards Compatibility</h2>
The new SSZ types coexist with existing types without conflict and share their serialization logic.</p>

Reference Implementation</h2>
See `ethereum/remerkleable</code>.</p>`

Abstract</h2>
Add an instruction to EOF that reads code delegation designations from an account without requiring code introspection.</p>

Abstract</h2>
This EIP adds a flag to the block builder in order to allow them to include a client configured maximum amount of blobs. This is an execution layer only change.</p>

Motivation</h2>
Currently a builder will include all blobs in their local mempool, up to the maximum amount that the protocol requires. If a builder has low bandwidth, they may include too many blobs and subsequently end up not being able to convince the network that the blobs are available.</p>

Backwards Compatibility</h2>
No backward compatibility issues found.</p>

Security Considerations</h2>
N/A</p>

Abstract</h2>
Introduce a new separate metadata section to the Ethereum Object Format (EOF) that is unreachable by the code, and any changes to which does not affect the code.</p>