Ethereum Improvement Proposals - Last Call

Referable NFT Royalties

2025-10-02T00:00:00+00:00

Abstract</h2>
This ERC proposes Royalty

Motivatio
Specif
The key words "MUST",

Interface</h3>

The IRNFTRoyalty

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

 uRWA - Universal 2025-06-10T00:00:00+00:00

Distribution, a standalone royalty distribution for Referable Non-Fungible Tokens (rNFTs). It enables royalty distribution to multiple recipients at the primary level and referenced NFTs in the directed acyclic graph (DAG), with a single depth limit to control propagation. The standard is independent of ERC-2981</a>. and token-standard-agnostic, but expects ERC-5521</a> rNFTs, which in practice build on ERC-721</a> ownership semantics. It includes a function to query fixed royalty amounts (in basis points) for transparency. Royalties are voluntary, transparent, and configurable on-chain, supporting collaborative ecosystems and fair compensation.</p> n</h2> ;wg-eips.ritovision.com/5521/">ERC-5521</a> introduces Referable NFTs (rNFTs), which form a DAG through "referring" and "referred" relationships. Existing royalty standards like ERC-2981</a> do not account for this structure or support multiple recipients per level. This EIP addresses the need for a royalty mechanism that:</p> recipients per royalty level (e.g., creators and collaborators).</li> to referenced NFTs in the DAG.</li> with a single reference depth.</li> to query fixed royalty amounts without a sale price.</li> to query fixed royalty amounts with a sale price.</li> of ERC-721</a> or ERC-2981</a>.</li> for marketplaces and users.</li> via ERC-165</a> supportsInterface.</li> EIP-712</a> signature-based configuration to streamline marketplace or owner-driven updates.</li> ication</h2> "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.</p> interface defines the royalty distribution for rNFTs and MUST inherit ERC165</code> so that supporting contracts can advertise compliance via ERC-165</a>:</p> data-lang="solidity">//</span> SPDX-License-Identifier: CC0-1.0</span></span> class="z-keyword">pragma</span> solidity</span> ^0.8.0</span>;</span></span> class="z-storage z-type">interface</span> IRNFTRoyalty</span> is</span> ERC165</span> {</span></span> class="z-storage z-type">    struct</span> RoyaltyInfo</span> {</span></span> class="z-support">        address</span> recipient</span>;</span> //</span> Address to receive royalty</span></span> class="z-support">        uint256</span> royaltyAmount</span>;</span> //</span> Royalty amount (in wei for sale-based queries, basis points for fixed queries)</span></span> }</span></span> class="z-storage z-type">    struct</span> ReferenceRoyalty</span> {</span></span> RoyaltyInfo</span>[</span>]</span> royaltyInfos</span>;</span> //</span> Array of recipients and their royalty amounts</span></span> class="z-support">        uint256</span> referenceDepth</span>;</span> //</span> Maximum depth in the reference DAG for royalty distribution</span></span> }</span></span> class="z-storage z-type">    event</span> ReferenceRoyaltiesPaid</span>(</span></span> class="z-support">        address</span> indexed</span> rNFTContract</span>,</span></span> class="z-support">        uint256</span> indexed</span> tokenId</span>,</span></span> class="z-support">        address</span> indexed</span> buyer</span>,</span></span> class="z-support">        address</span> marketplace</span>,</span></span> class="z-variable">        ReferenceRoyalty</span> royalties</span></span> )</span>;</span></span> class="z-storage z-type">    function</span> getReferenceRoyaltyInfo</span>(</span></span> class="z-support">        address</span> rNFTContract</span>,</span></span> class="z-support">        uint256</span> tokenId</span>,</span></span> class="z-support">        uint256</span> salePrice</span></span> )</span> external</span> view</span> returns</span> (</span>ReferenceRoyalty</span> memory</span> royalties</span>)</span>;</span></span> class="z-storage z-type">    function</span> getReferenceRoyaltyInfo</span>(</span></span> class="z-support">        address</span> rNFTContract</span>,</span></span> class="z-support">        uint256</span> tokenId</span></span> )</span> external</span> view</span> returns</span> (</span>ReferenceRoyalty</span> memory</span> royalties</span>)</span>;</span></span> class="z-storage z-type">    function</span> setReferenceRoyalty</span>(</span></span> class="z-support">        address</span> rNFTContract</span>,</span></span> class="z-support">        uint256</span> tokenId</span>,</span></span> class="z-support">        address</span>[</span>]</span> memory</span> recipients</span>,</span></span> class="z-support">        uint256</span>[</span>]</span> memory</span> royaltyFractions</span>,</span></span> class="z-support">        uint256</span> referenceDepth</span></span> )</span> external</span>;</span></span> </span></span> class="z-storage z-type">    function</span> setReferenceRoyalty</span>(</span></span> class="z-support">        address</span> rNFTContract</span>,</span></span> class="z-support">        uint256</span> tokenId</span>,</span></span> class="z-support">        address</span>[</span>]</span> memory</span> recipients</span>,</span></span> class="z-support">        uint256</span>[</span>]</span> memory</span> royaltyFractions</span>,</span></span> class="z-support">        uint256</span> referenceDepth</span>,</span></span> class="z-support">        address</span> signer</span>,</span></span> class="z-support">        uint256</span> deadline</span>,</span></span> class="z-support">        bytes</span> calldata</span> signature</span></span> )</span> external</span>;</span></span> class="z-storage z-type">    function</span> supportsReferenceRoyalties</span>(</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span> </span></span> class="z-storage z-type">    function</span> royaltyNonce</span>(</span>address</span> signer</span>,</span> address</span> rNFTContract</span>,</span> uint256</span> tokenId</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span> }</span></span></code></pre>
ERC-165 requirement</h3> MUST return true for supportsInterface(type(IRNFTRoyalty).interfaceId)</code>.</li> (e.g., AccessControl) SHOULD be forwarded via super.supportsInterface(interfaceId)</code> when using inheritance.</li> guration">Signature-Based Configuration</h3> and flexible configuration, implementations MUST support the following semantics for the signature overload:</p> recovered EIP-712 signer MUST satisfy one of: ract).ownerOf(tokenId)</code> at verification time.</li> message MUST include a nonce; the contract MUST track, verify, and increment a nonce to prevent replay.</li> EIP-712 domain and struct as below (reference implementation provided).</li> compared against block.timestamp; signatures with block.timestamp > deadline MUST be rejected.</li> version = "2", chainId, verifyingContract = address(this)</li> data-lang="plain">SetReferenceRoyalty(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> bytes32 recipientsHash,        // keccak256(abi.encode(recipients))</span></span> bytes32 royaltyFractionsHash,  // keccak256(abi.encode(royaltyFractions))</span></span> uint256 referenceDepth,</span></span> address signer,</span></span> uint256 deadline,</span></span> uint256 nonce</span></span> )</span></span></code></pre>Key Components</h3> to receive the royalty payment.</li> The royalty amount, in wei for getReferenceRoyaltyInfo</code> with salePrice, or basis points (e.g., 100 = 1%) for getReferenceRoyaltyInfo</code> without salePrice.</li> An array of RoyaltyInfo</code> for multiple recipients at the primary level and referenced NFTs.</li> A single value limiting royalty distribution to referenced NFTs in the DAG.</li> rNFTContract, uint256 tokenId, uint256 salePrice)</code>:</p> struct with royalty amounts in wei, calculated from the salePrice.</li> royalties and referenced NFT royalties up to referenceDepth</code>.</li> amounts if no royalties are configured or if salePrice is zero.</li> rNFTContract, uint256 tokenId)</code>:</p> struct with fixed royalty amounts in basis points (e.g., 100 = 1%).</li> royalties and referenced NFT royalties up to referenceDepth.</li> configured royalty fractions without sale price calculations.</li> rNFTContract, uint256 tokenId, address[] recipients, uint256[] royaltyFractions, uint256 referenceDepth)</code>:</p> for the specified rNFT.</li> (in basis points) define primary-level royalties.</li> royalty distribution to referenced NFTs.</li> to authorized parties (e.g., rNFT contract owner).</li> primary-level royalty cap of ≤ 1000 basis points (10%).</li> rNFTContract, uint256 tokenId, address[] recipients, uint256[] royaltyFractions, uint256 referenceDepth, address signer, uint256 deadline, bytes signature)</code>:</p> configuration per EIP-712.</li> authorization, nonce, and enforce deadline to reject expired signatures.</li> specifies which address is expected to have signed the message, enabling relayer execution.</li> alties()</code>:</p> the contract implements this standard. Discovery MUST rely on ERC-165.</li> signer, address rNFTContract, uint256 tokenId) external view returns (uint256)</code>:</p> nonce used for EIP-712 signatures.</li> aid</code>: Emitted when royalties are paid, logging the rNFT contract, token ID, buyer, marketplace, and ReferenceRoyalty</code> details (with royaltyAmount in wei).</li> model">Royalty Distribution Model</h3> The rNFT’s royaltyInfos array specifies multiple recipients and their fractions (e.g., 5% total, split as 3% and 2%).</li> At each hop, a total forwarded share equal to REFERRED_ROYALTY_FRACTION (e.g., 200 bps / 2%) is carved out and distributed across all referenced NFTs at that depth proportional to their configured weights (fallback: evenly if all weights are zero).</li> (Primary Level): The 10% (1000 bps) cap applies to the primary-level configured royaltyFractions. Propagated/reference-level flows are governed separately by REFERRED_ROYALTY_FRACTION and referenceDepth.</li> MUST cap referenceDepth</code>; this reference implementation enforces <= 3 (RECOMMENDED).</li> The getReferenceRoyaltyInfo</code> function without salePrice returns royalty fractions in basis points, enabling transparent inspection.</li> 0xABC, token ID 1) with referenceDepth</code> = 2:</p> 5% (3% to creator, 2% to collaborator).</li> NFTs; a total of 2% is forwarded at depth 1 and split equally (1% each) under equal weights.</li> (capped by referenceDepth).</li> 1)</code>:</p> {recipient: creator, royaltyAmount: 300}, {recipient: collaborator, royaltyAmount: 200}, {recipient: tokenA_owner, royaltyAmount: 100}, {recipient: tokenB_owner, royaltyAmount: 100} ], referenceDepth: 2 }.</p> 1, 100 ether) returns:</p> {recipient: creator, royaltyAmount: 3 ether}, {recipient: collaborator, royaltyAmount: 2 ether}, {recipient: tokenA_owner, royaltyAmount: 1 ether}, {recipient: tokenB_owner, royaltyAmount: 1 ether} ], referenceDepth: 2 }.</p> The new getReferenceRoyaltyInfo</code> function without salePrice allows users to inspect fixed royalty fractions (in basis points), improving transparency.</li> The RoyaltyInfo</code> array supports collaborative projects.</li> Simplifies configuration and reduces gas costs.</li> Ensures compatibility with any ERC-5521 contract.</li> Aligns with marketplace practices.</li> storage and fixed-amount queries enable verifiable royalties.</li> Marketplaces and wallets can reliably detect support via supportsInterface, avoiding ad-hoc feature flags.</li> Off-chain approvals enable safe, gas-efficient configurations.</li> Compatibility</h2> independent of ERC-2981 and targets ERC-5521 rNFTs, which in practice build on ERC-721 ownership semantics. Marketplaces can integrate by:</p> supportsInterface(type(IRNFTRoyalty).interfaceId)</code>.</li> eRoyaltyInfo</code> (with or without sale price).</li> the signature-based configuration for off-chain workflows.</li> ion">Reference Implementation</h2> data-lang="plain">// SPDX-License-Identifier: CC0-1.0</span></span> solidity ^0.8.0;</span></span> "@openzeppelin/contracts/access/AccessControl.sol";</span></span> "@openzeppelin/contracts/utils/cryptography/EIP712.sol"; </span></span> "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";</span></span> "@openzeppelin/contracts/utils/introspection/IERC165.sol";</span></span> "@openzeppelin/contracts/token/ERC721/IERC721.sol";</span></span> "@openzeppelin/contracts/utils/ReentrancyGuard.sol";</span></span> "./IRNFTRoyalty.sol";</span></span> IERC_5521 is IERC165 {</span></span> function setNode(uint256 tokenId, address[] memory addresses, uint256[][] memory tokenIds) external;</span></span> function referringOf(address _address, uint256 tokenId) external view returns (address[] memory, uint256[][] memory);</span></span> function referredOf(address _address, uint256 tokenId) external view returns (address[] memory, uint256[][] memory);</span></span> function supportsInterface(bytes4 interfaceId) external view returns (bool);</span></span> }</span></span> RNFTRoyalty is IRNFTRoyalty, AccessControl, EIP712, ReentrancyGuard {</span></span> using ECDSA for bytes32;</span></span> bytes32 public constant CONFIGURATOR_ROLE = keccak256("CONFIGURATOR_ROLE");</span></span> uint256 private constant MAX_ROYALTY_FRACTION = 1000; // 10%</span></span> uint256 private constant REFERRED_ROYALTY_FRACTION = 200; // 2%</span></span> uint256 private constant MAX_CHAIN_STEPS = 32;</span></span> uint256 private constant MAX_RECIPIENTS = 64;</span></span> // storage</span></span> mapping(address => mapping(uint256 => ReferenceRoyalty)) private _royalties;</span></span> event ReferenceRoyaltyConfigured(</span></span> address indexed rNFTContract,</span></span> uint256 indexed tokenId,</span></span> address indexed setter,</span></span> address[] recipients,</span></span> uint256[] royaltyFractions,</span></span> uint256 referenceDepth,</span></span> bool viaSignature</span></span> );</span></span> // EIP-712 typed data & nonce</span></span> bytes32 private constant _SET_TYPEHASH =</span></span> keccak256("SetReferenceRoyalty(address rNFTContract,uint256 tokenId,bytes32 recipientsHash,bytes32 royaltyFractionsHash,uint256 referenceDepth,address signer,uint256 deadline,uint256 nonce)");</span></span> // (signer => rNFT => tokenId => nonce)</span></span> mapping(address => mapping(address => mapping(uint256 => uint256))) private _sigNonces;</span></span> constructor() EIP712("RNFTRoyalty", "2") {</span></span> _grantRole(DEFAULT_ADMIN_ROLE, msg.sender);</span></span> _grantRole(CONFIGURATOR_ROLE, msg.sender);</span></span> }</span></span> // ===== IRNFTRoyalty =====</span></span> // expose nonce for off-chain signing</span></span> function royaltyNonce(address signer, address rNFTContract, uint256 tokenId)</span></span> external</span></span> view</span></span> returns (uint256)</span></span> {</span></span> return _sigNonces[signer][rNFTContract][tokenId];</span></span> }</span></span> function setReferenceRoyalty(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address[] calldata recipients,</span></span> uint256[] calldata royaltyFractions,</span></span> uint256 referenceDepth</span></span> ) external onlyRole(CONFIGURATOR_ROLE) {</span></span> _configureRoyalty(rNFTContract, tokenId, recipients, royaltyFractions, referenceDepth);</span></span> emit ReferenceRoyaltyConfigured(</span></span> rNFTContract,</span></span> tokenId,</span></span> msg.sender,</span></span> recipients,</span></span> royaltyFractions,</span></span> referenceDepth,</span></span> false</span></span> );</span></span> }</span></span> /// @notice Configure reference royalty via EIP-712 signature (supports relayers).</span></span> /// @dev</span></span> /// - Uses explicit `signer` for nonce lookup and authorization; caller can be a relayer.</span></span> /// - Includes `deadline` in the signed struct; reverts with "Signature expired" if now > deadline.</span></span> /// - Non-reentrant to defend against malicious `rNFT.ownerOf` implementations.</span></span> /// - Authorization: `signer` must have `CONFIGURATOR_ROLE` or be current `ownerOf(tokenId)`.</span></span> /// - Nonce scope: per-signer-per-token; increments on success to prevent replay.</span></span> function setReferenceRoyalty(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address[] calldata recipients,</span></span> uint256[] calldata royaltyFractions,</span></span> uint256 referenceDepth,</span></span> address signer,</span></span> uint256 deadline,</span></span> bytes calldata signature</span></span> ) external nonReentrant {</span></span> _checkParams(rNFTContract, recipients, royaltyFractions, referenceDepth);</span></span> bytes32 recipientsHash = keccak256(abi.encode(recipients));</span></span> bytes32 fractionsHash  = keccak256(abi.encode(royaltyFractions));</span></span> // Compute expected signer digest and use per-signer-per-token nonce (explicit signer for relaying)</span></span> require(signer != address(0), "Invalid signer");</span></span> uint256 nonce = _sigNonces[signer][rNFTContract][tokenId];</span></span> require(block.timestamp <= deadline, "Signature expired");</span></span> bytes32 structHash = keccak256(</span></span> abi.encode(</span></span> _SET_TYPEHASH,</span></span> rNFTContract,</span></span> tokenId,</span></span> recipientsHash,</span></span> fractionsHash,</span></span> referenceDepth,</span></span> signer,</span></span> deadline,</span></span> nonce</span></span> )</span></span> );</span></span> bytes32 digest = _hashTypedDataV4(structHash);</span></span> address recovered = ECDSA.recover(digest, signature);</span></span> require(recovered == signer && signer != address(0), "Invalid signature");</span></span> // Authorization: CONFIGURATOR_ROLE or current owner</span></span> bool authorized = hasRole(CONFIGURATOR_ROLE, signer);</span></span> if (!authorized) {</span></span> address owner = _safeOwnerOf(IERC721(rNFTContract), tokenId);</span></span> require(signer == owner, "Signer not authorized");</span></span> }</span></span> // effects: bump nonce to prevent replay</span></span> _sigNonces[signer][rNFTContract][tokenId] = nonce + 1;</span></span> // configure royalties</span></span> _configureRoyalty(rNFTContract, tokenId, recipients, royaltyFractions, referenceDepth);</span></span> emit ReferenceRoyaltyConfigured(</span></span> rNFTContract,</span></span> tokenId,</span></span> signer,</span></span> recipients,</span></span> royaltyFractions,</span></span> referenceDepth,</span></span> true</span></span> );</span></span> }</span></span> /// @notice Compute reference royalty distribution for a concrete sale price (values in wei).</span></span> /// @param rNFTContract RNFT contract implementing IERC_5521</span></span> /// @param tokenId Token id</span></span> /// @param salePrice Sale price in wei</span></span> function getReferenceRoyaltyInfo(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> uint256 salePrice</span></span> ) external view returns (ReferenceRoyalty memory royalties) {</span></span> royalties = _royalties[rNFTContract][tokenId];</span></span> if (salePrice == 0) {</span></span> uint256 len = royalties.royaltyInfos.length;</span></span> if (len == 0) return royalties;</span></span> RoyaltyInfo[] memory zeroed = new RoyaltyInfo[](len);</span></span> for (uint256 i = 0; i < len; i++) {</span></span> zeroed[i] = RoyaltyInfo(royalties.royaltyInfos[i].recipient, 0);</span></span> }</span></span> royalties.royaltyInfos = zeroed;</span></span> return royalties;</span></span> }</span></span> RoyaltyInfo[] memory chainRoyalties = _calculateChainRoyalties(rNFTContract, tokenId, salePrice);</span></span> royalties.royaltyInfos = chainRoyalties;</span></span> return royalties;</span></span> }</span></span> /// @notice Compute reference royalty distribution in basis points (bps), i.e. relative amounts.</span></span> /// @param rNFTContract RNFT contract implementing IERC_5521</span></span> /// @param tokenId Token id</span></span> function getReferenceRoyaltyInfo(</span></span> address rNFTContract,</span></span> uint256 tokenId</span></span> ) external view returns (ReferenceRoyalty memory royalties) {</span></span> royalties = _royalties[rNFTContract][tokenId];</span></span> if (royalties.royaltyInfos.length == 0) return royalties;</span></span> RoyaltyInfo[] memory bpsRoyalties = _calculateChainRoyalties(rNFTContract, tokenId, 0);</span></span> royalties.royaltyInfos = bpsRoyalties;</span></span> return royalties;</span></span> }</span></span> function supportsReferenceRoyalties() external pure returns (bool) {</span></span> return true;</span></span> }</span></span> // ===== ERC-165 =====</span></span> function supportsInterface(bytes4 interfaceId)</span></span> public</span></span> view</span></span> override(AccessControl, IERC165)</span></span> returns (bool)</span></span> {</span></span> return</span></span> interfaceId == type(IRNFTRoyalty).interfaceId ||</span></span> super.supportsInterface(interfaceId);</span></span> }</span></span> // ===== Internal =====</span></span> function _checkParams(</span></span> address rNFTContract,</span></span> address[] calldata recipients,</span></span> uint256[] calldata royaltyFractions,</span></span> uint256 referenceDepth</span></span> ) internal pure {</span></span> require(rNFTContract != address(0), "Invalid contract");</span></span> require(recipients.length == royaltyFractions.length, "Length mismatch");</span></span> require(recipients.length <= MAX_RECIPIENTS, "Too many recipients");</span></span> require(referenceDepth <= 3, "Depth too high");</span></span> for (uint256 i = 0; i < recipients.length; ++i) {</span></span> require(recipients[i] != address(0), "Zero recipient");</span></span> }</span></span> }</span></span> function _configureRoyalty(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address[] calldata recipients,</span></span> uint256[] calldata royaltyFractions,</span></span> uint256 referenceDepth</span></span> ) internal {</span></span> uint256 totalFraction = 0;</span></span> for (uint256 i = 0; i < royaltyFractions.length; i++) {</span></span> totalFraction += royaltyFractions[i];</span></span> }</span></span> require(totalFraction <= MAX_ROYALTY_FRACTION, "Royalty cap exceeded");</span></span> ReferenceRoyalty memory config;</span></span> config.referenceDepth = referenceDepth;</span></span> config.royaltyInfos = new RoyaltyInfo[](recipients.length);</span></span> for (uint256 i = 0; i < recipients.length; i++) {</span></span> config.royaltyInfos[i] = RoyaltyInfo(recipients[i], royaltyFractions[i]);</span></span> }</span></span> _royalties[rNFTContract][tokenId] = config;</span></span> }</span></span> function _safeOwnerOf(IERC721 rNFT, uint256 tokenId) internal view returns (address) {</span></span> address owner = rNFT.ownerOf(tokenId);</span></span> require(owner != address(0), "No owner");</span></span> return owner;</span></span> }</span></span> function _calculateChainRoyalties(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> uint256 salePrice</span></span> ) internal view returns (RoyaltyInfo[] memory) {</span></span> ReferenceRoyalty memory currentRoyalty = _royalties[rNFTContract][tokenId];</span></span> if (currentRoyalty.royaltyInfos.length == 0) {</span></span> return new RoyaltyInfo[](0);</span></span> }</span></span> RoyaltyInfo[] memory staged = new RoyaltyInfo[](MAX_CHAIN_STEPS * 32 + 32);</span></span> uint256 count = 0;</span></span> uint256 totalShare = _sumShares(currentRoyalty);</span></span> (uint256 netPrimary, uint256 remainder) = _splitRoyalty(totalShare, salePrice, currentRoyalty.referenceDepth > 0);</span></span> count = _appendDistribution(staged, count, currentRoyalty, netPrimary);</span></span> if (remainder == 0) {</span></span> return _shrink(staged, count);</span></span> }</span></span> // Layered aggregation (BFS) to support multi-parent merges</span></span> uint256 maxItems = MAX_CHAIN_STEPS * 32 + 32;</span></span> address[] memory curContracts = new address[](maxItems);</span></span> uint256[] memory curIds = new uint256[](maxItems);</span></span> uint256[] memory curAmts = new uint256[](maxItems);</span></span> uint256[] memory curDepths = new uint256[](maxItems);</span></span> uint256 curCount = 0;</span></span> if (remainder > 0 && currentRoyalty.referenceDepth > 0) {</span></span> curContracts[0] = rNFTContract;</span></span> curIds[0] = tokenId;</span></span> curAmts[0] = remainder;</span></span> curDepths[0] = currentRoyalty.referenceDepth;</span></span> curCount = 1;</span></span> }</span></span> address[] memory processedContracts = new address[](maxItems);</span></span> uint256[] memory processed = new uint256[](maxItems);</span></span> uint256 processedCount = 0;</span></span> while (curCount > 0) {</span></span> address[] memory nextContracts = new address[](maxItems);</span></span> uint256[] memory nextIds = new uint256[](maxItems);</span></span> uint256[] memory nextAmts = new uint256[](maxItems);</span></span> uint256[] memory nextDepths = new uint256[](maxItems);</span></span> uint256 nextCount = 0;</span></span> for (uint256 iL = 0; iL < curCount; iL++) {</span></span> address curContract = curContracts[iL];</span></span> uint256 curId = curIds[iL];</span></span> uint256 amt = curAmts[iL];</span></span> uint256 depth = curDepths[iL];</span></span> if (amt == 0) continue;</span></span> IERC_5521 curRNFT = IERC_5521(curContract);</span></span> IERC721 curRNFT721 = IERC721(curContract);</span></span> bool seen = false;</span></span> for (uint256 p = 0; p < processedCount; p++) {</span></span> if (processed[p] == curId && processedContracts[p] == curContract) { seen = true; break; }</span></span> }</span></span> if (seen) {</span></span> address cycOwner = _safeOwnerOf(curRNFT721, curId);</span></span> staged[count++] = RoyaltyInfo(cycOwner, amt);</span></span> continue;</span></span> }</span></span> uint256 maxChildren = 32;</span></span> address[] memory childContracts = new address[](maxChildren);</span></span> uint256[] memory childIds = new uint256[](maxChildren);</span></span> uint256 children = _collectReferring(curRNFT, curContract, curId, childContracts, childIds);</span></span> if (depth == 0 || children == 0) {</span></span> address fallbackOwner = _safeOwnerOf(curRNFT721, curId);</span></span> staged[count++] = RoyaltyInfo(fallbackOwner, amt);</span></span> processedContracts[processedCount] = curContract;</span></span> processed[processedCount++] = curId;</span></span> continue;</span></span> }</span></span> uint256 keepBase = (amt * (10_000 - REFERRED_ROYALTY_FRACTION)) / 10_000;</span></span> uint256 passBase = amt - keepBase;</span></span> uint256[] memory childWeights = new uint256[](maxChildren);</span></span> ReferenceRoyalty[] memory childConfigs = new ReferenceRoyalty[](maxChildren);</span></span> uint256 sumWeights = 0;</span></span> for (uint256 j = 0; j < children; j++) {</span></span> address childContract = childContracts[j];</span></span> uint256 cid = childIds[j];</span></span> ReferenceRoyalty memory cfg = _royalties[childContract][cid];</span></span> childConfigs[j] = cfg;</span></span> if (cfg.royaltyInfos.length > 0) {</span></span> uint256 w = _sumShares(cfg);</span></span> childWeights[j] = w;</span></span> sumWeights += w;</span></span> }</span></span> }</span></span> if (sumWeights == 0) {</span></span> uint256 each = amt / children;</span></span> uint256 rem = amt - (each * children);</span></span> for (uint256 j = 0; j < children; j++) {</span></span> address ow = _safeOwnerOf(IERC721(childContracts[j]), childIds[j]);</span></span> uint256 share = each + (j == children - 1 ? rem : 0);</span></span> staged[count++] = RoyaltyInfo(ow, share);</span></span> }</span></span> processedContracts[processedCount] = curContract;</span></span> processed[processedCount++] = curId;</span></span> continue;</span></span> }</span></span> uint256 passDistributed = 0;</span></span> uint256 lastWeightedIdx = 0;</span></span> uint256[] memory keepShares = new uint256[](children);</span></span> uint256[] memory passShares = new uint256[](children);</span></span> for (uint256 j = 0; j < children; j++) {</span></span> if (childWeights[j] == 0) continue;</span></span> lastWeightedIdx = j;</span></span> uint256 kShare = (keepBase * childWeights[j]) / sumWeights;</span></span> uint256 pShare = (passBase * childWeights[j]) / sumWeights;</span></span> keepShares[j] = kShare;</span></span> passShares[j] = pShare;</span></span> passDistributed += pShare;</span></span> }</span></span> // Remainders: pass and keep</span></span> uint256 passRemainder = passBase - passDistributed;</span></span> if (passRemainder > 0) {</span></span> passShares[lastWeightedIdx] += passRemainder;</span></span> }</span></span> uint256 keepDistributed = 0;</span></span> for (uint256 j2 = 0; j2 < children; j2++) {</span></span> keepDistributed += keepShares[j2];</span></span> }</span></span> uint256 keepRemainder = keepBase - keepDistributed;</span></span> if (keepRemainder > 0) {</span></span> keepShares[lastWeightedIdx] += keepRemainder;</span></span> }</span></span> for (uint256 j = 0; j < children; j++) {</span></span> if (childWeights[j] == 0) continue;</span></span> uint256 kShare = keepShares[j];</span></span> uint256 pShare = passShares[j];</span></span> ReferenceRoyalty memory cfgj = childConfigs[j];</span></span> uint256 cid2 = childIds[j];</span></span> address childContract = childContracts[j];</span></span> uint256 nextDepth = depth > 0 ? depth - 1 : 0;</span></span> if (nextDepth == 0) {</span></span> // Depth exhausted: distribute both keep and pass to child's recipients</span></span> count = _appendDistribution(staged, count, cfgj, kShare + pShare);</span></span> } else {</span></span> if (kShare > 0) {</span></span> count = _appendDistribution(staged, count, cfgj, kShare);</span></span> }</span></span> if (pShare > 0) {</span></span> bool merged = false;</span></span> for (uint256 nx = 0; nx < nextCount; nx++) {</span></span> if (nextIds[nx] == cid2 && nextContracts[nx] == childContract) {</span></span> nextAmts[nx] += pShare;</span></span> if (nextDepth > nextDepths[nx]) {</span></span> nextDepths[nx] = nextDepth;</span></span> }</span></span> merged = true;</span></span> break;</span></span> }</span></span> }</span></span> if (!merged) {</span></span> nextContracts[nextCount] = childContract;</span></span> nextIds[nextCount] = cid2;</span></span> nextAmts[nextCount] = pShare;</span></span> nextDepths[nextCount] = nextDepth;</span></span> nextCount++;</span></span> }</span></span> }</span></span> }</span></span> }</span></span> processedContracts[processedCount] = curContract;</span></span> processed[processedCount++] = curId;</span></span> }</span></span> for (uint256 k = 0; k < nextCount; k++) {</span></span> curContracts[k] = nextContracts[k];</span></span> curIds[k] = nextIds[k];</span></span> curAmts[k] = nextAmts[k];</span></span> curDepths[k] = nextDepths[k];</span></span> }</span></span> curCount = nextCount;</span></span> }</span></span> return _shrink(staged, count);</span></span> }</span></span> function _splitRoyalty(uint256 totalRate, uint256 salePrice, bool canPropagate)</span></span> internal</span></span> pure</span></span> returns (uint256 netPrimary, uint256 forwardedAmount)</span></span> {</span></span> if (totalRate == 0) {</span></span> return (0, 0);</span></span> }</span></span> if (!canPropagate) {</span></span> if (salePrice == 0) {</span></span> return (totalRate, 0);</span></span> }</span></span> return ((salePrice * totalRate) / 10_000, 0);</span></span> }</span></span> if (salePrice == 0) {</span></span> if (totalRate <= REFERRED_ROYALTY_FRACTION) {</span></span> return (0, totalRate);</span></span> }</span></span> return (totalRate - REFERRED_ROYALTY_FRACTION, REFERRED_ROYALTY_FRACTION);</span></span> }</span></span> uint256 gross = (salePrice * totalRate) / 10_000;</span></span> uint256 forwarded = (salePrice * REFERRED_ROYALTY_FRACTION) / 10_000;</span></span> if (forwarded > gross) {</span></span> forwarded = gross;</span></span> }</span></span> return (gross > forwarded ? gross - forwarded : 0, forwarded);</span></span> }</span></span> function _sumShares(ReferenceRoyalty memory config) internal pure returns (uint256 total) {</span></span> for (uint256 i = 0; i < config.royaltyInfos.length; i++) {</span></span> total += config.royaltyInfos[i].royaltyAmount;</span></span> }</span></span> }</span></span> function _collectReferring(</span></span> IERC_5521 rNFT,</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address[] memory childContracts,</span></span> uint256[] memory childIds</span></span> ) internal view returns (uint256 childCount) {</span></span> (address[] memory refContracts, uint256[][] memory refTokenIds) =</span></span> rNFT.referringOf(rNFTContract, tokenId);</span></span> uint256 maxChildren = childIds.length;</span></span> uint256 listLen = refContracts.length;</span></span> if (refTokenIds.length < listLen) {</span></span> listLen = refTokenIds.length;</span></span> }</span></span> for (uint256 i = 0; i < listLen && childCount < maxChildren; i++) {</span></span> uint256[] memory ids = refTokenIds[i];</span></span> for (uint256 j = 0; j < ids.length && childCount < maxChildren; j++) {</span></span> childContracts[childCount] = refContracts[i];</span></span> childIds[childCount] = ids[j];</span></span> childCount++;</span></span> }</span></span> }</span></span> }</span></span> function _appendDistribution(</span></span> RoyaltyInfo[] memory staged,</span></span> uint256 count,</span></span> ReferenceRoyalty memory config,</span></span> uint256 amount</span></span> ) internal pure returns (uint256) {</span></span> uint256 len = config.royaltyInfos.length;</span></span> if (len == 0) {</span></span> return count;</span></span> }</span></span> require(count + len <= staged.length, "royalty overflow");</span></span> if (amount == 0) {</span></span> for (uint256 i = 0; i < len; i++) {</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[i].recipient, 0);</span></span> }</span></span> return count;</span></span> }</span></span> uint256 totalShare = _sumShares(config);</span></span> if (totalShare == 0) {</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[0].recipient, amount);</span></span> for (uint256 i = 1; i < len; i++) {</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[i].recipient, 0);</span></span> }</span></span> return count;</span></span> }</span></span> uint256 remaining = amount;</span></span> for (uint256 i = 0; i < len; i++) {</span></span> uint256 share = config.royaltyInfos[i].royaltyAmount;</span></span> if (share == 0) {</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[i].recipient, 0);</span></span> continue;</span></span> }</span></span> uint256 portion = (amount * share) / totalShare;</span></span> if (portion > remaining) {</span></span> portion = remaining;</span></span> }</span></span> remaining -= portion;</span></span> staged[count++] = RoyaltyInfo(config.royaltyInfos[i].recipient, portion);</span></span> }</span></span> if (remaining > 0) {</span></span> staged[count - 1].royaltyAmount += remaining;</span></span> }</span></span> return count;</span></span> }</span></span> function _shrink(RoyaltyInfo[] memory staged, uint256 count)</span></span> internal</span></span> pure</span></span> returns (RoyaltyInfo[] memory out)</span></span> {</span></span> out = new RoyaltyInfo[](count);</span></span> for (uint256 i = 0; i < count; i++) {</span></span> out[i] = staged[i];</span></span> }</span></span> }</span></span> function recordRoyaltyPayment(</span></span> address rNFTContract,</span></span> uint256 tokenId,</span></span> address buyer,</span></span> ReferenceRoyalty memory royalties</span></span> ) external {</span></span> emit ReferenceRoyaltiesPaid(rNFTContract, tokenId, buyer, msg.sender, royalties);</span></span> }</span></span> }</span></span></code></pre>Security Considerations</h2> setReferenceRoyalty</code> MUST be restricted to authorized roles (e.g., via AccessControl).</li> (Primary Level): The 10% (1000 bps) cap applies to the primary-level configured royaltyFractions. Propagated/reference-level flows are governed separately by REFERRED_ROYALTY_FRACTION and referenceDepth.</li> ceDepth</code> MUST be capped (e.g., ≤ 3) to avoid high gas costs.</li> Ensure non-zero addresses and valid royalty fractions.</li> Ensure supportsInterface forwards properly to parents.</li> Use a per-signer-per-(rNFTContract, tokenId) nonce, and increment after successful verification. Implementations MUST document the chosen scope.</li> rights waived via CC0</a>.</p> Real World Asset Interface

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


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

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

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

The canTransfer</code></p>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


DeFi Protocol Solvency Proof Mechanism
2025-01-30T00:00:00+00:00
Abstract</h2>
A standardized interface that enables DeFi protocols to implement verifiable solvency proofs through smart contracts. This interface works by defining structured data types for assets and liabilities, with oracle-validated price feeds tracking token values in real-time. The technical implementation calculates solvency ratios using configurable risk thresholds (105% minimum solvency ratio), maintains historical metrics for trend analysis, and emits structured events upon threshold breaches. The interface standardizes methods for querying current financial health, retrieving historical data points, and updating protocol positions, all while enforcing proper validation and security controls.</p>
Motivation</h2>
The DeFi ecosystem currently lacks standardization in financial health reporting, leading to:</p>

Inconsistent reporting methodologies across protocols</li>
Limited transparency in real-time financial status</li>
Absence of standardized early warning systems</li>
Complex and time-consuming audit processes</li>
Difficulty in assessing cross-protocol risks</li>
</ol>
This proposal directly addresses these challenges through a comprehensive interface that standardizes solvency reporting and monitoring:</p>


Standardized Methodology</strong>: By providing a common interface with well-defined asset/liability structures and mathematical models, this EIP eliminates reporting inconsistencies that currently prevent clear comparisons between protocols.</p>
</li>

Real-time Transparency</strong>: The proposed event system and query functions enable continuous monitoring of protocol health, rather than relying on periodic manual reporting that can miss critical changes in financial status.</p>
</li>

Automated Risk Alerts</strong>: The threshold-based alert system provides early warnings of deteriorating conditions through standardized RiskAlert</code> events, enabling faster response to potential insolvencies than current ad-hoc monitoring approaches.</p>
</li>

Efficient Audit Trail</strong>: The historical metrics tracking creates an immutable record of protocol health over time, significantly reducing audit complexity compared to current solutions that require reconstructing historical positions.</p>
</li>

Cross-Protocol Risk Assessment</strong>: A common interface enables aggregation of risk data across multiple protocols, allowing systemic risk monitoring that's impossible with today's fragmented reporting systems.</p>
</li>
</ul>
Alternative approaches considered include:</p>


Off-chain Reporting</strong>: While simpler to implement, this lacks the verifiability, real-time nature, and trustless properties of an on-chain solution.</p>
</li>

Protocol-Specific Standards</strong>: These would lack the interoperability benefits of a common standard and would perpetuate fragmentation.</p>
</li>

Complex Risk Models</strong>: More sophisticated models were evaluated but rejected in favor of this proposal's balance between comprehensiveness and implementability.</p>
</li>
</ol>
This EIP represents the optimal approach by providing a flexible yet standardized framework that can be implemented across diverse protocol types while maintaining reasonable gas efficiency and usability.</p>
The ISolvencyProof</code> interface provides a standardized, on-chain mechanism for DeFi protocols to report, verify, and monitor their solvency status. This interface is designed to be both comprehensive and flexible, supporting a wide range of protocol architectures and risk management strategies.</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>
</p>
Core Interface Requirements</h3>
Compliant implementations MUST implement the ISolvencyProof</code> interface.</p>
Compliant implementations MUST provide the following functionality:</p>


Asset and Liability Tracking</strong>: Implementations MUST store and maintain current protocol assets and liabilities with token addresses, amounts, and ETH-denominated values in contract state variables. This data MUST be updated through the updateAssets</code> and updateLiabilities</code> functions called by authorized oracles.</p>
</li>

Timestamp Recording</strong>: Implementations MUST record the timestamp of each asset and liability update.</p>
</li>

Solvency Calculation</strong>: Implementations MUST calculate the solvency ratio as (Total Assets / Total Liabilities) × 10000</code>.</p>
</li>

Historical Data</strong>: Implementations MUST maintain historical records of solvency metrics for querying within specified time ranges. Implementations MAY expire old data after a reasonable retention period (e.g., 1 year) but MUST clearly document their retention policy and available time ranges in their implementation documentation.</p>
</li>

Event Emission</strong>: Implementations MUST emit SolvencyMetricsUpdated</code> events when financial metrics are updated, and SHOULD emit RiskAlert</code> events when risk thresholds are breached.</p>
</li>

Array Validation</strong>: Implementations MUST ensure that all arrays in ProtocolAssets</code> and ProtocolLiabilities</code> structures are of equal length.</p>
</li>

Value Denomination</strong>: Implementations MUST express all values in ETH with 18 decimals for consistency.</p>
</li>
</ol>
//</span> SPDX-License-Identifier: CC0-1.0</span></span>
pragma</span> solidity</span> ^0.8.20</span>;</span></span>
</span>
/**</span></span>
 * </span>@title</span> ISolvencyProof</span></span>
 * </span>@author</span> Sean Luis (@SeanLuis) <seanluis47@gmail.com></span></span>
 * </span>@notice</span> Standard Interface for DeFi Protocol Solvency (EIP-DRAFT)</span></span>
 * </span>@dev</span> Interface for the DeFi Protocol Solvency Proof Standard</span></span>
 * </span>@custom:security</span>-contact seanluis47@gmail.com</span></span>
 * </span>@custom:version</span> 1.0.0</span></span>
 */</span></span>
interface</span> ISolvencyProof</span> {</span></span>
    /**</span></span>
     * </span>@dev</span> Protocol assets structure</span></span>
     * </span>@notice</span> Represents the current state of protocol assets</span></span>
     * </span>@custom:validation</span> All arrays must be equal length</span></span>
     * </span>@custom:validation</span> Values must be in ETH with 18 decimals</span></span>
     */</span></span>
    struct</span> ProtocolAssets</span> {</span></span>
        address</span>[</span>]</span> tokens</span>;</span>    //</span> Addresses of tracked tokens</span></span>
        uint256</span>[</span>]</span> amounts</span>;</span>   //</span> Amount of each token (in token decimals)</span></span>
        uint256</span>[</span>]</span> values</span>;</span>    //</span> Value in ETH (18 decimals) of each token amount</span></span>
        uint256</span> timestamp</span>;</span>   //</span> Last update timestamp (Unix timestamp in seconds)</span></span>
    }</span></span>
</span>
    /**</span></span>
     * </span>@dev</span> Protocol liabilities structure</span></span>
     * </span>@notice</span> Represents the current state of protocol liabilities</span></span>
     * </span>@custom:validation</span> All arrays must be equal length</span></span>
     * </span>@custom:validation</span> Values must be in ETH with 18 decimals</span></span>
     */</span></span>
    struct</span> ProtocolLiabilities</span> {</span></span>
        address</span>[</span>]</span> tokens</span>;</span>    //</span> Addresses of liability tokens</span></span>
        uint256</span>[</span>]</span> amounts</span>;</span>   //</span> Amount of each liability (in token decimals)</span></span>
        uint256</span>[</span>]</span> values</span>;</span>    //</span> Value in ETH (18 decimals) of each liability</span></span>
        uint256</span> timestamp</span>;</span>   //</span> Last update timestamp (Unix timestamp in seconds)</span></span>
    }</span></span>
</span>
    /**</span></span>
     * </span>@dev</span> Emitted on metrics update</span></span>
     * </span>@notice</span> Real-time financial health update</span></span>
     * </span>@param</span> totalAssets</span> Sum of asset values in ETH</span></span>
     * </span>@param</span> totalLiabilities</span> Sum of liability values in ETH</span></span>
     * </span>@param</span> healthFactor</span> Calculated as (totalAssets/totalLiabilities) × 10000</span></span>
     * </span>@param</span> timestamp</span> Update timestamp</span></span>
     */</span></span>
    event</span> SolvencyMetricsUpdated</span>(</span></span>
        uint256</span> totalAssets</span>,</span></span>
        uint256</span> totalLiabilities</span>,</span></span>
        uint256</span> healthFactor</span>,</span></span>
        uint256</span> timestamp</span></span>
    )</span>;</span></span>
</span>
    /**</span></span>
     * </span>@dev</span> Emitted when risk thresholds are breached</span></span>
     * </span>@notice</span> Alerts stakeholders of potential solvency risks</span></span>
     * </span></span>
     * </span>@param</span> riskLevel</span> Risk level indicating severity of the breach (CRITICAL, HIGH_RISK, WARNING)</span></span>
     * </span>@param</span> currentValue</span> Current value that triggered the alert</span></span>
     * </span>@param</span> threshold</span> Risk threshold that was breached</span></span>
     * </span>@param</span> timestamp</span> Alert timestamp</span></span>
     */</span></span>
    event</span> RiskAlert</span>(</span></span>
        string</span> riskLevel</span>,</span></span>
        uint256</span> currentValue</span>,</span></span>
        uint256</span> threshold</span>,</span></span>
        uint256</span> timestamp</span></span>
    )</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Get protocol's current assets</span></span>
     * </span>@return</span> Full</span> asset state including tokens, amounts and values</span></span>
     */</span></span>
    function</span> getProtocolAssets</span>(</span>)</span> external</span> view</span> returns</span> (</span>ProtocolAssets</span> memory</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Get protocol's current liabilities</span></span>
     * </span>@return</span> Full</span> liability state including tokens, amounts and values</span></span>
     */</span></span>
    function</span> getProtocolLiabilities</span>(</span>)</span> external</span> view</span> returns</span> (</span>ProtocolLiabilities</span> memory</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Calculate current solvency ratio</span></span>
     * </span>@return</span> SR</span> = (Total Assets / Total Liabilities) × 10000</span></span>
     */</span></span>
    function</span> getSolvencyRatio</span>(</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Check protocol solvency status</span></span>
     * </span>@return</span> isSolvent</span> True if ratio >= minimum required</span></span>
     * </span>@return</span> healthFactor</span> Current solvency ratio</span></span>
     */</span></span>
    function</span> verifySolvency</span>(</span>)</span> external</span> view</span> returns</span> (</span>bool</span> isSolvent</span>,</span> uint256</span> healthFactor</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Get historical solvency metrics</span></span>
     * </span>@param</span> startTime</span> Start of time range (Unix timestamp in seconds)</span></span>
     * </span>@param</span> endTime</span> End of time range (Unix timestamp in seconds)</span></span>
     * </span>@return</span> timestamps</span> Array of historical update timestamps (Unix timestamp in seconds)</span></span>
     * </span>@return</span> ratios</span> Array of historical solvency ratios (scaled by 10000)</span></span>
     * </span>@return</span> assets</span> Array of historical asset states</span></span>
     * </span>@return</span> liabilities</span> Array of historical liability states</span></span>
     * </span>@custom:gas</span> This function may consume significant gas for large time ranges</span></span>
     */</span></span>
    function</span> getSolvencyHistory</span>(</span>uint256</span> startTime</span>,</span> uint256</span> endTime</span>)</span> </span></span>
        external</span> </span></span>
        view</span> </span></span>
        returns</span> (</span></span>
            uint256</span>[</span>]</span> memory</span> timestamps</span>,</span></span>
            uint256</span>[</span>]</span> memory</span> ratios</span>,</span></span>
            ProtocolAssets</span>[</span>]</span> memory</span> assets</span>,</span></span>
            ProtocolLiabilities</span>[</span>]</span> memory</span> liabilities</span></span>
        )</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Update protocol assets</span></span>
     * </span>@dev</span> Only callable by authorized oracle</span></span>
     */</span></span>
    function</span> updateAssets</span>(</span></span>
        address</span>[</span>]</span> calldata</span> tokens</span>,</span></span>
        uint256</span>[</span>]</span> calldata</span> amounts</span>,</span></span>
        uint256</span>[</span>]</span> calldata</span> values</span></span>
    )</span> external</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Update protocol liabilities</span></span>
     * </span>@dev</span> Only callable by authorized oracle</span></span>
     */</span></span>
    function</span> updateLiabilities</span>(</span></span>
        address</span>[</span>]</span> calldata</span> tokens</span>,</span></span>
        uint256</span>[</span>]</span> calldata</span> amounts</span>,</span></span>
        uint256</span>[</span>]</span> calldata</span> values</span></span>
    )</span> external</span>;</span></span>
}</span></span></code></pre>Oracle Authorization Requirements</h3>
Implementations MUST restrict calls to updateAssets</code> and updateLiabilities</code> to authorized addresses only. Implementations MUST revert these function calls when msg.sender</code> is not an authorized oracle.</p>
Implementations MAY provide oracle management functions. If provided, implementations SHOULD emit events when oracle authorization changes.</p>
Example oracle management pattern (OPTIONAL):</p>
//</span> Optional oracle management pattern</span></span>
event</span> OracleUpdated</span>(</span>address</span> indexed</span> oracle</span>, </span>bool</span> authorized</span>)</span>;</span></span>
function</span> setOracle</span>(</span>address</span> oracle</span>,</span> bool</span> authorized</span>)</span> external</span>;</span></span></code></pre>
The core standard focuses on solvency verification requirements. Oracle management implementation details are left to individual protocol needs.</p>
Update Function Requirements</h3>
Implementations MUST validate input parameters for updateAssets</code> and updateLiabilities</code> functions:</p>

Implementations MUST revert if the tokens</code>, amounts</code>, and values</code> arrays are not of equal length.</li>
Implementations MUST update the timestamp field to the current block timestamp (block.timestamp</code>) when processing updates.</li>
Implementations MUST emit a SolvencyMetricsUpdated</code> event after successfully updating assets or liabilities.</li>
</ol>
Query Function Requirements</h3>
Implementations MUST provide the following query capabilities:</p>


getProtocolAssets()</code> MUST return the current state of protocol assets including all token addresses, amounts, values, and the timestamp of the last update.</p>
</li>

getProtocolLiabilities()</code> MUST return the current state of protocol liabilities including all token addresses, amounts, values, and the timestamp of the last update.</p>
</li>

getSolvencyRatio()</code> MUST calculate and return the solvency ratio as (totalAssets * 10000) / totalLiabilities</code>. If totalLiabilities</code> is zero, implementations SHOULD return a value indicating maximum solvency or revert with an appropriate error.</p>
</li>

verifySolvency()</code> MUST return both a boolean indicating solvency status and the current health factor (solvency ratio).</p>
</li>

getSolvencyHistory(startTime, endTime)</code> MUST return historical data for all recorded snapshots where the timestamp falls within the specified range (inclusive).</p>
</li>
</ol>
Interface Detection Support</h3>
Compliant implementations MUST implement the ERC-165</a> supportsInterface</code> function and MUST return true</code> for the ISolvencyProof</code> interface ID.</p>
Rationale</h2>
The standard's design prioritizes:</p>

Reliability through robust calculations</li>
Efficiency via optimized data structures</li>
Flexibility through modular design</li>
Transparency via standardized metrics</li>
</ol>
Asset and Liability Management</h4>
Authorized oracles update the protocol's asset and liability data through the updateAssets</code> and updateLiabilities</code> functions, which accept parallel arrays of token addresses, amounts, and ETH-denominated values. The interface enforces data consistency by requiring all input arrays to be of equal length and all values to be denominated in ETH with 18 decimal precision. Each update automatically timestamps the data using block.timestamp</code>, ensuring chronological ordering of financial state changes and enabling accurate historical analysis.</p>
Solvency Calculation and Verification</h4>
The getSolvencyRatio</code> function computes the current solvency ratio, defined as the total value of assets divided by the total value of liabilities, scaled by a factor of 10,000 for precision. The verifySolvency</code> function checks whether the protocol meets a minimum required solvency ratio (commonly 105%), returning both a boolean status and the current health factor. This allows both on-chain and off-chain systems to quickly assess the protocol's financial health and respond accordingly.</p>
Historical Data and Trend Analysis</h4>
The getSolvencyHistory</code> function enables retrieval of historical solvency metrics, including timestamps, ratios, and the corresponding asset and liability states over a specified time range. This historical data is crucial for reconstructing past events, analyzing risk trends, and providing transparency to stakeholders. This supports audits, regulatory requirements, and trend analysis needs.</p>
Event Emission and Risk Alerts</h4>
Whenever the protocol's financial metrics are updated, the SolvencyMetricsUpdated</code> event is emitted, providing real-time data for off-chain monitoring and analytics. When risk thresholds are breached (for example, if the solvency ratio falls below a critical level), the RiskAlert</code> event is triggered, signaling the severity and nature of the risk. These events enable automated monitoring systems, auditors, and users to receive timely notifications and take appropriate action.</p>
Oracle Integration and Security</h4>
The interface is designed to be oracle-agnostic, allowing protocols to integrate with a variety of price feed solutions (e.g., Chainlink, API3, custom oracles). The requirement that only authorized oracles can update asset and liability data ensures that updates are secure and resistant to manipulation. The optional setOracle</code> and OracleUpdated</code> event pattern is recommended for managing oracle permissions and maintaining robust security controls.</p>
Intended Usage and Integration</h4>
Protocols implementing this interface integrate with trusted oracles for price feeds and position updates, maintain up-to-date records of their financial positions, emit standardized events for off-chain monitoring and risk management, and provide transparent, verifiable, and standardized information about their solvency status to all stakeholders. External consumers (such as auditors, users, or other smart contracts) can query the protocol's current and historical solvency status using the provided view functions, and can listen for events to receive timely notifications of significant changes or risks. This design ensures that all stakeholders have access to reliable, real-time information about a protocol's financial health, enabling more robust risk management and greater trust in the DeFi ecosystem.</p>
Data Structure Design Rationale</h3>
The interface defines two primary data structures (ProtocolAssets</code> and ProtocolLiabilities</code>) with specific attributes:</p>


Array-based token tracking</strong> was selected over mapping-based approaches for:</p>

More efficient state retrieval for monitoring systems</li>
Better compatibility with historical tracking requirements</li>
Simplified batch updates in volatile market conditions</li>
</ul>
</li>

Timestamp embedding</strong> within structures rather than separate mappings provides:</p>

Atomic updates with data consistency guarantees</li>
Protection against partial-update scenarios during price volatility</li>
Single-transaction verification of data freshness</li>
</ul>
</li>

Combined value and amount tracking</strong> was implemented for:</p>

Enhanced resilience during high market volatility</li>
Ability to detect oracle manipulation by comparing historical value/amount ratios</li>
Clear audit trails for post-mortem analysis</li>
</ul>
</li>
</ol>
Test-Driven Design Decisions</h3>
Our implementation testing significantly shaped the final design:</p>


Market Crash Simulation Tests</strong></p>

Tests simulate extreme scenarios (80% ETH price drop, 70% BTC price drop)</li>
Validates the system correctly identifies insolvency when ratios fall below critical thresholds</li>
Confirms proper functionality of emergency protocols during rapid market movements</li>
</ul>
</li>

Volatility Testing</strong></p>

Test suite subjects implementation to sinusoidal price movements</li>
Validates consistent health factor calculation across 5 distinct price points</li>
Confirms historical metrics are properly recorded with sequential timestamps</li>
Verifies that price volatility is accurately reflected in solvency ratios</li>
</ul>
</li>

Oracle Integration</strong></p>

Tests confirm proper authorization controls for price updates</li>
Validates calculation consistency across different token types</li>
Demonstrates resilience against unexpected price movements</li>
</ul>
</li>
</ol>
Threshold Selection Methodology</h3>
The recommended threshold values (105%, 110%, 120%) were selected based on:</p>


Market Crash Testing</strong></p>

105% represents the critical threshold where recovery becomes unlikely</li>
Testing confirms this threshold successfully identifies insolvency scenarios</li>
System correctly triggers warnings at appropriate levels</li>
</ul>
</li>

Complex Portfolio Analysis</strong></p>

Tests with diverse portfolios (ETH, BTC, USDC, LP tokens, etc.)</li>
Complex liability structures (stablecoins + volatile assets)</li>
Thresholds provide appropriate buffer against normal market fluctuations</li>
</ul>
</li>

Gas Optimization vs. Precision</strong></p>

The selected ratio calculation method balances computational efficiency with accuracy</li>
Implementation uses fixed-point math for consistent results</li>
Storage optimizations maintain historical data while minimizing costs</li>
</ul>
</li>
</ol>
Implementation Insights</h3>
Key insights from comprehensive implementation and testing:</p>


Efficient Asset Tracking</strong></p>

The parallel arrays approach for token data minimizes storage costs</li>
Implementation maintains constant-time lookups for critical operations</li>
Bounded array sizes prevent out-of-gas scenarios</li>
</ul>
</li>

Oracle Integration Patterns</strong></p>

Permissioned oracle design prevents manipulation</li>
Clean separation between price data and protocol logic</li>
Flexible design supports various oracle implementations</li>
</ul>
</li>

Risk Management System</strong></p>

Multi-tier alert system provides graduated responses to deteriorating conditions</li>
Historical metrics enable trend analysis across market cycles</li>
Verification functions support both on-chain and off-chain monitoring systems</li>
</ul>
</li>
</ol>
These insights are derived from comprehensive testing covering market crashes, volatility scenarios, and complex asset portfolios.</p>
Mathematical Model</h3>
The solvency verification system is based on comprehensive mathematical models:</p>
1. Core Solvency Calculations</h4>
$SR = (TA / TL) × 100$</p>
Where:</p>

$TA = \sum(A_i × P_i)$  // Total Assets</li>
$TL = \sum(L_i × P_i)$  // Total Liabilities</li>
$A_i$ = Amount of asset i</li>
$P_i$ = Price of asset i</li>
$L_i$ = Liability i</li>
</ul>
2. Risk-Adjusted Health Factor</h4>
$HF = \frac{\sum(A_i × P_i × W_i)}{\sum(L_i × P_i × R_i)}$</p>
Where:</p>

$W_i$ = Risk weight of asset i $(0 < W_i \leq 1)$</li>
$R_i$ = Risk factor for liability i $(R_i \geq 1)$</li>
</ul>
3. Risk Metrics</h4>
Value at Risk (VaR)</h5>
$VaR(\alpha) = \mu - (\sigma × z(\alpha))$</p>
Where:</p>

$\mu$ = Expected return</li>
$\sigma$ = Standard deviation</li>
$z(\alpha)$ = z-value for confidence level $\alpha$</li>
</ul>
Liquidity Coverage Ratio (LCR)</h5>
$LCR = \frac{HQLA}{TNCO} × 100$</p>
Where:</p>

HQLA = High Quality Liquid Assets</li>
TNCO = Total Net Cash Outflows (30 days)</li>
</ul>
4. System Health Index</h4>
$SI = \frac{SR × w_1 + LCR × w_2 + (1/\sigma) × w_3}{w_1 + w_2 + w_3}$</p>
Where:</p>

$w_1,w_2,w_3$ = Weighting factors</li>
$\sigma$ = System volatility</li>
</ul>
5. Default Probability</h4>
$PD = N(-DD)$
$DD = \frac{ln(TA/TL) + (\mu - \sigma^2/2)T}{\sigma\sqrt{T}}$</p>
Where:</p>

DD = Distance to Default</li>
T = Time horizon</li>
N() = Standard normal distribution</li>
</ul>
Risk Thresholds</h3>
The following thresholds have been validated through extensive testing:</p>
Risk Level</th> Ratio Range</th> Action Required</th> Validation Status</th></tr></thead>

CRITICAL</td> < 105%</td> Emergency Stop</td> ✅ Validated</td></tr>
HIGH RISK</td> 105% - 110%</td> Risk Alert</td> ✅ Validated</td></tr>
WARNING</td> 110% - 120%</td> Monitor</td> ✅ Validated</td></tr>
HEALTHY</td> ≥ 120%</td> Normal</td> ✅ Validated</td></tr>
</tbody></table>
Testing has confirmed that:</p>

The system correctly handles 50% market drops</li>
Ratios are calculated accurately in all scenarios</li>
State updates maintain consistency</li>
Ratio limits are effective for early detection</li>
</ol>
</p>
Risk Assessment Framework</h3>
The standard implements a multi-tiered risk assessment system:</p>


Primary Metrics:</p>

Base Solvency Ratio (SR)</li>
Risk-Adjusted Health Factor (HF)</li>
Liquidity Coverage Ratio (LCR)</li>
</ul>
</li>

Threshold Levels:</p>
</li>
</ol>
</p>
Oracle Integration (Optional)</h3>
This standard intentionally leaves oracle implementation flexible. Protocols MAY implement price feeds in various ways:</p>


Direct Integration</p>

Using existing oracle networks (Chainlink, API3, etc.)</li>
Custom price feed implementations</li>
Internal price calculations</li>
</ul>
</li>

Aggregation Strategies</p>

Multiple oracle sources</li>
TWAP implementations</li>
Medianized price feeds</li>
</ul>
</li>
</ol>
</p>
Implementation Requirements</h3>


Asset Management:</p>

Real-time asset tracking</li>
Price feed integration</li>
Historical data maintenance</li>
</ul>
</li>

Liability Tracking:</p>

Debt obligation monitoring</li>
Collateral requirement calculation</li>
Risk factor assessment</li>
</ul>
</li>

Reporting System:</p>

Event emission for significant changes</li>
Threshold breach notifications</li>
Historical data access</li>
</ul>
</li>
</ol>
Implementation Considerations</h3>
Implementation Notes</h3>
Based on conducted tests, it is recommended:</p>


Liability Management:</p>

Maintain constant liabilities during price updates</li>
Validate that liabilities are never 0 to avoid division by zero</li>
Update liabilities only when actual positions change</li>
</ul>
</li>

Ratio Calculation:</p>
function</span> calculateRatio</span>(</span>uint256</span> assets</span>,</span> uint256</span> liabilities</span>)</span> pure</span> returns</span> (</span>uint256</span>)</span> {</span></span>
    if</span> (</span>liabilities </span>==</span> 0</span>)</span> {</span></span>
        return</span> assets </span>></span> 0</span> ?</span> RATIO_DECIMALS </span>*</span> 2</span> :</span> RATIO_DECIMALS</span>;</span></span>
    }</span></span>
    return</span> (</span>assets </span>*</span> RATIO_DECIMALS</span>)</span> /</span> liabilities</span>;</span></span>
}</span></span></code></pre></li>

State Validation:</p>

Verify values before updating</li>
Maintain accurate history</li>
Emit events for significant changes</li>
</ul>
</li>

Gas Considerations:</p>

Optimize history storage</li>
Batch updates for multiple tokens</li>
Limit array sizes in updates</li>
</ul>
</li>
</ol>
Backwards Compatibility</h2>
This EIP is compatible with existing DeFi protocols and requires no changes to existing token standards.</p>
Reference Implementation</h2>
The reference implementation provides a comprehensive example of the standard in action:</p>
Core Implementation Requirements</h3>
Implementations of the ISolvencyProof</code> interface should provide robust solvency monitoring with:</p>

Advanced state management</strong> with atomic updates and timestamp tracking</li>
Multi-layered security</strong> including access control, rate limiting, and circuit breakers</li>
Historical data management</strong> with bounded storage and configurable retention</li>
Oracle integration</strong> with consensus validation and staleness detection</li>
Emergency response systems</strong> with automatic pausing and guardian controls</li>
Comprehensive event emission</strong> for real-time monitoring and risk alerts</li>
</ul>
Recommended Implementation Patterns</h3>
State Management with Security Constants</h4>
//</span> Security constants for production deployment</span></span>
uint256</span> private</span> constant</span> RATIO_DECIMALS </span>=</span> 10000</span>;</span></span>
uint256</span> private</span> constant</span> MIN_SOLVENCY_RATIO </span>=</span> 10500</span>;</span></span>
uint256</span> private</span> constant</span> CRITICAL_RATIO </span>=</span> 10200</span>;</span></span>
uint256</span> private</span> constant</span> WARNING_RATIO </span>=</span> 11000</span>;</span></span>
</span>
//</span> Enhanced security constants</span></span>
uint256</span> private</span> constant</span> MAX_PRICE_DEVIATION </span>=</span> 500</span>;</span>    //</span> 5%</span></span>
uint256</span> private</span> constant</span> MAX_TOKENS_PER_UPDATE </span>=</span> 50</span>;</span>   //</span> DoS protection</span></span>
uint256</span> private</span> constant</span> STALENESS_THRESHOLD </span>=</span> 3600</span>;</span>   //</span> 1 hour</span></span>
uint256</span> private</span> constant</span> CIRCUIT_BREAKER_THRESHOLD </span>=</span> 2000</span>;</span> //</span> 20%</span></span>
uint256</span> private</span> constant</span> UPDATE_COOLDOWN </span>=</span> 5</span>;</span>          //</span> 5 blocks</span></span>
uint256</span> private</span> constant</span> MAX_HISTORY_ENTRIES </span>=</span> 8760</span>;</span>   //</span> ~1 year</span></span>
uint256</span> private</span> constant</span> MIN_ENTRY_INTERVAL </span>=</span> 3600</span>;</span>     //</span> 1 hour</span></span>
</span>
//</span> Role-based access control</span></span>
bytes32</span> public</span> constant</span> ORACLE_ROLE </span>=</span> keccak256</span>(</span>"ORACLE_ROLE"</span>)</span>;</span></span>
bytes32</span> public</span> constant</span> EMERGENCY_ROLE </span>=</span> keccak256</span>(</span>"EMERGENCY_ROLE"</span>)</span>;</span></span>
bytes32</span> public</span> constant</span> ADMIN_ROLE </span>=</span> keccak256</span>(</span>"ADMIN_ROLE"</span>)</span>;</span></span>
</span>
//</span> Enhanced state variables</span></span>
ProtocolAssets </span>private</span> currentAssets</span>;</span></span>
ProtocolLiabilities </span>private</span> currentLiabilities</span>;</span></span>
</span>
//</span> Multi-oracle price tracking</span></span>
mapping</span>(</span>address</span> =></span> mapping</span>(</span>address</span> =></span> uint256</span>)</span>)</span> public</span> oraclePrices</span>;</span></span>
mapping</span>(</span>address</span> =></span> uint256</span>)</span> public</span> oracleLastUpdate</span>;</span></span>
mapping</span>(</span>address</span> =></span> uint256</span>)</span> public</span> lastUpdateBlock</span>;</span></span>
</span>
//</span> Emergency controls</span></span>
bool</span> public</span> emergencyPaused</span>;</span></span>
uint256</span> public</span> pauseEndTime</span>;</span></span>
address</span> public</span> emergencyGuardian</span>;</span></span>
</span>
//</span> Historical data with metadata</span></span>
struct</span> HistoricalMetric</span> {</span></span>
    uint256</span> timestamp</span>;</span></span>
    uint256</span> solvencyRatio</span>;</span></span>
    ProtocolAssets assets</span>;</span></span>
    ProtocolLiabilities liabilities</span>;</span></span>
    address</span> updatedBy</span>;</span></span>
}</span></span>
</span>
HistoricalMetric</span>[</span>]</span> private</span> metricsHistory</span>;</span></span>
uint256</span> private</span> lastHistoricalEntry</span>;</span></span></code></pre>Advanced Security Features</h4>
Access Control System</h5>
//</span> Multi-role access control with backward compatibility</span></span>
modifier</span> onlyOracle</span>(</span>)</span> {</span></span>
    require</span>(</span></span>
        assetOracles</span>[</span>msg.sender</span>]</span> ||</span> hasRole</span>(</span>ORACLE_ROLE</span>,</span> msg.sender</span>)</span>,</span></span>
        "Not authorized oracle"</span></span>
    )</span>;</span></span>
    require</span>(</span>!</span>emergencyPaused </span>||</span> block</span>.</span>timestamp </span>></span> pauseEndTime</span>,</span></span>
        "Emergency paused"</span>)</span>;</span></span>
    _</span>;</span></span>
}</span></span>
</span>
//</span> Rate limiting to prevent spam</span></span>
modifier</span> rateLimited</span>(</span>)</span> {</span></span>
    require</span>(</span></span>
        block</span>.</span>number </span>></span>=</span> lastUpdateBlock</span>[</span>msg.sender</span>]</span> +</span> UPDATE_COOLDOWN</span>,</span></span>
        "Update too frequent"</span></span>
    )</span>;</span></span>
    lastUpdateBlock</span>[</span>msg.sender</span>]</span> =</span> block</span>.</span>number</span>;</span></span>
    emit</span> RateLimitTriggered</span>(</span>msg.sender</span>,</span> block</span>.</span>number</span>)</span>;</span></span>
    _</span>;</span></span>
}</span></span></code></pre>Circuit Breaker Implementation</h5>
function</span> _checkCircuitBreaker</span>(</span>uint256</span> previousTotal</span>,</span> uint256</span> newTotal</span>)</span> internal</span> {</span></span>
    if</span> (</span>previousTotal </span>></span> 0</span>)</span> {</span></span>
        uint256</span> assetChange </span>=</span> newTotal </span>></span> previousTotal</span></span>
            ?</span> (</span>(</span>newTotal </span>-</span> previousTotal</span>)</span> *</span> 10000</span>)</span> /</span> previousTotal</span></span>
            :</span> (</span>(</span>previousTotal </span>-</span> newTotal</span>)</span> *</span> 10000</span>)</span> /</span> previousTotal</span>;</span></span>
</span>
        if</span> (</span>assetChange </span>></span> CIRCUIT_BREAKER_THRESHOLD</span>)</span> {</span></span>
            emergencyPaused </span>=</span> true</span>;</span></span>
            pauseEndTime </span>=</span> block</span>.</span>timestamp </span>+</span> 3600</span>;</span> //</span> 1 hour pause</span></span>
            emit</span> CircuitBreakerTriggered</span>(</span>"Large asset change"</span>,</span></span>
                assetChange</span>,</span> CIRCUIT_BREAKER_THRESHOLD</span>)</span>;</span></span>
            emit</span> EmergencyPaused</span>(</span>address</span>(</span>this</span>)</span>,</span> pauseEndTime</span>)</span>;</span></span>
        }</span></span>
    }</span></span>
}</span></span></code></pre>Multi-Oracle Consensus Validation</h5>
function</span> _validatePriceConsensus</span>(</span>address</span> token</span>,</span> uint256</span> proposedPrice</span>)</span></span>
    internal</span> returns</span> (</span>bool</span>)</span> {</span></span>
    address</span>[</span>]</span> memory</span> activeOracles </span>=</span> _getActiveOracles</span>(</span>)</span>;</span></span>
    if</span> (</span>activeOracles</span>.</span>length </span><</span> 3</span>)</span> return</span> true</span>;</span></span>
</span>
    //</span> Collect and validate prices from multiple oracles</span></span>
    uint256</span>[</span>]</span> memory</span> prices </span>=</span> new</span> uint256</span>[](</span>activeOracles</span>.</span>length</span>)</span>;</span></span>
    uint256</span> validPrices </span>=</span> 0</span>;</span></span>
</span>
    for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> activeOracles</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span>
        if</span> (</span>oraclePrices</span>[</span>activeOracles</span>[</span>i</span>]</span>]</span>[</span>token</span>]</span> ></span> 0</span>)</span> {</span></span>
            prices</span>[</span>validPrices</span>]</span> =</span> oraclePrices</span>[</span>activeOracles</span>[</span>i</span>]</span>]</span>[</span>token</span>]</span>;</span></span>
            validPrices</span>+</span>+</span>;</span></span>
        }</span></span>
    }</span></span>
</span>
    if</span> (</span>validPrices </span><</span> 2</span>)</span> return</span> true</span>;</span></span>
</span>
    //</span> Calculate median and check deviation</span></span>
    uint256</span> median </span>=</span> _calculateMedian</span>(</span>prices</span>,</span> validPrices</span>)</span>;</span></span>
    uint256</span> deviation </span>=</span> proposedPrice </span>></span> median</span></span>
        ?</span> (</span>(</span>proposedPrice </span>-</span> median</span>)</span> *</span> 10000</span>)</span> /</span> median</span></span>
        :</span> (</span>(</span>median </span>-</span> proposedPrice</span>)</span> *</span> 10000</span>)</span> /</span> median</span>;</span></span>
</span>
    if</span> (</span>deviation </span>></span> MAX_PRICE_DEVIATION</span>)</span> {</span></span>
        emit</span> PriceDeviationAlert</span>(</span>token</span>,</span> deviation</span>,</span> activeOracles</span>)</span>;</span></span>
        return</span> false</span>;</span></span>
    }</span></span>
</span>
    return</span> true</span>;</span></span>
}</span></span></code></pre>Historical Data Management</h4>
function</span> getSolvencyHistory</span>(</span>uint256</span> startTime</span>,</span> uint256</span> endTime</span>)</span></span>
    external</span> view</span> returns</span> (</span>uint256</span>[</span>]</span> memory</span>,</span> uint256</span>[</span>]</span> memory</span>,</span></span>
        ProtocolAssets</span>[</span>]</span> memory</span>,</span> ProtocolLiabilities</span>[</span>]</span> memory</span>)</span> {</span></span>
</span>
    //</span> Two-pass approach for gas optimization</span></span>
    uint256</span> count </span>=</span> 0</span>;</span></span>
    for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> metricsHistory</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span>
        if</span> (</span>metricsHistory</span>[</span>i</span>]</span>.</span>timestamp </span>></span>=</span> startTime </span>&&</span></span>
            metricsHistory</span>[</span>i</span>]</span>.</span>timestamp </span><</span>=</span> endTime</span>)</span> {</span></span>
            count</span>+</span>+</span>;</span></span>
            if</span> (</span>count </span>></span>=</span> 100</span>)</span> break</span>;</span> //</span> Gas limit protection</span></span>
        }</span></span>
    }</span></span>
</span>
    //</span> Allocate exact size arrays</span></span>
    uint256</span>[</span>]</span> memory</span> timestamps </span>=</span> new</span> uint256</span>[](</span>count</span>)</span>;</span></span>
    uint256</span>[</span>]</span> memory</span> ratios </span>=</span> new</span> uint256</span>[](</span>count</span>)</span>;</span></span>
    ProtocolAssets</span>[</span>]</span> memory</span> assets </span>=</span> new</span> ProtocolAssets</span>[</span>]</span>(</span>count</span>)</span>;</span></span>
    ProtocolLiabilities</span>[</span>]</span> memory</span> liabilities </span>=</span> new</span> ProtocolLiabilities</span>[</span>]</span>(</span>count</span>)</span>;</span></span>
</span>
    //</span> Populate arrays</span></span>
    uint256</span> index </span>=</span> 0</span>;</span></span>
    for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> metricsHistory</span>.</span>length </span>&&</span> index </span><</span> count</span>;</span> i</span>+</span>+</span>)</span> {</span></span>
        if</span> (</span>metricsHistory</span>[</span>i</span>]</span>.</span>timestamp </span>></span>=</span> startTime </span>&&</span></span>
            metricsHistory</span>[</span>i</span>]</span>.</span>timestamp </span><</span>=</span> endTime</span>)</span> {</span></span>
            timestamps</span>[</span>index</span>]</span> =</span> metricsHistory</span>[</span>i</span>]</span>.</span>timestamp</span>;</span></span>
            ratios</span>[</span>index</span>]</span> =</span> metricsHistory</span>[</span>i</span>]</span>.</span>solvencyRatio</span>;</span></span>
            assets</span>[</span>index</span>]</span> =</span> metricsHistory</span>[</span>i</span>]</span>.</span>assets</span>;</span></span>
            liabilities</span>[</span>index</span>]</span> =</span> metricsHistory</span>[</span>i</span>]</span>.</span>liabilities</span>;</span></span>
            index</span>+</span>+</span>;</span></span>
        }</span></span>
    }</span></span>
</span>
    return</span> (</span>timestamps</span>,</span> ratios</span>,</span> assets</span>,</span> liabilities</span>)</span>;</span></span>
}</span></span>
</span>
function</span> getHistoricalDataInfo</span>(</span>)</span> external</span> view</span> returns</span> (</span></span>
    uint256</span> totalEntries</span>,</span> uint256</span> maxEntries</span>,</span></span>
    uint256</span> oldestTimestamp</span>,</span> uint256</span> newestTimestamp</span>,</span></span>
    uint256</span> minInterval</span>)</span> {</span></span>
</span>
    totalEntries </span>=</span> metricsHistory</span>.</span>length</span>;</span></span>
    maxEntries </span>=</span> MAX_HISTORY_ENTRIES</span>;</span></span>
    minInterval </span>=</span> MIN_ENTRY_INTERVAL</span>;</span></span>
</span>
    if</span> (</span>totalEntries </span>></span> 0</span>)</span> {</span></span>
        oldestTimestamp </span>=</span> metricsHistory</span>[</span>0</span>]</span>.</span>timestamp</span>;</span></span>
        newestTimestamp </span>=</span> metricsHistory</span>[</span>totalEntries </span>-</span> 1</span>]</span>.</span>timestamp</span>;</span></span>
    }</span></span>
</span>
    return</span> (</span>totalEntries</span>,</span> maxEntries</span>,</span> oldestTimestamp</span>,</span></span>
        newestTimestamp</span>,</span> minInterval</span>)</span>;</span></span>
}</span></span></code></pre>Emergency Response System</h4>
function</span> emergencyPause</span>(</span>)</span> external</span> onlyEmergencyGuardian</span> {</span></span>
    emergencyPaused </span>=</span> true</span>;</span></span>
    pauseEndTime </span>=</span> block</span>.</span>timestamp </span>+</span> 4</span> *</span> 3600</span>;</span> //</span> 4 hour default</span></span>
    emit</span> EmergencyPaused</span>(</span>msg.sender</span>,</span> pauseEndTime</span>)</span>;</span></span>
}</span></span>
</span>
function</span> emergencyUnpause</span>(</span>)</span> external</span> onlyEmergencyGuardian</span> {</span></span>
    emergencyPaused </span>=</span> false</span>;</span></span>
    pauseEndTime </span>=</span> 0</span>;</span></span>
    emit</span> EmergencyUnpaused</span>(</span>msg.sender</span>)</span>;</span></span>
}</span></span>
</span>
function</span> getEmergencyStatus</span>(</span>)</span> external</span> view</span> returns</span> (</span></span>
    bool</span> isPaused</span>,</span> uint256</span> endTime</span>,</span> address</span> guardian</span>)</span> {</span></span>
    return</span> (</span>emergencyPaused</span>,</span> pauseEndTime</span>,</span> emergencyGuardian</span>)</span>;</span></span>
}</span></span></code></pre>Gas Optimization Strategies</h3>
Bounded Operations</h4>

Maximum array sizes</strong> (50 tokens per update) to prevent out-of-gas</li>
Historical data pagination</strong> (max 100 entries per query)</li>
Efficient storage patterns</strong> with bounded retention periods</li>
</ul>
Storage Optimization</h4>

Circular buffer approach</strong> for historical data rotation</li>
Rate-limited historical entries</strong> (minimum 1-hour intervals)</li>
Compact data structures</strong> minimizing storage overhead</li>
</ul>
Testing and Validation Requirements</h3>
Comprehensive Test Coverage</h4>

Mathematical precision</strong> validation for ratio calculations</li>
Security feature testing</strong> (access control, rate limiting, circuit breakers)</li>
Oracle reliability testing</strong> under various market conditions</li>
Gas consumption analysis</strong> with stress testing</li>
Emergency scenario simulation</strong> with pause/unpause cycles</li>
</ul>
Production Deployment Requirements</h4>
Production implementations should ensure:</p>

Multi-oracle consensus mechanism implemented and tested</li>
Circuit breaker triggers validated with historical data</li>
Rate limiting prevents spam without blocking legitimate updates</li>
Emergency pause/unpause mechanisms tested with time delays</li>
Gas optimization prevents DoS while maintaining functionality</li>
Access controls follow principle of least privilege</li>
Historical data storage bounded and efficient</li>
Security parameters documented and transparent</li>
</ul>
Integration Patterns</h3>
Oracle Integration</h4>

Primary oracle feeds</strong> (Chainlink, API3) with fallback mechanisms</li>
TWAP integration</strong> for manipulation resistance</li>
Staleness detection</strong> with automatic fallback to secondary oracles</li>
</ul>
Liquidation System (Optional Enhancement)</h4>
struct</span> LiquidationConfig</span> {</span></span>
    uint256</span> maxLiquidationRatio</span>;</span>  //</span> Max % liquidatable</span></span>
    uint256</span> liquidationBonus</span>;</span>     //</span> Liquidator bonus</span></span>
    uint256</span> minHealthFactor</span>;</span>      //</span> Minimum health factor</span></span>
    uint256</span> maxSlippage</span>;</span>          //</span> Slippage tolerance</span></span>
    bool</span> isActive</span>;</span></span>
}</span></span>
</span>
function</span> safeLiquidation</span>(</span>address</span> protocol</span>,</span> address</span> user</span>,</span></span>
    uint256</span> debtAmount</span>,</span> uint256</span> expectedCollateral</span>,</span> uint256</span> maxSlippage</span>)</span></span>
    external</span> returns</span> (</span>uint256</span> actualCollateral</span>,</span> uint256</span> liquidationBonus</span>)</span> {</span></span>
    //</span> Comprehensive liquidation logic with health factor validation</span></span>
    //</span> Slippage protection and bonus calculation</span></span>
    //</span> Position updates and event emission</span></span>
}</span></span></code></pre>
This implementation demonstrates production-ready patterns for DeFi protocol solvency monitoring with enterprise-grade security, gas optimization, and comprehensive risk management.</p>
Security Considerations</h2>
When implementing solvency monitoring for DeFi protocols, security isn't optional—it's essential. We've learned hard lessons from protocol failures, oracle manipulation attacks, and market crashes. This section covers the practical security measures you need to implement, drawn from what actually works in production systems like Aave, Compound, and MakerDAO.</p>
Oracle Security - Implementation Requirements</h3>
Price Feed Validation</h4>

Minimum 3 independent oracle sources</strong> with median aggregation to prevent single points of failure</li>
Deviation threshold checks:</strong> Reject price updates exceeding 5% difference between sources</li>
Staleness validation:</strong> ETH/USD and major crypto pairs should use 1-hour maximum staleness (3600 seconds)</li>
Circuit breaker integration:</strong> Pause solvency updates when price movements exceed 20% in single block</li>
</ul>
Implementation patterns for price validation should include median calculation, deviation checks, and appropriate error handling.</p>
Real-world reference:</strong> Chainlink's Feed Registry and Aave's AaveOracle provide solid patterns for oracle integration.</p>
TWAP Integration</h4>

30-minute minimum windows</strong> for manipulation resistance (based on Uniswap V3 security analysis)</li>
Minimum $1-5M liquidity</strong> in reference pools for oracle reliability</li>
Combined validation:</strong> Primary Chainlink feeds with Uniswap V3 TWAP backup verification</li>
</ul>
Oracle Failure Handling</h4>
Implementations should include fallback mechanisms for oracle failures, including timestamp validation, secondary oracle integration, and graceful degradation patterns.</p>
Access Control - Specific Implementation</h3>
Role-Based Permissions</h4>
Implementations should use established access control patterns such as OpenZeppelin's AccessControl for role management, including oracle roles, emergency roles, and administrative functions.</p>
Rate Limiting Implementation</h4>

Maximum 1 update per 5 blocks</strong> per authorized oracle to prevent spam attacks</li>
Daily update limits:</strong> 288 updates per day (every 5 minutes) for high-frequency protocols</li>
Emergency cooldowns:</strong> 1-hour minimum between emergency pause activations</li>
</ul>
Rate limiting should be implemented using block-based cooldowns and per-oracle tracking.</p>
Multi-signature Requirements</h4>

3/5 multisig for parameter changes (threshold updates, oracle management)</li>
4/7 multisig for critical upgrades (we borrowed this from Compound V3)</li>
Separate emergency pause authority from main governance (Aave's Guardian model works well here)</li>
</ul>
Risk Management - Concrete Parameters</h3>
Threshold Calibration with Production Values</h4>
Risk Level</th> Solvency Ratio</th> Liquidation Bonus</th> Close Factor</th> Implementation</th></tr></thead>

CRITICAL</td> < 105%</td> 10-15%</td> 100%</td> Emergency pause all operations</td></tr>
HIGH_RISK</td> 105% - 110%</td> 7-10%</td> 75%</td> Restrict new borrowing</td></tr>
WARNING</td> 110% - 120%</td> 5-7%</td> 50%</td> Enhanced monitoring</td></tr>
HEALTHY</td> ≥ 120%</td> 5%</td> 50%</td> Normal operations</td></tr>
</tbody></table>
Alert System Implementation</h4>
Risk threshold monitoring should include graduated alerts (CRITICAL, HIGH_RISK, WARNING) with appropriate automated responses.</p>
Historical Data Protection</h4>

Immutable storage patterns</strong> to prevent historical data manipulation</li>
Checksum validation</strong> for stored historical ratios using merkle trees</li>
Maximum storage limits:</strong> 8760 hourly records (1 year) to prevent unbounded growth</li>
</ul>
Emergency Response Mechanisms</h3>
Circuit Breaker Integration</h4>
Circuit breaker mechanisms should monitor for dramatic value changes and automatically pause operations when thresholds are exceeded. Implementation should include emergency pause states, time-based recovery, and appropriate event emission.</p>

Automatic pause triggers:</strong> Oracle deviation >20%, liquidity drop >50% in 1 hour</li>
Initial pause duration:</strong> 1-4 hours with exponential backoff for repeated triggers</li>
Gradual resume:</strong> 25% → 50% → 75% → 100% capacity with 30-minute monitoring between phases</li>
</ul>
Time Delays for Critical Operations</h4>

Protocol upgrades:</strong> 7 days (604,800 seconds) following MakerDAO governance pattern</li>
Threshold parameter changes:</strong> 48 hours (172,800 seconds)</li>
Oracle authority changes:</strong> 24 hours (86,400 seconds) with immediate emergency override</li>
</ul>
Gas Optimization Security</h3>
Bounded Operations</h5>
Implementations should enforce reasonable limits on array sizes, historical data storage, and operation complexity to prevent denial-of-service attacks and ensure predictable gas consumption.</p>
DoS Attack Prevention</h5>

Maximum 50 tokens per update</strong> to prevent out-of-gas scenarios</li>
Pagination for historical queries</strong> with max 100 records per call</li>
Input validation:</strong> Reject empty arrays, validate array length consistency</li>
Reentrancy protection:</strong> Use OpenZeppelin's ReentrancyGuard for all external calls</li>
</ul>
Integration Security Patterns</h3>
Liquidation Protection Pattern</h4>

Note:</strong> This is a recommended integration pattern for protocols implementing this ERC. The core solvency monitoring contract focuses on solvency monitoring; liquidation logic should be implemented in the consuming protocol.</p>
</blockquote>
Liquidation integrations should include health factor validation, partial liquidation limits, and slippage protection mechanisms.</p>

Health factor buffers:</strong> 110% warning threshold before 105% liquidation</li>
Partial liquidation limits:</strong> Maximum 50% of debt in single transaction</li>
Slippage protection:</strong> 3% maximum slippage for automated liquidations</li>
</ul>
Validation and Testing Requirements</h3>
Stress Testing Scenarios</h4>

50% market crash simulation</strong> with proper threshold triggers</li>
Oracle manipulation attempts</strong> with 20%+ false price movements</li>
High-frequency update scenarios</strong> testing rate limiting effectiveness</li>
Network congestion testing</strong> with increased gas prices</li>
</ul>
Audit Requirements</h4>

Formal verification</strong> of solvency calculation logic</li>
Oracle integration testing</strong> across multiple price feed providers</li>
Emergency scenario testing</strong> including pause/unpause cycles</li>
Gas consumption analysis</strong> for all operations under stress conditions</li>
</ul>
Production Deployment Requirements</h4>
Production implementations should ensure:</p>

Multi-oracle consensus mechanism implemented and tested</li>
Circuit breaker triggers validated with historical data</li>
Rate limiting prevents spam without blocking legitimate updates</li>
Emergency pause/unpause mechanisms tested with time delays</li>
Gas optimization prevents DoS while maintaining functionality</li>
Access controls follow principle of least privilege</li>
Historical data storage bounded and efficient</li>
</ul>
These security considerations are based on production implementations from Aave V3, Compound V3, MakerDAO, and Synthetix protocols, incorporating lessons learned from actual security incidents and governance responses in the DeFi ecosystem. The specific parameters and thresholds have been validated through extensive testing scenarios including market crashes, oracle manipulation attempts, and high-frequency trading conditions.</p>
Production-Validated Security Parameters</h3>
All security parameters have been validated against real-world DeFi protocols:</p>
Parameter</th> Value</th> Reference</th> Validation Status</th></tr></thead>

Critical Ratio</strong></td> 102%</td> Aave V3 WBTC liquidation threshold</td> ✅ Production-tested</td></tr>
Min Solvency Ratio</strong></td> 105%</td> Compound V3 close factor trigger</td> ✅ Production-tested</td></tr>
Warning Ratio</strong></td> 110%</td> MakerDAO emergency shutdown threshold</td> ✅ Production-tested</td></tr>
Price Deviation</strong></td> 5%</td> Chainlink deviation standard</td> ✅ Industry standard</td></tr>
Staleness Threshold</strong></td> 1 hour</td> Chainlink ETH/USD heartbeat</td> ✅ Industry standard</td></tr>
Circuit Breaker</strong></td> 20%</td> NYSE/circuit breaker standard</td> ✅ Regulatory compliant</td></tr>
Rate Limiting</strong></td> 5 blocks</td> ~1 minute (12s avg block time)</td> ✅ DoS protection</td></tr>
Gas Optimization</strong></td> 50 token max</td> 30M gas block limit consideration</td> ✅ Network compliant</td></tr>
</tbody></table>
Security Documentation:</strong> Security validation reports and fork testing guides are available for detailed parameter validation and mainnet validation instructions.</p>
Test Coverage:</strong> Implementations should include comprehensive test suites covering core functionality, security features, and edge cases. Every security-critical code path should be tested.</p>
Testing Approach:</strong> Test contracts should simulate attack scenarios and consensus mechanisms. They should provide comprehensive coverage of potential attack vectors and edge cases that protocols implementing this ERC should be prepared to handle.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Cross-Chain Messaging Gateway
2024-10-14T00:00:00+00:00
Abstract</h2>
This proposal describes an interface, and the corresponding workflow, for smart contracts to send arbitrary data through cross-chain messaging protocols. The end goal of this proposal is to have all such messaging protocols accessible via this interface (natively or using "adapters") to improve their composability and interoperability. That would allow a new class of cross-chain native smart contracts to emerge while reducing vendor lock-in. This proposal is modular by design, allowing users to leverage bridge-specific features through attributes (structured metadata) while providing simple "universal" access to the simple feature of "just getting a simple message through".</p>
Motivation</h2>
Cross-chain messaging protocols (or bridges) allow communication between smart contracts deployed on different blockchains. There is a large diversity of such protocols with multiple degrees of decentralization, different architectures, implementing different interfaces, and providing different guarantees to users.</p>
Because almost every protocol implements a different workflow using a specific interface, portability between bridges is currently basically impossible. This also prevents the development of generic contracts that rely on cross chain communication.</p>
The objective of this ERC is to provide a standard interface, and a corresponding workflow, for performing cross-chain communication between contracts. Existing cross-chain communication protocols that do not natively implement this interface should be able to adopt it using adapter gateway contracts.</p>
Compared to previous ERCs in this area, this ERC offers compatibility with chains outside of the Ethereum/EVM ecosystem, and it is extensible to support the different feature sets of various protocols while offering a shared core of standard functionality.</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>
Message Field Encoding</h3>
A cross-chain message consists of a sender, recipient, payload, value (native token), and list of attributes.</p>
Sender and Recipient</h4>
The sender account (in the source chain) and recipient account (in the destination chain) MUST be input in an Interoperable Address binary format, specified in ERC-7930</a>, which MUST be serialized according to CAIP-350. The recipient field MAY be omitted or zeroed (contain an Interoperable Address with all fields set to zero) to indicate an unspecified destination, such as when a broadcast mode is employed and the final recipients are determined by the protocol itself.</p>
Payload</h4>
The payload is an opaque bytes</code> value.</p>
Attributes</h4>
An attribute is a key-value pair, where the key determines the type and encoding of the value, as well as its meaning and behavior in the gateway.</p>
The set of valid attributes is extensible. It is RECOMMENDED to standardize them and their characteristics by publishing them as ERCs. A gateway MAY support any set of standard or custom attributes.</p>
An attribute key is a 4-byte value (bytes4</code>). It is RECOMMENDED to define a key as the function selector for a function signature according to Solidity ABI (for example, minGasLimit(uint256)</code> resulting in the key 39f87ba1</code>), so as to give the key a human-readable name and a standard value encoding corresponding to the ABI-encoding of the function arguments.</p>
An attribute value is byte array (bytes</code>).</p>
The list of attributes MUST be encoded as bytes[]</code> (an array of bytes</code>) where each element is the concatenation of a key and a value. (Note that in the case of keys defined as Solidity function selectors, each element of the array can be encoded by abi.encodeWithSignature</code>.)</p>
A message with no attributes (an empty attributes list) MUST be considered a valid message.</p>
Sending Procedure</h3>
A Source Gateway</strong> is a contract that offers a protocol to send a message to a recipient on another chain. It MUST implement IERC7786GatewaySource</code>.</p>
interface</span> IERC7786GatewaySource</span> {</span></span>
    event</span> MessageSent</span>(</span></span>
        bytes32</span> indexed</span> sendId</span>,</span></span>
        bytes</span> sender</span>,    </span>// </span>Binary</span> Interoperable</span> Address</span></span>
        bytes</span> recipient</span>, </span>// </span>Binary</span> Interoperable</span> Address</span></span>
        bytes</span> payload</span>,</span></span>
        uint256</span> value</span>,</span></span>
        bytes</span>[</span>]</span> attributes</span></span>
    )</span>;</span></span>
</span>
    error</span> UnsupportedAttribute</span>(</span>bytes4</span> selector</span>)</span>;</span></span>
</span>
    function</span> supportsAttribute</span>(</span>bytes4</span> selector</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
</span>
    function</span> sendMessage</span>(</span></span>
        bytes</span> calldata</span> recipient</span>,</span> //</span> Binary Interoperable Address</span></span>
        bytes</span> calldata</span> payload</span>,</span></span>
        bytes</span>[</span>]</span> calldata</span> attributes</span></span>
    )</span> external</span> payable</span> returns</span> (</span>bytes32</span> sendId</span>)</span>;</span></span>
}</span></span></code></pre>supportsAttribute</code></h4>
Returns a boolean indicating whether an attribute (identified by its key) is supported by the gateway.</p>
A gateway MAY be upgraded with support for additional attributes. Once present support for an attribute SHOULD NOT be removed to preserve backwards compatibility with users of the gateway.</p>
sendMessage</code></h4>
Initiates the sending of a message.</p>
Further action MAY be required by the gateway to make the sending of the message effective, such as providing payment for gas. See Post-processing.</p>
MUST revert with UnsupportedAttribute</code> if an unsupported attribute is included. MAY revert if an attribute value is not valid for the key.</p>
MAY accept call value (native token) to be sent with the message. MUST revert if call value is included but it is not a feature supported by the gateway. It is unspecified how this value is represented on the destination.</p>
MAY generate and return a unique non-zero send identifier</em>, otherwise returning zero. This identifier can be used to track the lifecycle of the message in the source gateway in events and for post-processing. Note that this identifier MAY be different from the receiveId</code> that is delivered to the recipient, since that identifier may preferably consist of values like transaction id and log index that are not available in the execution environment.</em></p>
MUST emit a MessageSent</code> event, including the optional send identifier that is returned by the function.</p>
MessageSent</code></h4>
This event signals that a would-be sender has requested a message to be sent.</p>
If sendId</code> is present, post-processing MAY be required to send the message through the cross-chain channel.</p>
Post-processing</h4>
After a sender has invoked sendMessage</code>, further action MAY be required by the gateways to make the message effective. This is called post-processing</em>. For example, some payment is typically required to cover the gas of executing the message at the destination.</p>
The exact interface for any such action is out of scope of this ERC.</p>
Reception Procedure</h3>
A Destination Gateway</strong> is a contract that implements a protocol to validate messages sent on other chains. The interface of the destination gateway and how it is invoked is out of scope of this ERC.</p>
The protocol MUST ensure delivery of a sent message to its recipient</strong> using the IERC7786Recipient</code> interface (specified below), which the recipient MUST implement.</p>
Once the message can be safely delivered (see Properties), the gateway MUST invoke receiveMessage</code> with the message identifier and contents, unless the sender or the recipient explicitly requested otherwise.</p>
The receiveId</code> MUST be either empty or unique (for the calling gateway) to the message being relayed. The format of this identifier is not specified, and the gateway can use it at its own discretion. For example it can be an identifier of the MessagePosted</code> event that created the message.</p>
The gateway MUST verify that receiveMessage</code> returns the correct value, and MUST revert otherwise.</p>
interface</span> IERC7786Recipient</span> {</span></span>
    function</span> receiveMessage</span>(</span></span>
        bytes32</span> receiveId</span>,</span>     //</span> Unique identifier</span></span>
        bytes</span> calldata</span> sender</span>,</span> //</span> Binary Interoperable Address</span></span>
        bytes</span> calldata</span> payload</span>,</span></span>
    )</span> external</span> payable</span> returns</span> (</span>bytes4</span>)</span>;</span></span>
}</span></span></code></pre>receiveMessage</code></h4>
Delivery of a message sent from another chain.</p>
The recipient MUST validate that the caller of this function is a known gateway</strong>, i.e., one whose underlying cross-chain messaging protocol it trusts.</p>
MUST return IERC7786Recipient.receiveMessage.selector</code> (0x2432ef26</code>).</p>
Interaction Diagram</h4>
</p>
Properties</h3>
The protocol underlying a pair of gateways is expected to guarantee a series of properties. For a detailed definition and discussion, we refer to XChain Research’s Cross-chain Interoperability Report</em>.</p>

The protocol MUST guarantee Safety: A message is delivered at the destination if and only if it was sent at the source. The delivery process must ensure a message is only delivered once the sending transaction is finalized, and not delivered more than once. Note that there can be multiple messages with identical parameters that must be delivered separately.</li>
The protocol MUST guarantee Liveness: A sent message is eventually delivered to the destination, assuming Liveness and censorship-resistance of the source and destination chains and that any protocol costs are paid.</li>
The protocol SHOULD guarantee Timeliness: A sent message is delivered at the destination within a bounded delivery time, which should be documented.</li>
The above properties SHOULD NOT rely on trust in some centralized actor. For example, safety should be guaranteed by some trustless mechanism such as a light client proof or attestations by an open, decentralized validator set. Relaying should be decentralized or permissionless to ensure liveness; a centralized relayer can fail and thus halt the protocol.</li>
</ul>
Rationale</h2>
Attributes are designed so that gateways can expose any specific features the bridge offers without having to use a proprietary interface. This should allow contracts to change the gateway they use while continuing to express messages the same way. This portability offers many advantages:</p>

A contract that relies on a specific gateway for sending messages is vulnerable to the gateway being paused, deprecated, or simply breaking. If the communication between the contract and the gateway is standard, an admin of the contract could update the address (in storage) of the gateway to use. In particular, senders to update to the new gateway when a new version is available.</li>
Bridge layering is made easier. In particular, this interface should allow for gateways that route the message through multiple independent bridges. Delivery of the message could require one or multiple of these independent bridges depending on whether improved liveness or safety is desired.</li>
</ul>
As some cross-chain communication protocols require additional parameters beyond the destination and the payload, and because we want to send messages through those bridges without any knowledge of these additional parameters, a post-processing of the message MAY be required (after sendMessage</code> is called, and before the message is delivered). The additional parameters MAY be supported through attributes, which would remove the need for a post-processing step. If these additional parameters are not provided through attributes, an additional call to the gateway is REQUIRED for the message to be sent. If possible, the gateway SHOULD be designed so that anyone with an incentive for the message to be delivered can jump in. A malicious actor providing invalid parameters SHOULD NOT prevent the message from being successfully relayed by someone else.</p>
Some protocols gateway support doing arbitrary direct calls on the recipient. In that case, the recipient must detect that they are being called by the gateway to properly identify cross-chain messages. Getters are available on the gateway to figure out where the cross-chain message comes from (source chain and sender address). This approach has the downside that it allows anyone to trigger any call from the gateway to any contract. This is dangerous if the gateway ever holds any assets (ERC-20</a> or similar). The use of a dedicated receiveMessage</code> function on the recipient protects any assets or permissions held by the gateway against such attacks. If the ability to perform direct calls is desired, this can be implemented as a wrapper on top of any gateway that implements this ERC.</p>
Backwards Compatibility</h2>
Existing cross-chain messaging protocols implement proprietary interfaces. We recommend that protocols natively implement the standard interface defined here, and propose the development of standard adapters for those that don't.</p>
Security Considerations</h2>
Handling addresses</h3>
Interoperable Addresses (ERC‑7930) rely on CAIP‑350 serialization. Using non‑canonical encodings can lead to silent delivery failures. Gateways SHOULD reject non‑canonical encodings and MAY normalize them before emission.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Composable Security Middleware Hooks
2024-07-17T00:00:00+00:00
Abstract</h2>
This EIP proposes a standard interface, ILayer</code>, for implementing composable security layers in smart contracts. These layers act as middleware, enabling runtime validation of function calls before and after execution, independent of the protected contract's logic. This approach facilitates modular security, allowing independent providers to manage and upgrade security layers across multiple contracts.</p>
Motivation</h2>
Current smart contract security practices often rely on monolithic validation logic within the contract itself. This can lead to tightly coupled code, making it difficult to isolate and address security concerns. Better structured architecture is needed, middleware like approach is widely used in the industry, allowing to wrap calls in other calls in generic and repeatable pattern with same call signatures.</p>
The Security Layers Standard introduces a modular approach, enabling:</p>

Independent Security Providers:</strong> Specialized security providers can focus on developing and maintaining specific security checks.</li>
Composable Security:</strong> Layers can be combined to create comprehensive security profiles tailored to individual contract needs.</li>
Upgradability:</strong> Security layers can be updated without requiring changes to the protected contract.</li>
Flexibility:</strong> Layers can perform a wide range of validation checks, including access control, input sanitization, output verification, and more.</li>
</ul>
Having a generalized standard for such layers can help to build more secure and modular systems as well as enable security providers to build generic, service-oriented security oracle solutions.</p>
Specification</h2>
A contract implementing the ILayer</code> interface MUST provide two functions:</p>
//</span> SPDX-License-Identifier: CC0-1.0</span></span>
pragma</span> solidity</span> 0.8.20</span>;</span></span>
</span>
interface</span> ILayer</span> {</span></span>
    ///</span> @notice</span> Validates a function call before execution.</span></span>
    ///</span> @param</span> configuration</span> Layer-specific configuration data.</span></span>
    ///</span> @param</span> selector</span> The function selector being called.</span></span>
    ///</span> @param</span> sender</span> The address initiating the call.</span></span>
    ///</span> @param</span> value</span> The amount of ETH sent with the call (if any).</span></span>
    ///</span> @param</span> data</span> The calldata for the function call.</span></span>
    ///</span> @return</span> beforeCallResult</span> Arbitrary data to be passed to `afterCallValidation`.</span></span>
    ///</span> @dev</span> MUST revert if validation fails.</span></span>
    function</span> beforeCall</span>(</span></span>
        bytes</span> memory</span> configuration</span>,</span></span>
        bytes4</span> selector</span>,</span></span>
        address</span> sender</span>,</span></span>
        uint256</span> value</span>,</span></span>
        bytes</span> memory</span> data</span></span>
    )</span> external</span> returns</span> (</span>bytes</span> memory</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Validates a function call after execution.</span></span>
    ///</span> @param</span> configuration</span> Layer-specific configuration data.</span></span>
    ///</span> @param</span> selector</span> The function selector being called.</span></span>
    ///</span> @param</span> sender</span> The address initiating the call.</span></span>
    ///</span> @param</span> value</span> The amount of ETH sent with the call (if any).</span></span>
    ///</span> @param</span> data</span> The calldata for the function call.</span></span>
    ///</span> @param</span> beforeCallResult</span> The data returned by `beforeCallValidation`.</span></span>
    ///</span> @dev</span> MUST revert if validation fails.</span></span>
    function</span> afterCall</span>(</span></span>
        bytes</span> memory</span> configuration</span>,</span></span>
        bytes4</span> selector</span>,</span></span>
        address</span> sender</span>,</span></span>
        uint256</span> value</span>,</span></span>
        bytes</span> memory</span> data</span>,</span></span>
        bytes</span> memory</span> beforeCallResult</span></span>
    )</span> external</span>;</span></span>
}</span></span>
</span></code></pre>
A protected contract MAY integrate security layers by calling the beforeCallValidation</code> function before executing its logic and the afterCallValidation</code> function afterwards. Multiple layers can be registered and executed in a defined order. The protected contract MUST revert if any layer reverts.</p>
Rationale</h2>
Flexibility</strong>: The layerConfig</code> parameter allows for layer-specific customization, enabling a single layer implementation to serve multiple contracts with varying requirements.</p>
non-static calls</strong>: Layers can maintain their own state, allowing for more complex validation logic (e.g., rate limiting, usage tracking).</p>
Strict Validation</strong>: Reverts on validation failure ensure a fail-safe mechanism, preventing execution of potentially harmful transactions.</p>
Gas Costs</strong>: Layers naturally will have gas costs associated with their execution. However, the benefits of enhanced security and modularity outweigh these costs, especially as blockchain technology continues to evolve and we expect gas costs to decrease over time.</p>
Reference Implementation</h2>
A reference implementation of the ILayer</code> interface and a sample protected contract can be found in the repository:
In the ILayer.sol</code></a> a reference interface is provided.</p>
In this test, a Protected.sol</code></a> contract is protected by a RateLimitLayer.sol</code></a> layer. The RateLimitLayer</code> implements the ILayer</code> interface and enforces a rate which client has configured.
The Drainer</code> simulates a vulnerable contract that acts in a malicious way. In the test.ts</code> The Drainer</code> contract is trying to drain the funds from the Protected</code> contract. It is assumed that Protected</code> contract has bug that allows partial unauthorized access to the state.
The RateLimitLayer</code> is configured to allow only 10 transactions per block from same sender. The test checks that the Drainer</code> contract is not able to drain the funds from the Protected</code> contract.</p>
Security Considerations</h2>
Layer Trust</strong>: Thoroughly audit and vet any security layer before integrating it into your contract. Malicious layers can compromise contract security.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Code Index
2024-07-16T00:00:00+00:00
Abstract</h2>
This EIP defines a standard interface for indexing smart contracts on Ethereum by their bytecode hash. This enables trustless discovery and verification of contract code, facilitating use cases like bytecode signing, whitelisting, and decentralized distribution mechanisms.</p>
Motivation</h2>
Existing contract discovery relies on addresses, which are non-deterministic and can be obfuscated through proxies. Indexing by bytecode hash provides a deterministic and tamper-proof way to identify and verify contract code, enhancing security and trust in the Ethereum ecosystem.</p>
Consider a security auditor who wants to attest to the integrity of a contract's code. By referencing bytecode hashes, auditors can focus their audit on the bytecode itself, without needing to assess deployment parameters or storage contents. This method verifies the integrity of a contract's codebase without auditing the entire contract state.</p>
Additionally, bytecode referencing allows whitelist contracts before deployment, allowing developers to get pre-approval for their codebase without disclosing the code itself, or even pre-setup infrastructure that will change it behavior upon adding some determined functionality on chain.</p>
For developers relying on extensive code reuse, bytecode referencing protects against malicious changes that can occur with address-based referencing through proxies. This builds long-term trust chains extending to end-user applications.</p>
For decentralized application (dApp) developers, a code index can save gas costs by allowing them to reference existing codebases instead of redeploying them, optimizing resource usage. This can be useful for dApps that rely on extensive re-use of same codebase as own dependencies.</p>
Why this registry needs to be an ERC</h3>
The Code Index is essential for trustless and secure smart contract development. By standardizing the interface for indexing contracts by their bytecode, developers can easily integrate this feature into their smart contracts, enhancing the security and trustworthiness of the Ethereum ecosystem.</p>
Its simplicity and generic nature make it suitable for a wide range of applications. The ability to globally reference the same codebase makes it an ideal candidate for standardization.</p>
Ultimately, this feature should be incorporated into EIP standards, as it is a fundamental building block for trustless and secure smart contract development. This standard is a step towards this goal.</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>
//</span> SPDX-License-Identifier: CC0-1.0</span></span>
pragma</span> solidity</span> 0.8.28</span>;</span></span>
import</span> {</span>IERC7744</span>}</span> from</span> "./IERC7744.sol"</span>;</span></span>
</span>
/**</span></span>
 * </span>@title</span> Byte Code Indexer Contract</span></span>
 * </span>@notice</span> You can use this contract to index contracts by their bytecode.</span></span>
 * </span>@dev</span> This allows to query contracts by their bytecode instead of addresses.</span></span>
 * </span>@author</span> Tim Pechersky (@Peersky)</span></span>
 */</span></span>
contract</span> ERC7744</span> is</span> IERC7744</span> {</span></span>
    mapping</span>(</span>bytes32</span> =></span> address</span>)</span> private</span> index</span>;</span></span>
</span>
    function</span> isEIP7702</span>(</span>address</span> account</span>)</span> public</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span>
        bytes3</span> prefix</span>;</span></span>
        assembly</span> {</span></span>
            extcodecopy</span>(</span>account</span>,</span> 0</span>,</span> mload</span>(</span>0x40</span>)</span>,</span> 3</span>)</span> //</span> Copy first 3 bytes to memory</span></span>
            prefix </span>:=</span> mload</span>(</span>0x40</span>)</span> //</span> Load the 3 bytes from memory</span></span>
        }</span></span>
        return</span> prefix </span>==</span> bytes3</span>(</span>0xef0100</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> isValidContainer</span>(</span>address</span> container</span>)</span> private</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span>
        bytes</span> memory</span> code </span>=</span> container</span>.</span>code</span>;</span></span>
        bytes32</span> codeHash </span>=</span> address</span>(</span>container</span>)</span>.</span>codehash</span>;</span></span>
        return</span> (</span>code</span>.</span>length </span>></span> 0</span> &&</span> codeHash </span>!=</span> bytes32</span>(</span>0</span>)</span> &&</span> !</span>isEIP7702</span>(</span>container</span>)</span>)</span>;</span></span>
    }</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Registers a contract in the index by its bytecode hash</span></span>
     * </span>@param</span> container</span> The contract to register</span></span>
     * </span>@dev</span> `msg.codeHash` will be used</span></span>
     * </span>@dev</span> It will revert if the contract is already indexed or if returns EIP7702 delegated EOA</span></span>
     */</span></span>
    function</span> register</span>(</span>address</span> container</span>)</span> external</span> {</span></span>
        address</span> etalon </span>=</span> index</span>[</span>container</span>.</span>codehash</span>]</span>;</span></span>
        require</span>(</span>isValidContainer</span>(</span>container</span>)</span>,</span> "Invalid container"</span>)</span>;</span></span>
        if</span> (</span>etalon </span>!=</span> address</span>(</span>0</span>)</span>)</span> {</span></span>
            if</span> (</span>isValidContainer</span>(</span>etalon</span>)</span>)</span> revert</span> alreadyExists</span>(</span>container</span>.</span>codehash</span>,</span> container</span>)</span>;</span></span>
        }</span></span>
        index</span>[</span>container</span>.</span>codehash</span>]</span> =</span> container</span>;</span></span>
        emit</span> Indexed</span>(</span>container</span>,</span> container</span>.</span>codehash</span>)</span>;</span></span>
    }</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Returns the contract address by its bytecode hash</span></span>
     * </span>@dev</span> returns zero if the contract is not indexed</span></span>
     * </span>@param</span> id</span> The bytecode hash</span></span>
     * </span>@return</span> The</span> contract address</span></span>
     */</span></span>
    function</span> get</span>(</span>bytes32</span> id</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span> {</span></span>
        return</span> index</span>[</span>id</span>]</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Deployment method</h3>
The CodeIndex</code> contract is deployed at: 0xC0De1D1126b6D698a0073A4e66520111cEe22F62</code> using CREATE2</code> via the deterministic deployer at 0x4e59b44847b379578588920ca78fbf26c0b4956c</code> with a salt of 0x9425035d50edcd7504fe5eeb5df841cc74fe6cccd82dca6ee75bcdf774bd88d9</code> is obtained by seeking a vanity address starting with meaningful name "Code ID (c0de1d</code>) for a bytecode compiled with solc 0.8.28</code> as solc --input-file src/ERC7744.sol --bin --optimize --optimize-runs 2000 --metadata-hash none --via-ir --optimize-yul</code></p>
Rationale</h2>
Bytecode over Addresses</strong>: Bytecode is deterministic and can be verified on-chain, while addresses are opaque and mutable.</p>
Reverting on re-indexing</strong>: There is small, yet non-zero probability of hash collision attack. Disallowing updates to indexed location of bytecode coupes with this.</p>
Simple Interface</strong>: The interface is minimal and focused to maximize composability and ease of implementation.</p>
Library Implementation</strong>: Implementing this as a library would limit its impact, making code reuse more difficult and lacking a single, official source of truth. By establishing this as an ERC, we ensure standardization and widespread adoption, driving the ecosystem forward.</p>
Reference Implementation</h2>
Reference implementation of the Code Index can be found in the assets folder. There you can find the interface</a> and the implementation</a> of the Code Index.</p>
Security Considerations</h2>
Malicious Code</strong>: The index does NOT guarantee the safety or functionality of indexed contracts. Users MUST exercise caution and perform their own due diligence before interacting with indexed contracts.</p>
Storage contents of registered contracts</strong>: The index only refers to the bytecode of the contract, not the storage contents. This means that the contract state is not indexed and may change over time.</p>
EIP-7702</a></strong>: The index does not index the EIP-7702 delegated accounts. During attempt to register, it checks if contract code begins with reserved delegation designator 0xef0100</code> and if so, it will revert.</p>
Self-Destruct Contracts</strong>: In case of indexed contract storage becomes empty, contracts may be re-indexed, During register function call, if contract is already indexed, we run isValidContainer</code> check on the indexed address. It it fails, re-indexing is allowed with a newly specified address.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Network Upgrade Inclusion Stages
2024-06-12T00:00:00+00:00
Abstract</h2>
Define the stages that EIPs go through in the process of planning network upgrades: Proposed for Inclusion</code>, Considered for Inclusion</code>, Scheduled for Inclusion</code>, Declined for Inclusion</code> and Included</code>.</p>
Motivation</h2>
This EIP proposes definitions for the various stages EIPs go through when planning network upgrades. It also provides context and guidelines around when and how EIPs should be moved from one stage to the next.</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>
All EIP statuses apply to a single network upgrade. EIPs must be Proposed</code>, Considered</code>, Declined</code> or Scheduled</code> separately for each network upgrade. While an EIP cannot be Included</code> in two network upgrades, an EIP being Declined for Inclusion</code> in a previous upgrade does not prevent it from being Proposed</code>, Considered</code>, Declined</code> or Scheduled</code> for inclusion in any future upgrade.</p>
The statuses below are generally defined for Core EIPs, which must be activated synchronously by all nodes on a network. To help with prioritization and communications, non-Core EIPs may also be assigned these statuses. The differences in the process and implications for non-Core EIPs are noted in each status definition.</p>
Upgrade Meta EIPs</h3>
Anyone MAY</strong> draft a Meta EIP to list EIPs for a network upgrade. This Meta EIP SHOULD</strong> include four categories in its specification section: Proposed for Inclusion</code>, Declined for Inclusion</code>, Considered for Inclusion</code> and Scheduled for Inclusion</code>. Even if a category is empty, it SHOULD</strong> be included in the initial draft for clarity.</p>
When the Upgrade Meta EIP is moved to Last Call</code>, the Proposed for Inclusion</code>, Declined for Inclusion</code> and Considered for Inclusion</code> lists SHOULD</strong> be removed, leaving only Scheduled for Inclusion</code>.</p>
Before the Upgrade Meta EIP is moved to Final</code>, the Scheduled for Inclusion</code> stage MUST</strong> be renamed to Included</code> and contain only EIPs that were activated in the upgrade.</p>
Upgrade Devnets</h3>
When preparing a network upgrade, client developers typically implement EIPs first on an ephemeral test network (upgrade devnet) to verify client interoperability, before deploying to long-lived test networks. These upgrade devnets follow a naming convention of upgradeName-devnet-version</code> (e.g. pectra-devnet-0</code> for the first upgrade devnet of the Pectra network upgrade, dencun-devnet-1</code> for the second upgrade devnet of the Dencun update, etc).</p>
Since client developers' ability to include EIPs in a network upgrade is constrained by what can be implemented and tested in these upgrade devnets, the Considered for Inclusion</a> and Scheduled for Inclusion</a> sections below propose aligning these statuses with EIPs' implementation status in upgrade devnets.</p>
Proposed for Inclusion</h3>
To propose an EIP for inclusion, someone MUST</strong> open a pull request to add it to the Proposed for Inclusion</code> section of the Upgrade Meta EIP. The proposer of an EIP SHOULD</strong> serve as the primary point of contact for that EIP for the duration of the upgrade cycle or SHOULD</strong> designate another person to serve in that role. Reasonable pull requests SHOULD</strong> be merged in a timely fashion by the Upgrade Meta EIP author.</p>
At this stage, implementation teams SHOULD</strong> review the EIP. For Core EIPs, this should be in the context of including it in the next upgrade. For non-Core EIPs, this should be in the context of supporting the EIP before the network upgrade is activated.</p>
Note that EIPs must be Proposed for Inclusion</code> for each network upgrade. In other words, proposals do not "carry over" to the next upgrade if an EIP is not included in the one it was first proposed for.</p>
Considered for Inclusion</h3>
Once client developers have reviewed an EIP which was Proposed for Inclusion</code>, they MAY</strong> move it to the Considered for Inclusion</code> stage. Once a decision is made by client teams to move an EIP to Considered for Inclusion</code>, the Upgrade Meta EIP SHOULD</strong> be updated to reflect this.</p>
Considered for Inclusion</code> signals that client developers are positive towards the EIP. A Core EIP that is Considered for Inclusion</code>  SHOULD</strong> be implemented in future Upgrade Devnets. Assuming it meets all the requirements for mainnet deployment it MAY</strong> be included in the network upgrade. This stage is similar to "concept ACK" in other open source projects, and is not sufficient to result in deployment to mainnet.</p>
Non-Core EIPs that are Considered for Inclusion</code> SHOULD</strong> be supported prior to the network upgrade being activated.</p>
An EIP MAY</strong> be moved from Considered for Inclusion</code> to Declined for Inclusion</code> if client teams are against including the EIP in the network upgrade.</p>
An EIP SHOULD</strong> have a Python implementation accompanied by tests in execution-specs</a> submitted as an open PR. The EIP writer is encouraged to reach out to the maintainers of execution-specs for assistance with implementation. Client developers MAY</strong> decide to allow an EIP to be moved to Considered for Inclusion</code> without either implementation, being aware that the absence of these implementations could lead to delays in the testing cycle.</p>
Any updates to an EIP that is already at this stage SHOULD</strong> be accompanied by the appropriate updates to its implementation and tests in execution-specs</a> if deemed necessary by client developers.</p>
Declined for Inclusion</h3>
At any time during the network upgrade planning process, client developers MAY</strong> move EIPs from any other stage to the Declined for Inclusion</code> stage if client teams are against including the EIP in the network upgrade. Once a decision is made by client teams to move an EIP to Declined for Inclusion</code>, the Upgrade Meta EIP SHOULD</strong> be updated to reflect this.</p>
Declined for Inclusion</code> signals that client developers wish to exclude the EIP from the current network upgrade and stop discussing its potential inclusion or implementation status in relation to this upgrade. An EIP which was Declined for Inclusion</code> in a particular upgrade MAY</strong> still be Proposed for Inclusion</code> in a subsequent upgrade. In exceptional circumstances, client developers MAY</strong> choose to move an EIP from Declined for Inclusion</code> to Considered for Inclusion</code> or Scheduled for Inclusion</code>.</p>
Scheduled for Inclusion</h3>
When client teams agree to implement a Core EIP in the next</strong> Upgrade Devnet, the EIP SHOULD</strong> move to the Scheduled for Inclusion</code> stage, and the Upgrade Meta EIP SHOULD</strong> be updated to reflect this. Non-Core EIPs SHOULD</strong> move to Scheduled for Inclusion</code> when client teams agree to immediately prioritize their implementation.</p>
An EIP MUST</strong> have a Python implementation accompanied by tests in execution-specs</a>, submitted as an open PR or merged to the devnets/upgradeName/version</code> branch of the repository. Client developers MAY</strong> decide to allow an EIP to be moved to Scheduled for Inclusion</code> without an execution-specs</a> implementation, but the tests are strictly mandatory.</p>
Any updates to an EIP that is already at this stage MUST</strong> be accompanied by appropriate updates to its implementation and tests in execution-specs</a> if deemed necessary by client developers.</p>
Scheduled for Inclusion</code> signals that implementation and testing work are underway. The EIP SHOULD</strong> be included in the network upgrade if no issues arise. The latest Upgrade Devnet must contain all Scheduled for Inclusion</code> Core EIPs.</p>
An EIP MAY</strong> be moved from Scheduled for Inclusion</code> to Declined for Inclusion</code> if client teams are against including the EIP in the network upgrade. An EIP MAY</strong> also be moved from Scheduled for Inclusion</code> to Considered for Inclusion</code> if client teams are in favor of including the EIP in the network upgrade but cannot commit to including it in the next</strong> Upgrade Devnet.</p>
Included</h3>
After network upgrade activation, all included Core EIPs and activated non-Core EIPs MUST</strong> be moved to Included</code> in the Meta EIP. All other status lists MUST</strong> be removed from the Meta EIP.</p>
Included</code> signals that the EIPs have been activated as part of the network upgrade.</p>
Rationale</h2>
Formalizing the Proposed for Inclusion</code>, Considered for Inclusion</code>, Scheduled for Inclusion</code>, Declined for Inclusion</code> and Included</code> stages provides better legibility to both protocol maintainers and the broader Ethereum community.</p>
The specification tries to minimize steps which MUST</strong> be followed to align with Ethereum's "rough consensus" governance model.</p>
Assuming it is adopted, the process outlined in this EIP should be used for at least one full network upgrade cycle before moving to Last Call</code> and at least two full network upgrades cycles before moving to Final</code>. This way, the EIP can be updated to reflect changes made to the process over time.</p>
Backwards Compatibility</h2>
This EIP does not directly change the Ethereum protocol. It formalizes parts of the current network upgrade planning process.</p>
Security Considerations</h2>
None.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Revert creation in case of non-empty storage
2024-02-02T00:00:00+00:00
Abstract</h2>
This EIP causes contract creation to throw an error when attempted at an address with pre-existing storage.</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>
If a contract creation is attempted due to a creation transaction, the CREATE</code> opcode, the CREATE2</code> opcode, or any other reason, and the destination address already has either a nonzero nonce, a nonzero code length, or non-empty storage, then the creation MUST throw as if the first byte in the init code were an invalid opcode. This change MUST apply retroactively for all existing blocks.</p>
This EIP amends EIP-684</a> with one extra condition, requiring empty storage for contract deployment.</p>
This EIP will not affect EIP-7702</a>, since the authority's nonce is always incremented after an authorization is applied, which conflicts with the condition required for contract deployment.</p>
Rationale</h2>
EIP-684 defines two conditions for contract deployment: the destination address must have zero nonce and zero code length. Unfortunately, this is not sufficient. Before EIP-161</a> was applied, the nonce of a newly deployed contract remained set to zero. Therefore, it was entirely possible to create a contract with a zero nonce and zero code length but with non-empty storage, if slots were set in the constructor. There exists 28 such contracts on Ethereum mainnet at this time.</p>
Backwards Compatibility</h2>
This is an execution layer upgrade, and so it requires a hard fork.</p>
Test Cases</h2>
There exists quite a number of tests in the ethereum tests repo as well as in the execution spec tests, which test the scenario of deployment to targets with non-empty storage. These tests have been considered problematic in the past; Reth and EELS both intentionally implement a version of the account reset solely to pass the tests. Py-evm declared the situation impossible and never implemented account reset.</p>
Refilling the existing tests will provide sufficient coverage for this EIP.</p>
Security Considerations</h2>
This EIP is a security upgrade: it enforces the immutability of deployed code.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Empty accounts deprecation
2023-09-19T00:00:00+00:00
Abstract</h2>
This EIP prohibits the state of any post-merge network from containing empty accounts. Since no empty accounts exist outside the testsuite and no new ones can be created this requirement is already achieved in practice. An explicit ban reduces technical debt going forward.</p>
Motivation</h2>
The possibility of empty accounts is a historical artifact of the early history of Ethereum. The only networks that have ever been capable of containing them are Ethereum Mainnet, the deprecated testnet Ropsten, Etheruem Classic Mainnet and various Ethereum Classic testnets. All remaining empty accounts on Mainnet were cleared in block 14049881</code> (transaction 0xf955834bfa097458a9cf6b719705a443d32e7f43f20b9b0294098c205b4bcc3d</code>) and a similar transaction was sent on Ethereum Classic. None of the other myriad EVM-compatible networks are old enough to have empty accounts and there is no realistic prospect that anyone will encounter an empty account in a production context.</p>
Despite empty accounts no longer existing, they still impose a legacy of technical debt. EIP-161</a> imposes complicated rules that require a client to delete an empty account when it is "touched". As the Ethereum specification continues to evolve new edgecases of the "touch" rules arise which must be debated, implemented, tested and documented. If a future client wishes to only support post-merge blocks it must implement unnecessary empty account support solely to pass the test suite.</p>
By prohibiting empty accounts on post-merge networks, this EIP frees designers and implementers of Ethereum and related blockchains from the burden of having to consider them going forward.</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>
An empty account is an account with has no code</strong> and zero nonce</strong> and zero balance</strong>. This is the same as the definition in EIP-161</a>.</p>
On networks that undergo the merge transition, the pre state of the merge block may not contain any empty accounts. For networks that are merged at genesis, none of the genesis accounts may be empty accounts.</p>
Rather than performing a scan of the state, clients MAY assume the following chains have no post-merge empty accounts:</p>


The Mainnet chain whose merge block has hash 0x56a9bb0302da44b8c0b3df540781424684c3af04d0b7a38d72842b762076a664</code>.</p>
</li>

Any chain which satisfies all of the following:</p>


has no empty accounts in the genesis.</p>
</li>

had a post Spurious Dragon fork at genesis.</p>
</li>
</ul>
</li>
</ol>
The Ethereum specification is declared to be undefined in the presence of an empty account in a post-merge context. Any testcase involving post-merge empty accounts is invalid.</p>
Rationale</h2>
This EIP was drafted to be the simplest possible way of eliminating the long term technical debt imposed by empty accounts. The Merge was chosen as a natural easily identifiable cutoff point.</p>
Alternative approaches include:</p>


Using an earlier cutoff point, such as block 14049881</code>.</p>
</li>

Identifying a wider range of edge case behaviour that never happened.</p>
</li>
</ul>
These approaches were rejected as being unnecessarily complicated.</p>
Backwards Compatibility</h2>
As EIP does not change any behaviour that can occur outside the testsuite, it has no backwards compatibility consequences.</p>
Security Considerations</h2>
The validity of this EIP is dependent on the assertion that all empty accounts on Ethereum Mainnet were cleared prior to the merge. This should be subject to appropriate verification.</p>
Any networks artificially created with empty accounts will cause problems with tooling and clients.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Single-contract Multi-delegatecall
2023-01-18T00:00:00+00:00
Abstract</h2>
This EIP standardizes an interface containing a single function, multicall</code>, allowing EOAs to call multiple functions of a smart contract in a single transaction, and revert all calls if any call fails.</p>
Motivation</h2>
Currently, in order to transfer several ERC-721</a> NFTs, one needs to submit a number of transactions equal to the number of NFTs being tranferred. This wastes users' funds by requiring them to pay 21000 gas fee for every NFT they transfer.</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>
Contracts implementing this EIP must implement the following interface:</p>
pragma</span> solidity</span> ^0.8.0</span>;</span></span>
</span>
interface</span> IMulticall</span> {</span></span>
    ///</span> @notice</span>           Takes an array of abi-encoded call data, delegatecalls itself with each calldata, and returns the abi-encoded result</span></span>
    ///</span> @dev</span>              Reverts if any delegatecall reverts</span></span>
    ///</span> @param</span>    data</span>    The abi-encoded data</span></span>
    ///</span> @returns  results The abi-encoded return values</span></span>
    function</span> multicall</span>(</span>bytes</span>[</span>]</span> calldata</span> data</span>)</span> external</span> virtual</span> returns</span> (</span>bytes</span>[</span>]</span> memory</span> results</span>)</span>;</span></span>
</span>
    ///</span> @notice</span>           OPTIONAL. Takes an array of abi-encoded call data, delegatecalls itself with each calldata, and returns the abi-encoded result</span></span>
    ///</span> @dev</span>              Reverts if any delegatecall reverts</span></span>
    ///</span> @param</span>    data</span>    The abi-encoded data</span></span>
    ///</span> @param</span>    values</span>  The effective msg.values. These must add up to at most msg.value</span></span>
    ///</span> @returns  results The abi-encoded return values</span></span>
    function</span> multicallPayable</span>(</span>bytes</span>[</span>]</span> calldata</span> data</span>,</span> uint256</span>[</span>]</span> values</span>)</span> external</span> payable</span> virtual</span> returns</span> (</span>bytes</span>[</span>]</span> memory</span> results</span>)</span>;</span></span>
}</span></span></code></pre>Rationale</h2>
multicallPayable</code> is optional because it isn't always feasible to implement, due to the msg.value</code> splitting.</p>
Backwards Compatibility</h2>
This is compatible with most existing multicall functions.</p>
Test Cases</h2>
The following JavaScript code, using the Ethers library, should atomically transfer amt</code> units of an ERC-20</a> token to both addressA</code> and addressB</code>.</p>
await</span> token</span>.</span>multicall</span>(</span>await</span> Promise</span>.</span>all</span>(</span>[</span></span>
    token</span>.</span>interface</span>.</span>encodeFunctionData</span>(</span>'</span>transfer</span>'</span>,</span> [</span> addressA</span>,</span> amt</span> ]</span>)</span>,</span></span>
    token</span>.</span>interface</span>.</span>encodeFunctionData</span>(</span>'</span>transfer</span>'</span>,</span> [</span> addressB</span>,</span> amt</span> ]</span>)</span>,</span></span>
]</span>)</span>)</span>;</span></span></code></pre>Reference Implementation</h2>
pragma</span> solidity</span> ^0.8.0</span>;</span></span>
</span>
///</span> Derived from OpenZeppelin's implementation</span></span>
abstract</span> contract</span> Multicall</span> is</span> IMulticall</span> {</span></span>
    function</span> multicall</span>(</span>bytes</span>[</span>]</span> calldata</span> data</span>)</span> external</span> virtual</span> returns</span> (</span>bytes</span>[</span>]</span> memory</span> results</span>)</span> {</span></span>
        results </span>=</span> new</span> bytes</span>[](</span>data</span>.</span>length</span>)</span>;</span></span>
        for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> data</span>.</span>length</span>;</span> i</span>+</span>+</span>)</span> {</span></span>
            (</span>bool</span> success</span>,</span> bytes</span> memory</span> returndata</span>)</span> =</span> address</span>(</span>this</span>)</span>.</span>delegatecall</span>(</span>data</span>)</span>;</span></span>
            require</span>(</span>success</span>)</span>;</span></span>
            results</span>[</span>i</span>]</span> =</span> returndata</span>;</span></span>
        }</span></span>
        return</span> results</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Security Considerations</h2>
multicallPayable</code> should only be used if the contract is able to support it. A naive attempt at implementing it could allow an attacker to call a payable function multiple times with the same ether.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Contracts Dependencies Registry
2022-12-27T00:00:00+00:00
Abstract</h2>
This EIP introduces an on-chain registry system that a decentralized protocol may use to manage its smart contracts.</p>
The proposed system consists of two components: ContractsRegistry</code> and Dependant</code>. The ContractsRegistry</code> contract stores references to every smart contract used within a protocol, optionally making them upgradeable by deploying self-managed proxies on top, and acts as a hub the Dependant</code> contracts query to fetch their required dependencies from.</p>
Motivation</h2>
In the ever-growing Ethereum ecosystem, projects tend to become more and more complex. Modern protocols require portability and agility to satisfy customer needs by continuously delivering new features and staying on pace with the industry. However, the requirement is hard to achieve due to the immutable nature of blockchains and smart contracts. Moreover, the increased complexity and continuous delivery bring bugs and entangle the dependencies between the contracts, making systems less supportable.</p>
Applications that have a clear architectural facade; which are designed with forward compatibility in mind; which dependencies are transparent and clean are easier to develop and maintain. The given EIP tries to solve the aforementioned problems by presenting two smart contracts: the ContractsRegistry</code> and the Dependant</code>.</p>
The advantages of using the provided system might be:</p>

Structured smart contracts management via specialized contracts.</li>
Ad-hoc upgradeability provision of a protocol.</li>
Runtime addition, removal, and substitution of smart contracts.</li>
Dependency injection mechanism to keep smart contracts' dependencies under control.</li>
Ability to specify custom access control rules to maintain the protocol.</li>
</ul>
Specification</h2>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.</p>
Overview</h3>
The system consists of two smart contracts:</p>

ContractsRegistry</code> that is a singleton registry to manage and upgrade a protocol's smart contracts.</li>
Dependant</code> that is a mix-in which enables a dependency injection mechanism.</li>
</ul>
The following diagram depicts the relationship between the registry and its dependants:</p>
</p>
ContractsRegistry</h3>
The ContractsRegistry</code> is the main contract of the proposed system. It MUST store the references to every standalone contract used within a protocol. The ContractRegistry</code> MAY be configured to deploy a proxy contract of choice on top of the registered contracts.</p>
Additionally, the ContractsRegistry</code> MUST reject the registration of zero addresses.</p>
The ContractsRegistry</code> MUST implement the following interface:</p>
pragma</span> solidity</span> ^0.8.0</span>;</span></span>
</span>
interface</span> IContractsRegistry</span> {</span></span>
    /**</span></span>
     * </span>@notice</span> The event that is emitted when the contract gets added to the registry</span></span>
     * </span>@param</span> name</span> the name of the contract</span></span>
     * </span>@param</span> contractAddress</span> the address of the added contract</span></span>
     */</span></span>
    event</span> ContractAdded</span>(</span>string</span> name</span>, </span>address</span> contractAddress</span>)</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The event that is emitted when the proxy contract gets added to the registry</span></span>
     * </span>@param</span> name</span> the name of the contract</span></span>
     * </span>@param</span> contractAddress</span> the address of the proxy contract</span></span>
     * </span>@param</span> implementation</span> the address of the implementation contract</span></span>
     */</span></span>
    event</span> ProxyContractAdded</span>(</span>string</span> name</span>, </span>address</span> contractAddress</span>, </span>address</span> implementation</span>)</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The event that is emitted when the proxy contract gets upgraded through the registry</span></span>
     * </span>@param</span> name</span> the name of the contract</span></span>
     * </span>@param</span> newImplementation</span> the address of the new implementation contract</span></span>
     */</span></span>
    event</span> ProxyContractUpgraded</span>(</span>string</span> name</span>, </span>address</span> newImplementation</span>)</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The event that is emitted when the contract gets removed from the registry</span></span>
     * </span>@param</span> name</span> the name of the removed contract</span></span>
     */</span></span>
    event</span> ContractRemoved</span>(</span>string</span> name</span>)</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The function that returns an associated contract by the name. </span></span>
     *</span></span>
     * MUST revert if the requested contract is `address(0)`</span></span>
     *</span></span>
     * </span>@param</span> name</span> the name of the contract</span></span>
     * </span>@return</span> the</span> address of the contract</span></span>
     */</span></span>
    function</span> getContract</span>(</span>string</span> memory</span> name</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The function that checks if a contract with a given name has been added</span></span>
     * </span>@param</span> name</span> the name of the contract</span></span>
     * </span>@return</span> true</span> if the contract is present in the registry</span></span>
     */</span></span>
    function</span> hasContract</span>(</span>string</span> memory</span> name</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The function that injects dependencies into the given contract.</span></span>
     *</span></span>
     * MUST call the `setDependencies()` with `address(this)` and `bytes("")` as arguments on the provided contract</span></span>
     *</span></span>
     * </span>@param</span> name</span> the name of the contract</span></span>
     */</span></span>
    function</span> injectDependencies</span>(</span>string</span> memory</span> name</span>)</span> external</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The function that injects dependencies into the given contract with extra data.</span></span>
     *</span></span>
     * MUST call the `setDependencies()` with `address(this)` and `data` as arguments on the provided contract</span></span>
     *</span></span>
     * </span>@param</span> name</span> the name of the contract</span></span>
     * </span>@param</span> data</span> the extra context data that will be passed to the dependant contract</span></span>
     */</span></span>
    function</span> injectDependenciesWithData</span>(</span></span>
        string</span> memory</span> name</span>,</span></span>
        bytes</span> memory</span> data</span></span>
    )</span> external</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The function that upgrades added proxy contract with a new implementation.</span></span>
     *</span></span>
     * It is the Owner's responsibility to ensure the compatibility between implementations.</span></span>
     *</span></span>
     * MUST emit `ProxyContractUpgraded` event</span></span>
     *</span></span>
     * </span>@param</span> name</span> the name of the proxy contract</span></span>
     * </span>@param</span> newImplementation</span> the new implementation the proxy will be upgraded to</span></span>
     */</span></span>
    function</span> upgradeContract</span>(</span>string</span> memory</span> name</span>,</span> address</span> newImplementation</span>)</span> external</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The function that upgrades added proxy contract with a new implementation, providing data</span></span>
     *</span></span>
     * It is the Owner's responsibility to ensure the compatibility between implementations.</span></span>
     *</span></span>
     * MUST emit `ProxyContractUpgraded` event</span></span>
     *</span></span>
     * </span>@param</span> name</span> the name of the proxy contract</span></span>
     * </span>@param</span> newImplementation</span> the new implementation the proxy will be upgraded to</span></span>
     * </span>@param</span> data</span> the data that the proxy will be called with after upgrade. This can be an ABI encoded function call</span></span>
     */</span></span>
    function</span> upgradeContractAndCall</span>(</span></span>
        string</span> memory</span> name</span>,</span></span>
        address</span> newImplementation</span>,</span></span>
        bytes</span> memory</span> data</span></span>
    )</span> external</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The function that adds pure (non-proxy) contracts to the `ContractsRegistry`. The contracts MAY either be</span></span>
     * the ones the system does not have direct upgradeability control over or those that are not upgradeable by design.</span></span>
     *</span></span>
     * MUST emit `ContractAdded` event. Reverts if the provided address is `address(0)`</span></span>
     *</span></span>
     * </span>@param</span> name</span> the name to associate the contract with</span></span>
     * </span>@param</span> contractAddress</span> the address of the contract to be added</span></span>
     */</span></span>
    function</span> addContract</span>(</span>string</span> memory</span> name</span>,</span> address</span> contractAddress</span>)</span> external</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The function that adds the proxy contracts to the registry by deploying them above the provided implementation.</span></span>
     *</span></span>
     * The function may be used to add a contract that the `ContractsRegistry` has to be able to upgrade.</span></span>
     *</span></span>
     * MUST emit `ProxyContractAdded` event. Reverts if implementation address is `address(0)`</span></span>
     *</span></span>
     * </span>@param</span> name</span> the name to associate the contract with</span></span>
     * </span>@param</span> contractAddress</span> the address of the implementation to point the proxy to</span></span>
     */</span></span>
    function</span> addProxyContract</span>(</span>string</span> memory</span> name</span>,</span> address</span> contractAddress</span>)</span> external</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The function that adds the proxy contracts to the registry by deploying them above the provided implementation,</span></span>
     * providing data.</span></span>
     *</span></span>
     * The function may be used to add a contract that the `ContractsRegistry` has to be able to upgrade.</span></span>
     *</span></span>
     * MUST emit `ProxyContractAdded` event. Reverts if implementation address is `address(0)`</span></span>
     *</span></span>
     * </span>@param</span> name</span> the name to associate the contract with</span></span>
     * </span>@param</span> contractAddress</span> the address of the implementation</span></span>
     * </span>@param</span> data</span> the data that the proxy will be called with. This can be an ABI encoded initialization call</span></span>
     */</span></span>
    function</span> addProxyContractAndCall</span>(</span></span>
        string</span> memory</span> name</span>,</span></span>
        address</span> contractAddress</span>,</span></span>
        bytes</span> memory</span> data</span></span>
    )</span> external</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The function that adds an already deployed proxy to the `ContractsRegistry`. It MAY be used</span></span>
     * when the system migrates to the new `ContractRegistry`. In that case, the new registry MUST have the</span></span>
     * credentials to upgrade the newly added proxies.</span></span>
     *</span></span>
     * MUST emit `ProxyContractAdded` event. Reverts if implementation address is `address(0)`</span></span>
     *</span></span>
     * </span>@param</span> name</span> the name to associate the contract with</span></span>
     * </span>@param</span> contractAddress</span> the address of the proxy</span></span>
     */</span></span>
    function</span> justAddProxyContract</span>(</span>string</span> memory</span> name</span>,</span> address</span> contractAddress</span>)</span> external</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The function to remove contracts from the ContractsRegistry.</span></span>
     *</span></span>
     * MUST emit `ContractRemoved` event. Reverts if the contract is already removed</span></span>
     *</span></span>
     * </span>@param</span> name</span> the associated name with the contract</span></span>
     */</span></span>
    function</span> removeContract</span>(</span>string</span> memory</span> name</span>)</span> external</span>;</span></span>
}</span></span></code></pre>Dependant</h3>
The ContractsRegistry</code> works together with the Dependant</code> contract. Every standalone contract of a protocol MUST inherit Dependant</code> in order to support the dependency injection mechanism.</p>
The required dependencies MUST be set in the overridden setDependencies</code> method, not in the constructor</code> or initializer</code> methods.</p>
Only the injector MUST be able to call the setDependencies</code> and setInjector</code> methods. The initial injector will be a zero address, in that case, the call MUST NOT revert on access control checks.</p>
The Dependant</code> contract MUST implement the following interface:</p>
pragma</span> solidity</span> ^0.8.0</span>;</span></span>
</span>
interface</span> IDependant</span> {</span></span>
    /**</span></span>
     * </span>@notice</span> The function that is called from the `ContractsRegistry` to inject dependencies.</span></span>
     *</span></span>
     * The contract MUST perform a proper access check of `msg.sender`. The calls should only be possible from `ContractsRegistry`</span></span>
     *</span></span>
     * </span>@param</span> contractsRegistry</span> the registry to pull dependencies from</span></span>
     * </span>@param</span> data</span> the extra data that might provide additional application-specific context</span></span>
     */</span></span>
    function</span> setDependencies</span>(</span>address</span> contractsRegistry</span>,</span> bytes</span> memory</span> data</span>)</span> external</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The function that sets the new dependency injector.</span></span>
     *</span></span>
     * The contract MUST perform a proper access check of `msg.sender`</span></span>
     *</span></span>
     * </span>@param</span> injector</span> the new dependency injector</span></span>
     */</span></span>
    function</span> setInjector</span>(</span>address</span> injector</span>)</span> external</span>;</span></span>
 </span></span>
    /**</span></span>
     * </span>@notice</span> The function that gets the current dependency injector</span></span>
     * </span>@return</span> the</span> current dependency injector</span></span>
     */</span></span>
    function</span> getInjector</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
}</span></span></code></pre>

The Dependant</code> contract MAY store the dependency injector (usually ContractsRegistry</code>) address in the special slot 0x3d1f25f1ac447e55e7fec744471c4dab1c6a2b6ffb897825f9ea3d2e8c9be583</code> (obtained as bytes32(uint256(keccak256("eip6224.dependant.slot")) - 1)</code>).</li>
</ul>
Rationale</h2>
There are a few design decisions that have to be explicitly specified:</p>
ContractsRegistry Rationale</h3>
Contracts Identifier</h4>
The string</code> contracts identifier is chosen over the uint256</code> and bytes32</code> to maintain code readability and reduce the human error chances when interacting with the ContractsRegistry</code>. Being the topmost smart contract of a protocol, it MAY be typical for the users to interact with it via block explorers or DAOs. Clarity was prioritized over gas usage.</p>
Due to the string</code> identifier, the event parameters are not indexed. The string indexed</code> parameter will become the keccak256</code> hash of the contract name if it is larger than 32 bytes. This fact reduces readability, which was prioritized.</p>
Reverts</h4>
The getContract</code> view function reverts if the requested contract is address(0)</code>. This is essential to minimize the risks of misinitialization of a protocol. Correct contracts SHOULD be added to the registry prior to any dependency injection actions.</p>
The addContract</code>, addProxyContract</code>, addProxyContractAndCall</code>, and justAddProxyContract</code> methods revert if the provided address is address(0)</code> for the same risk minimization reason.</p>
Dependant Rationale</h3>
Dependencies</h4>
The data</code> parameter is provided to carry additional application-specific context. It MAY be used to extend the method's behavior.</p>
Injector</h4>
The setInjector</code> function is made external</code> to support the dependency injection mechanism for factory-made contracts. However, the method SHOULD be used with extra care.</p>
Reference Implementation</h2>

Note that the reference implementation depends on OpenZeppelin contracts 4.9.2</code>.</p>
</blockquote>
ContractsRegistry Implementation</h3>
pragma</span> solidity</span> ^0.8.0</span>;</span></span>
</span>
import</span> {</span>Address</span>}</span> from</span> "@openzeppelin/contracts/utils/Address.sol"</span>;</span></span>
import</span> {</span>TransparentUpgradeableProxy</span>}</span> from</span> "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol"</span>;</span></span>
import</span> {</span>OwnableUpgradeable</span>}</span> from</span> "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol"</span>;</span></span>
</span>
import</span> {</span>Dependant</span>}</span> from</span> "./Dependant.sol"</span>;</span></span>
</span>
interface</span> IContractsRegistry</span> {</span></span>
    event</span> ContractAdded</span>(</span>string</span> name</span>, </span>address</span> contractAddress</span>)</span>;</span></span>
    event</span> ProxyContractAdded</span>(</span></span>
        string</span> name</span>,</span></span>
        address</span> contractAddress</span>,</span></span>
        address</span> implementation</span></span>
    )</span>;</span></span>
    event</span> ProxyContractUpgraded</span>(</span>string</span> name</span>, </span>address</span> newImplementation</span>)</span>;</span></span>
    event</span> ContractRemoved</span>(</span>string</span> name</span>)</span>;</span></span>
</span>
    function</span> getContract</span>(</span>string</span> memory</span> name</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
</span>
    function</span> hasContract</span>(</span>string</span> memory</span> name</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
</span>
    function</span> injectDependencies</span>(</span>string</span> memory</span> name</span>)</span> external</span>;</span></span>
</span>
    function</span> injectDependenciesWithData</span>(</span>string</span> memory</span> name</span>,</span> bytes</span> memory</span> data</span>)</span></span>
        external</span>;</span></span>
</span>
    function</span> upgradeContract</span>(</span>string</span> memory</span> name</span>,</span> address</span> newImplementation</span>)</span></span>
        external</span>;</span></span>
</span>
    function</span> upgradeContractAndCall</span>(</span></span>
        string</span> memory</span> name</span>,</span></span>
        address</span> newImplementation</span>,</span></span>
        bytes</span> memory</span> data</span></span>
    )</span> external</span>;</span></span>
</span>
    function</span> addContract</span>(</span>string</span> memory</span> name</span>,</span> address</span> contractAddress</span>)</span> external</span>;</span></span>
</span>
    function</span> addProxyContract</span>(</span>string</span> memory</span> name</span>,</span> address</span> contractAddress</span>)</span></span>
        external</span>;</span></span>
</span>
    function</span> addProxyContractAndCall</span>(</span></span>
        string</span> memory</span> name</span>,</span></span>
        address</span> contractAddress</span>,</span></span>
        bytes</span> memory</span> data</span></span>
    )</span> external</span>;</span></span>
</span>
    function</span> justAddProxyContract</span>(</span>string</span> memory</span> name</span>,</span> address</span> contractAddress</span>)</span></span>
        external</span>;</span></span>
</span>
    function</span> removeContract</span>(</span>string</span> memory</span> name</span>)</span> external</span>;</span></span>
}</span></span>
</span>
contract</span> ProxyUpgrader</span> {</span></span>
    using</span> Address</span> for</span> address</span>;</span></span>
</span>
    address</span> private</span> immutable</span> _OWNER</span>;</span></span>
</span>
    modifier</span> onlyOwner</span>(</span>)</span> {</span></span>
        _onlyOwner</span>(</span>)</span>;</span></span>
        _</span>;</span></span>
    }</span></span>
</span>
    constructor</span>(</span>)</span> {</span></span>
        _OWNER </span>=</span> msg.sender</span>;</span></span>
    }</span></span>
</span>
    function</span> upgrade</span>(</span>address</span> what_</span>,</span> address</span> to_</span>,</span> bytes</span> calldata</span> data_</span>)</span> external</span> onlyOwner</span> {</span></span>
        if</span> (</span>data_</span>.</span>length </span>></span> 0</span>)</span> {</span></span>
            TransparentUpgradeableProxy</span>(</span>payable</span>(</span>what_</span>)</span>)</span>.</span>upgradeToAndCall</span>(</span>to_</span>,</span> data_</span>)</span>;</span></span>
        }</span> else</span> {</span></span>
            TransparentUpgradeableProxy</span>(</span>payable</span>(</span>what_</span>)</span>)</span>.</span>upgradeTo</span>(</span>to_</span>)</span>;</span></span>
        }</span></span>
    }</span></span>
</span>
    function</span> getImplementation</span>(</span>address</span> what_</span>)</span> external</span> view</span> onlyOwner</span> returns</span> (</span>address</span>)</span> {</span></span>
        //</span> bytes4(keccak256("implementation()")) == 0x5c60da1b</span></span>
        (</span>bool</span> success_</span>,</span> bytes</span> memory</span> returndata_</span>)</span> =</span> address</span>(</span>what_</span>)</span>.</span>staticcall</span>(</span>hex</span>"5c60da1b"</span>)</span>;</span></span>
</span>
        require</span>(</span>success_</span>,</span> "ProxyUpgrader: not a proxy"</span>)</span>;</span></span>
</span>
        return</span> abi</span>.</span>decode</span>(</span>returndata_</span>,</span> (</span>address</span>)</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> _onlyOwner</span>(</span>)</span> internal</span> view</span> {</span></span>
        require</span>(</span>_OWNER </span>==</span> msg.sender</span>,</span> "ProxyUpgrader: not an owner"</span>)</span>;</span></span>
    }</span></span>
}</span></span>
</span>
contract</span> ContractsRegistry</span> is</span> IContractsRegistry</span>, </span>OwnableUpgradeable</span> {</span></span>
    ProxyUpgrader </span>private</span> _proxyUpgrader</span>;</span></span>
</span>
    mapping</span>(</span>string</span> =></span> address</span>)</span> private</span> _contracts</span>;</span></span>
    mapping</span>(</span>address</span> =></span> bool</span>)</span> private</span> _isProxy</span>;</span></span>
</span>
    function</span> __ContractsRegistry_init</span>(</span>)</span> public</span> initializer</span> {</span></span>
        _proxyUpgrader </span>=</span> new</span> ProxyUpgrader</span>(</span>)</span>;</span></span>
</span>
        __Ownable_init</span>(</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> getContract</span>(</span>string</span> memory</span> name_</span>)</span> public</span> view</span> returns</span> (</span>address</span>)</span> {</span></span>
        address</span> contractAddress_ </span>=</span> _contracts</span>[</span>name_</span>]</span>;</span></span>
</span>
        require</span>(</span></span>
            contractAddress_ </span>!=</span> address</span>(</span>0</span>)</span>,</span></span>
            "ContractsRegistry: this mapping doesn't exist"</span></span>
        )</span>;</span></span>
</span>
        return</span> contractAddress_</span>;</span></span>
    }</span></span>
</span>
    function</span> hasContract</span>(</span>string</span> memory</span> name_</span>)</span> public</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span>
        return</span> _contracts</span>[</span>name_</span>]</span> !=</span> address</span>(</span>0</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> getProxyUpgrader</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span> {</span></span>
        return</span> address</span>(</span>_proxyUpgrader</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> injectDependencies</span>(</span>string</span> memory</span> name_</span>)</span> public</span> virtual</span> onlyOwner</span> {</span></span>
        injectDependenciesWithData</span>(</span>name_</span>,</span> bytes</span>(</span>""</span>)</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> injectDependenciesWithData</span>(</span>string</span> memory</span> name_</span>,</span> bytes</span> memory</span> data_</span>)</span></span>
        public</span></span>
        virtual</span></span>
        onlyOwner</span></span>
    {</span></span>
        address</span> contractAddress_ </span>=</span> _contracts</span>[</span>name_</span>]</span>;</span></span>
</span>
        require</span>(</span></span>
            contractAddress_ </span>!=</span> address</span>(</span>0</span>)</span>,</span></span>
            "ContractsRegistry: this mapping doesn't exist"</span></span>
        )</span>;</span></span>
</span>
        Dependant dependant_ </span>=</span> Dependant</span>(</span>contractAddress_</span>)</span>;</span></span>
        dependant_</span>.</span>setDependencies</span>(</span>address</span>(</span>this</span>)</span>,</span> data_</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> upgradeContract</span>(</span>string</span> memory</span> name_</span>,</span> address</span> newImplementation_</span>)</span></span>
        public</span></span>
        virtual</span></span>
        onlyOwner</span></span>
    {</span></span>
        upgradeContractAndCall</span>(</span>name_</span>,</span> newImplementation_</span>,</span> bytes</span>(</span>""</span>)</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> upgradeContractAndCall</span>(</span></span>
        string</span> memory</span> name_</span>,</span></span>
        address</span> newImplementation_</span>,</span></span>
        bytes</span> memory</span> data_</span></span>
    )</span> public</span> virtual</span> onlyOwner</span> {</span></span>
        address</span> contractToUpgrade_ </span>=</span> _contracts</span>[</span>name_</span>]</span>;</span></span>
</span>
        require</span>(</span></span>
            contractToUpgrade_ </span>!=</span> address</span>(</span>0</span>)</span>,</span></span>
            "ContractsRegistry: this mapping doesn't exist"</span></span>
        )</span>;</span></span>
        require</span>(</span></span>
            _isProxy</span>[</span>contractToUpgrade_</span>]</span>,</span></span>
            "ContractsRegistry: not a proxy contract"</span></span>
        )</span>;</span></span>
</span>
        _proxyUpgrader</span>.</span>upgrade</span>(</span>contractToUpgrade_</span>,</span> newImplementation_</span>,</span> data_</span>)</span>;</span></span>
</span>
        emit</span> ProxyContractUpgraded</span>(</span>name_</span>,</span> newImplementation_</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> addContract</span>(</span>string</span> memory</span> name_</span>,</span> address</span> contractAddress_</span>)</span></span>
        public</span></span>
        virtual</span></span>
        onlyOwner</span></span>
    {</span></span>
        require</span>(</span></span>
            contractAddress_ </span>!=</span> address</span>(</span>0</span>)</span>,</span></span>
            "ContractsRegistry: zero address is forbidden"</span></span>
        )</span>;</span></span>
</span>
        _contracts</span>[</span>name_</span>]</span> =</span> contractAddress_</span>;</span></span>
</span>
        emit</span> ContractAdded</span>(</span>name_</span>,</span> contractAddress_</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> addProxyContract</span>(</span>string</span> memory</span> name_</span>,</span> address</span> contractAddress_</span>)</span></span>
        public</span></span>
        virtual</span></span>
        onlyOwner</span></span>
    {</span></span>
        addProxyContractAndCall</span>(</span>name_</span>,</span> contractAddress_</span>,</span> bytes</span>(</span>""</span>)</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> addProxyContractAndCall</span>(</span></span>
        string</span> memory</span> name_</span>,</span></span>
        address</span> contractAddress_</span>,</span></span>
        bytes</span> memory</span> data_</span></span>
    )</span> public</span> virtual</span> onlyOwner</span> {</span></span>
        require</span>(</span></span>
            contractAddress_ </span>!=</span> address</span>(</span>0</span>)</span>,</span></span>
            "ContractsRegistry: zero address is forbidden"</span></span>
        )</span>;</span></span>
</span>
        address</span> proxyAddr_ </span>=</span> _deployProxy</span>(</span></span>
            contractAddress_</span>,</span></span>
            address</span>(</span>_proxyUpgrader</span>)</span>,</span></span>
            data_</span></span>
        )</span>;</span></span>
</span>
        _contracts</span>[</span>name_</span>]</span> =</span> proxyAddr_</span>;</span></span>
        _isProxy</span>[</span>proxyAddr_</span>]</span> =</span> true</span>;</span></span>
</span>
        emit</span> ProxyContractAdded</span>(</span>name_</span>,</span> proxyAddr_</span>,</span> contractAddress_</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> justAddProxyContract</span>(</span>string</span> memory</span> name_</span>,</span> address</span> contractAddress_</span>)</span></span>
        public</span></span>
        virtual</span></span>
        onlyOwner</span></span>
    {</span></span>
        require</span>(</span></span>
            contractAddress_ </span>!=</span> address</span>(</span>0</span>)</span>,</span></span>
            "ContractsRegistry: zero address is forbidden"</span></span>
        )</span>;</span></span>
</span>
        _contracts</span>[</span>name_</span>]</span> =</span> contractAddress_</span>;</span></span>
        _isProxy</span>[</span>contractAddress_</span>]</span> =</span> true</span>;</span></span>
</span>
        emit</span> ProxyContractAdded</span>(</span></span>
            name_</span>,</span></span>
            contractAddress_</span>,</span></span>
            _proxyUpgrader</span>.</span>getImplementation</span>(</span>contractAddress_</span>)</span></span>
        )</span>;</span></span>
    }</span></span>
</span>
    function</span> removeContract</span>(</span>string</span> memory</span> name_</span>)</span> public</span> virtual</span> onlyOwner</span> {</span></span>
        address</span> contractAddress_ </span>=</span> _contracts</span>[</span>name_</span>]</span>;</span></span>
</span>
        require</span>(</span></span>
            contractAddress_ </span>!=</span> address</span>(</span>0</span>)</span>,</span></span>
            "ContractsRegistry: this mapping doesn't exist"</span></span>
        )</span>;</span></span>
</span>
        delete</span> _isProxy</span>[</span>contractAddress_</span>]</span>;</span></span>
        delete</span> _contracts</span>[</span>name_</span>]</span>;</span></span>
</span>
        emit</span> ContractRemoved</span>(</span>name_</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> _deployProxy</span>(</span></span>
        address</span> contractAddress_</span>,</span></span>
        address</span> admin_</span>,</span></span>
        bytes</span> memory</span> data_</span></span>
    )</span> internal</span> virtual</span> returns</span> (</span>address</span>)</span> {</span></span>
        return</span></span>
            address</span>(</span></span>
                new</span> TransparentUpgradeableProxy</span>(</span>contractAddress_</span>,</span> admin_</span>,</span> data_</span>)</span></span>
            )</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Dependant Implementation</h3>
pragma</span> solidity</span> ^0.8.0</span>;</span></span>
</span>
interface</span> IDependant</span> {</span></span>
    function</span> setDependencies</span>(</span>address</span> contractsRegistry</span>,</span> bytes</span> memory</span> data</span>)</span> external</span>;</span></span>
 </span></span>
    function</span> setInjector</span>(</span>address</span> injector</span>)</span> external</span>;</span></span>
 </span></span>
    function</span> getInjector</span>(</span>)</span> external</span> view</span> returns</span> (</span>address</span>)</span>;</span></span>
}</span></span>
</span>
abstract</span> contract</span> Dependant</span> is</span> IDependant</span> {</span></span>
    /**</span></span>
     * </span>@dev</span> bytes32(uint256(keccak256("eip6224.dependant.slot")) - 1)</span></span>
     */</span></span>
    bytes32</span> private</span> constant</span> _INJECTOR_SLOT </span>=</span></span>
        0x3d1f25f1ac447e55e7fec744471c4dab1c6a2b6ffb897825f9ea3d2e8c9be583</span>;</span></span>
</span>
    modifier</span> dependant</span>(</span>)</span> {</span></span>
        _checkInjector</span>(</span>)</span>;</span></span>
        _</span>;</span></span>
        _setInjector</span>(</span>msg.sender</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> setDependencies</span>(</span>address</span> contractsRegistry_</span>,</span> bytes</span> memory</span> data_</span>)</span> public</span> virtual</span>;</span></span>
</span>
    function</span> setInjector</span>(</span>address</span> injector_</span>)</span> external</span> {</span></span>
        _checkInjector</span>(</span>)</span>;</span></span>
        _setInjector</span>(</span>injector_</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> getInjector</span>(</span>)</span> public</span> view</span> returns</span> (</span>address</span> injector_</span>)</span> {</span></span>
        bytes32</span> slot_ </span>=</span> _INJECTOR_SLOT</span>;</span></span>
</span>
        assembly</span> {</span></span>
            injector_ </span>:=</span> sload</span>(</span>slot_</span>)</span></span>
        }</span></span>
    }</span></span>
</span>
    function</span> _setInjector</span>(</span>address</span> injector_</span>)</span> internal</span> {</span></span>
        bytes32</span> slot_ </span>=</span> _INJECTOR_SLOT</span>;</span></span>
</span>
        assembly</span> {</span></span>
            sstore</span>(</span>slot_</span>,</span> injector_</span>)</span></span>
        }</span></span>
    }</span></span>
</span>
    function</span> _checkInjector</span>(</span>)</span> internal</span> view</span> {</span></span>
        address</span> injector_ </span>=</span> getInjector</span>(</span>)</span>;</span></span>
</span>
        require</span>(</span>injector_ </span>==</span> address</span>(</span>0</span>)</span> ||</span> injector_ </span>==</span> msg.sender</span>,</span> "Dependant: not an injector"</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Security Considerations</h2>
It is crucial for the owner of ContractsRegistry</code> to keep their keys in a safe place. The loss/leakage of credentials to the ContractsRegistry</code> will lead to the application's point of no return. The ContractRegistry</code> is a cornerstone of a protocol, access must be granted to the trusted parties only.</p>
ContractsRegistry Security</h3>

The ContractsRegistry</code> does not perform any upgradeability checks between the proxy upgrades. It is the user's responsibility to make sure that the new implementation is compatible with the old one.</li>
</ul>
Dependant Security</h3>

The Dependant</code> contract MUST set its dependency injector no later than the first call to the setDependencies</code> function is made. That being said, it is possible to front-run the first dependency injection.</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Endorsement - Permit for Any Functions
2022-08-12T00:00:00+00:00
Abstract</h2>
This EIP establish a general protocol for permitting approving function calls in the same transaction rely on ERC-5750</a>.
Unlike a few prior art (ERC-2612</a> for ERC-20</a>, ERC-4494</code> for ERC-721</a> that
usually only permit for a single behavior (transfer</code> for ERC-20 and safeTransferFrom</code> for ERC-721) and a single approver in two transactions (first a permit(...)</code> TX, then a transfer</code>-like TX), this EIP provides a way to permit arbitrary behaviors and aggregating multiple approvals from arbitrary number of approvers in the same transaction, allowing for Multi-Sig or Threshold Signing behavior.</p>
Motivation</h2>

Support permit(approval) alongside a function call.</li>
Support a second approval from another user.</li>
Support pay-for-by another user</li>
Support multi-sig</li>
Support persons acting in concert by endorsements</li>
Support accumulated voting</li>
Support off-line signatures</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.</p>
Interfaces</h3>
The interfaces and structure referenced here are as followed</p>
pragma</span> solidity</span> ^0.8.9</span>;</span></span>
</span>
struct</span> ValidityBound</span> {</span></span>
    bytes32</span> functionParamStructHash</span>;</span></span>
    uint256</span> validSince</span>;</span></span>
    uint256</span> validBy</span>;</span></span>
    uint256</span> nonce</span>;</span></span>
}</span></span>
</span>
struct</span> SingleEndorsementData</span> {</span></span>
    address</span> endorserAddress</span>;</span> //</span> 32</span></span>
    bytes</span> sig</span>;</span> //</span> dynamic = 65</span></span>
}</span></span>
</span>
struct</span> GeneralExtensionDataStruct</span> {</span></span>
    bytes32</span> erc5453MagicWord</span>;</span></span>
    uint256</span> erc5453Type</span>;</span></span>
    uint256</span> nonce</span>;</span></span>
    uint256</span> validSince</span>;</span></span>
    uint256</span> validBy</span>;</span></span>
    bytes</span> endorsementPayload</span>;</span></span>
}</span></span>
</span>
interface</span> IERC5453EndorsementCore</span> {</span></span>
    function</span> eip5453Nonce</span>(</span>address</span> endorser</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
    function</span> isEligibleEndorser</span>(</span>address</span> endorser</span>)</span> external</span> view</span> returns</span> (</span>bool</span>)</span>;</span></span>
}</span></span>
</span>
interface</span> IERC5453EndorsementDigest</span> {</span></span>
    function</span> computeValidityDigest</span>(</span></span>
        bytes32</span> _functionParamStructHash</span>,</span></span>
        uint256</span> _validSince</span>,</span></span>
        uint256</span> _validBy</span>,</span></span>
        uint256</span> _nonce</span></span>
    )</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span>
</span>
    function</span> computeFunctionParamHash</span>(</span></span>
        string</span> memory</span> _functionName</span>,</span></span>
        bytes</span> memory</span> _functionParamPacked</span></span>
    )</span> external</span> view</span> returns</span> (</span>bytes32</span>)</span>;</span></span>
}</span></span>
</span>
interface</span> IERC5453EndorsementDataTypeA</span> {</span></span>
    function</span> computeExtensionDataTypeA</span>(</span></span>
        uint256</span> nonce</span>,</span></span>
        uint256</span> validSince</span>,</span></span>
        uint256</span> validBy</span>,</span></span>
        address</span> endorserAddress</span>,</span></span>
        bytes</span> calldata</span> sig</span></span>
    )</span> external</span> view</span> returns</span> (</span>bytes</span> memory</span>)</span>;</span></span>
}</span></span>
</span>
</span>
interface</span> IERC5453EndorsementDataTypeB</span> {</span></span>
    function</span> computeExtensionDataTypeB</span>(</span></span>
        uint256</span> nonce</span>,</span></span>
        uint256</span> validSince</span>,</span></span>
        uint256</span> validBy</span>,</span></span>
        address</span>[</span>]</span> calldata</span> endorserAddress</span>,</span></span>
        bytes</span>[</span>]</span> calldata</span> sigs</span></span>
    )</span> external</span> view</span> returns</span> (</span>bytes</span> memory</span>)</span>;</span></span>
}</span></span></code></pre>
See IERC5453.sol</code></a>.</p>
Behavior specification</h3>
As specified in ERC-5750 General Extensibility for Method Behaviors</a>, any compliant method that has an bytes extraData</code> as its
last method designated for extending behaviors can conform to ERC-5453</a> as the way to indicate a permit from certain user.</p>

Any compliant method of this EIP MUST be a ERC-5750</a> compliant method.</li>
Caller MUST pass in the last parameter bytes extraData</code> conforming a solidity memory encoded layout bytes of GeneralExtensionDataStruct</code> specified in Section Interfaces</em>. The following descriptions are based on when decoding bytes extraData</code> into a GeneralExtensionDataStruct</code></li>
In the GeneralExtensionDataStruct</code>-decoded extraData</code>, caller MUST set the value of GeneralExtensionDataStruct.erc5453MagicWord</code> to be the keccak256("ERC5453-ENDORSEMENT")</code>.</li>
Caller MUST set the value of GeneralExtensionDataStruct.erc5453Type</code> to be one of the supported values.</li>
</ol>
uint256</span> constant</span> ERC5453_TYPE_A </span>=</span> 1</span>;</span></span>
uint256</span> constant</span> ERC5453_TYPE_B </span>=</span> 2</span>;</span></span></code></pre>


When the value of GeneralExtensionDataStruct.erc5453Type</code> is set to be ERC5453_TYPE_A</code>, GeneralExtensionDataStruct.endorsementPayload</code> MUST be abi encoded bytes of a SingleEndorsementData</code>.</p>
</li>

When the value of GeneralExtensionDataStruct.erc5453Type</code> is set to be ERC5453_TYPE_B</code>, GeneralExtensionDataStruct.endorsementPayload</code> MUST be abi encoded bytes of SingleEndorsementData[]</code> (a dynamic array).</p>
</li>

Each SingleEndorsementData</code> MUST have a address endorserAddress;</code> and a 65-bytes bytes sig</code> signature.</p>
</li>

Each bytes sig</code> MUST be an ECDSA (secp256k1) signature using private key of signer whose corresponding address is endorserAddress</code> signing validityDigest</code> which is the a hashTypeDataV4 of EIP-712</a> of hashStruct of ValidityBound</code> data structure as followed:</p>
</li>
</ol>
bytes32</span> validityDigest </span>=</span></span>
    eip712HashTypedDataV4</span>(</span></span>
        keccak256</span>(</span></span>
            abi</span>.</span>encode</span>(</span></span>
                keccak256</span>(</span></span>
                    "ValidityBound(bytes32 functionParamStructHash,uint256 validSince,uint256 validBy,uint256 nonce)"</span></span>
                )</span>,</span></span>
                functionParamStructHash</span>,</span></span>
                _validSince</span>,</span></span>
                _validBy</span>,</span></span>
                _nonce</span></span>
            )</span></span>
        )</span></span>
    )</span>;</span></span></code></pre>

The functionParamStructHash</code> MUST be computed as followed</li>
</ol>
        bytes32</span> functionParamStructHash </span>=</span> keccak256</span>(</span></span>
            abi</span>.</span>encodePacked</span>(</span></span>
                keccak256</span>(</span>bytes</span>(</span>_functionStructure</span>)</span>)</span>,</span></span>
                _functionParamPacked</span></span>
            )</span></span>
        )</span>;</span></span>
        return</span> functionParamStructHash</span>;</span></span></code></pre>
whereas</p>

_functionStructure</code> MUST be computed as function methodName(type1 param1, type2 param2, ...)</code>.</li>
_functionParamPacked</code> MUST be computed as enc(param1) || enco(param2) ...</code></li>
</ul>


Upon validating that endorserAddress == ecrecover(validityDigest, signature)</code> or EIP1271(endorserAddress).isValidSignature(validityDigest, signature) == ERC1271.MAGICVALUE</code>, the single endorsement MUST be deemed valid.</p>
</li>

Compliant method MAY choose to impose a threshold for a number of endorsements needs to be valid in the same ERC5453_TYPE_B</code> kind of endorsementPayload</code>.</p>
</li>

The validSince</code> and validBy</code> are both inclusive. Implementer MAY choose to use blocknumber or timestamp. Implementor SHOULD find away to indicate whether validSince</code> and validBy</code> is blocknumber or timestamp.</p>
</li>
</ol>
Rationale</h2>


We chose to have both ERC5453_TYPE_A</code>(single-endorsement) and ERC5453_TYPE_B</code>(multiple-endorsements, same nonce for entire contract) so we
could balance a wider range of use cases. E.g. the same use cases of ERC-2612 and ERC-4494</code> can be supported by ERC5453_TYPE_A</code>. And threshold approvals can be done via ERC5453_TYPE_B</code>. More complicated approval types can also be extended by defining new ERC5453_TYPE_?</code></p>
</li>

We chose to include both validSince</code> and validBy</code> to allow maximum flexibility in expiration. This can be also be supported by EVM natively at if adopted ERC-5081</code> but ERC-5081</code> will not be adopted anytime soon, we choose to add these two numbers in our protocol to allow
smart contract level support.</p>
</li>
</ol>
Backwards Compatibility</h2>
The design assumes a bytes calldata extraData</code> to maximize the flexibility of future extensions. This assumption is compatible with ERC-721</a>, ERC-1155</a> and many other ERC-track EIPs. Those that aren't, such as ERC-20</a>, can also be updated to support it, such as using a wrapper contract or proxy upgrade.</p>
Reference Implementation</h2>
In addition to the specified algorithm for validating endorser signatures, we also present the following reference implementations.</p>
pragma</span> solidity</span> ^0.8.9</span>;</span></span>
</span>
import</span> "@openzeppelin/contracts/utils/cryptography/SignatureChecker.sol"</span>;</span></span>
import</span> "@openzeppelin/contracts/utils/cryptography/EIP712.sol"</span>;</span></span>
</span>
import</span> "./IERC5453.sol"</span>;</span></span>
</span>
abstract</span> contract</span> AERC5453Endorsible</span> is</span> EIP712</span>,</span></span>
    IERC5453EndorsementCore</span>, </span>IERC5453EndorsementDigest</span>, </span>IERC5453EndorsementDataTypeA</span>, </span>IERC5453EndorsementDataTypeB</span> {</span></span>
    //</span> ...</span></span>
</span>
    function</span> _validate</span>(</span></span>
        bytes32</span> msgDigest</span>,</span></span>
        SingleEndorsementData</span> memory</span> endersement</span></span>
    )</span> internal</span> virtual</span> {</span></span>
        require</span>(</span></span>
            endersement</span>.</span>sig</span>.</span>length </span>==</span> 65</span>,</span></span>
            "AERC5453Endorsible: wrong signature length"</span></span>
        )</span>;</span></span>
        require</span>(</span></span>
            SignatureChecker</span>.</span>isValidSignatureNow</span>(</span></span>
                endersement</span>.</span>endorserAddress</span>,</span></span>
                msgDigest</span>,</span></span>
                endersement</span>.</span>sig</span></span>
            )</span>,</span></span>
            "AERC5453Endorsible: invalid signature"</span></span>
        )</span>;</span></span>
    }</span></span>
    //</span> ...</span></span>
</span>
    modifier</span> onlyEndorsed</span>(</span></span>
        bytes32</span> _functionParamStructHash</span>,</span></span>
        bytes</span> calldata</span> _extensionData</span></span>
    )</span> {</span></span>
        require</span>(</span>_isEndorsed</span>(</span>_functionParamStructHash</span>,</span> _extensionData</span>)</span>)</span>;</span></span>
        _</span>;</span></span>
    }</span></span>
</span>
    function</span> computeExtensionDataTypeB</span>(</span></span>
        uint256</span> nonce</span>,</span></span>
        uint256</span> validSince</span>,</span></span>
        uint256</span> validBy</span>,</span></span>
        address</span>[</span>]</span> calldata</span> endorserAddress</span>,</span></span>
        bytes</span>[</span>]</span> calldata</span> sigs</span></span>
    )</span> external</span> pure</span> override</span> returns</span> (</span>bytes</span> memory</span>)</span> {</span></span>
        require</span>(</span>endorserAddress</span>.</span>length </span>==</span> sigs</span>.</span>length</span>)</span>;</span></span>
        SingleEndorsementData</span>[</span>]</span></span>
            memory</span> endorsements </span>=</span> new</span> SingleEndorsementData</span>[</span>]</span>(</span></span>
                endorserAddress</span>.</span>length</span></span>
            )</span>;</span></span>
        for</span> (</span>uint256</span> i </span>=</span> 0</span>;</span> i </span><</span> endorserAddress</span>.</span>length</span>;</span> +</span>+</span>i</span>)</span> {</span></span>
            endorsements</span>[</span>i</span>]</span> =</span> SingleEndorsementData</span>(</span></span>
                endorserAddress</span>[</span>i</span>]</span>,</span></span>
                sigs</span>[</span>i</span>]</span></span>
            )</span>;</span></span>
        }</span></span>
        return</span></span>
            abi</span>.</span>encode</span>(</span></span>
                GeneralExtensionDataStruct</span>(</span></span>
                    MAGIC_WORLD</span>,</span></span>
                    ERC5453_TYPE_B</span>,</span></span>
                    nonce</span>,</span></span>
                    validSince</span>,</span></span>
                    validBy</span>,</span></span>
                    abi</span>.</span>encode</span>(</span>endorsements</span>)</span></span>
                )</span></span>
            )</span>;</span></span>
    }</span></span>
}</span></span>
</span></code></pre>
See AERC5453.sol</code></a></p>
Reference Implementation of EndorsableERC721</code></h3>
Here is a reference implementation of EndorsableERC721</code> that achieves similar behavior of ERC-4494</code>.</p>
pragma</span> solidity</span> ^0.8.9</span>;</span></span>
</span>
contract</span> EndorsableERC721</span> is</span> ERC721</span>, </span>AERC5453Endorsible</span> {</span></span>
    //</span>...</span></span>
</span>
    function</span> mint</span>(</span></span>
        address</span> _to</span>,</span></span>
        uint256</span> _tokenId</span>,</span></span>
        bytes</span> calldata</span> _extraData</span></span>
    )</span></span>
        external</span></span>
        onlyEndorsed</span>(</span></span>
            _computeFunctionParamHash</span>(</span></span>
                "</span>function</span> mint</span>(</span>address</span> _to</span>,</span>uint256</span> _tokenId</span>)</span>"</span>,</span></span>
                abi</span>.</span>encode</span>(</span>_to</span>,</span> _tokenId</span>)</span></span>
            )</span>,</span></span>
            _extraData</span></span>
        )</span></span>
    {</span></span>
        _mint</span>(</span>_to</span>,</span> _tokenId</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>
See EndorsableERC721.sol</code></a></p>
Reference Implementation of ThresholdMultiSigForwarder</code></h3>
Here is a reference implementation of ThresholdMultiSigForwarder that achieves similar behavior of multi-sig threshold approval
remote contract call like a Gnosis-Safe wallet.</p>
pragma</span> solidity</span> ^0.8.9</span>;</span></span>
</span>
contract</span> ThresholdMultiSigForwarder</span> is</span> AERC5453Endorsible</span> {</span></span>
    //</span>...</span></span>
    function</span> forward</span>(</span></span>
        address</span> _dest</span>,</span></span>
        uint256</span> _value</span>,</span></span>
        uint256</span> _gasLimit</span>,</span></span>
        bytes</span> calldata</span> _calldata</span>,</span></span>
        bytes</span> calldata</span> _extraData</span></span>
    )</span></span>
        external</span></span>
        onlyEndorsed</span>(</span></span>
            _computeFunctionParamHash</span>(</span></span>
                "</span>function</span> forward</span>(</span>address</span> _dest</span>,</span>uint256</span> _value</span>,</span>uint256</span> _gasLimit</span>,</span>bytes</span> calldata</span> _calldata</span>)</span>"</span>,</span></span>
                abi</span>.</span>encode</span>(</span>_dest</span>,</span> _value</span>,</span> _gasLimit</span>,</span> keccak256</span>(</span>_calldata</span>)</span>)</span></span>
            )</span>,</span></span>
            _extraData</span></span>
        )</span></span>
    {</span></span>
        string</span> memory</span> errorMessage </span>=</span> "Fail to call remote contract"</span>;</span></span>
        (</span>bool</span> success</span>,</span> bytes</span> memory</span> returndata</span>)</span> =</span> _dest</span>.</span>call</span>{</span>value</span>:</span> _value</span>}</span>(</span></span>
            _calldata</span></span>
        )</span>;</span></span>
        Address</span>.</span>verifyCallResult</span>(</span>success</span>,</span> returndata</span>,</span> errorMessage</span>)</span>;</span></span>
    }</span></span>
</span>
}</span></span>
</span></code></pre>
See ThresholdMultiSigForwarder.sol</code></a></p>
Security Considerations</h2>
Replay Attacks</h3>
A replay attack is a type of attack on cryptography authentication. In a narrow sense, it usually refers to a type of attack that circumvents the cryptographically signature verification by reusing an existing signature for a message being signed again. Any implementations relying on this EIP must realize that all smart endorsements described here are cryptographic signatures that are public</em> and can be obtained by anyone. They must foresee the possibility of a replay of the transactions not only at the exact deployment of the same smart contract, but also other deployments of similar smart contracts, or of a version of the same contract on another chainId</code>, or any other similar attack surfaces. The nonce</code>, validSince</code>, and validBy</code> fields are meant to restrict the surface of attack but might not fully eliminate the risk of all such attacks, e.g. see the Phishing</a> section.</p>
Phishing</h3>
It's worth pointing out a special form of replay attack by phishing. An adversary can design another smart contract in a way that the user be tricked into signing a smart endorsement for a seemingly legitimate purpose, but the data-to-designed matches the target application</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Multi-privilege Management NFT Extension
2022-07-30T00:00:00+00:00
Abstract</h2>
This EIP defines an interface extending EIP-721</a> to provide shareable multi-privileges for NFTs. Privileges may be on-chain (voting rights, permission to claim an airdrop) or off-chain (a coupon for an online store, a discount at a local restaurant, access to VIP lounges in airports). Each NFT may contain many privileges, and the holder of a privilege can verifiably transfer that privilege to others. Privileges may be non-shareable or shareable. Shareable privileges can be cloned, with the provider able to adjust the details according to the spreading path. Expiration periods can also be set for each privilege.</p>
Motivation</h2>
This standard aims to efficiently manage privileges attached to NFTs in real-time. Many NFTs have functions other than just being used as profile pictures or art collections, they may have real utilities in different scenarios. For example, a fashion store may give a discount for its own NFT holders; a DAO member NFT holder can vote for the proposal of how to use their treasury; a dApp may create an airdrop event to attract a certain group of people like some blue chip NFT holders to claim; the grocery store can issue its membership card on chain (as an NFT) and give certain privileges when the members shop at grocery stores, etc. There are cases when people who own NFTs do not necessarily want to use their privileges. By providing additional data recording different privileges a NFT collection has and interfaces to manage them, users can transfer or sell privileges without losing their ownership of the NFT.</p>
EIP-721</a> only records the ownership and its transfer, the privileges of an NFT are not recorded on-chain. This extension would allow merchants/projects to give out a certain privilege to a specified group of people, and owners of the privileges can manage each one of the privileges independently. This facilitates a great possibility for NFTs to have real usefulness.</p>
For example, an airline company issues a series of EIP-721</a>/EIP-1155</a> tokens to Crypto Punk holders to give them privileges, in order to attract them to join their club. However, since these tokens are not bound to the original NFT, if the original NFT is transferred, these privileges remain in the hands of the original holders, and the new holders cannot enjoy the privileges automatically.
So, we propose a set of interfaces that can bind the privileges to the underlying NFT, while allowing users to manage the privileges independently.</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>
Every contract complying with this standard MUST implement the IERC5496</code> interface. The shareable multi-privilege extension</strong> is OPTIONAL for EIP-721 contracts.</p>
///</span> @title</span> multi-privilege extension for EIP-721</span></span>
///</span>  Note</span>: the EIP-165 identifier for this interface is 0x076e1bbb</span></span>
interface</span> IERC5496</span>{</span></span>
    ///</span> @notice</span> Emitted when `owner` changes the `privilege holder` of a NFT.</span></span>
    event</span> PrivilegeAssigned</span>(</span>uint256</span> tokenId</span>, </span>uint256</span> privilegeId</span>, </span>address</span> user</span>, </span>uint256</span> expires</span>)</span>;</span></span>
    ///</span> @notice</span> Emitted when `contract owner` changes the `total privilege` of the collection</span></span>
    event</span> PrivilegeTotalChanged</span>(</span>uint256</span> newTotal</span>, </span>uint256</span> oldTotal</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> set the privilege holder of a NFT.</span></span>
    ///</span> @dev</span> expires should be less than 30 days</span></span>
    ///</span> Throws if `msg.sender` is not approved or owner of the tokenId.</span></span>
    ///</span> @param</span> tokenId</span> The NFT to set privilege for</span></span>
    ///</span> @param</span> privilegeId</span> The privilege to set</span></span>
    ///</span> @param</span> user</span> The privilege holder to set</span></span>
    ///</span> @param</span> expires</span> For how long the privilege holder can have</span></span>
    function</span> setPrivilege</span>(</span>uint256</span> tokenId</span>,</span> uint256</span> privilegeId</span>,</span> address</span> user</span>,</span> uint256</span> expires</span>)</span> external</span>;</span></span>
</span>
    ///</span> @notice</span> Return the expiry timestamp of a privilege</span></span>
    ///</span> @param</span> tokenId</span> The identifier of the queried NFT</span></span>
    ///</span> @param</span> privilegeId</span> The identifier of the queried privilege</span></span>
    ///</span> @return</span> Whether</span> a user has a certain privilege</span></span>
    function</span> privilegeExpires</span>(</span>uint256</span> tokenId</span>,</span> uint256</span> privilegeId</span>)</span> external</span> view</span> returns</span>(</span>uint256</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Check if a user has a certain privilege</span></span>
    ///</span> @param</span> tokenId</span> The identifier of the queried NFT</span></span>
    ///</span> @param</span> privilegeId</span> The identifier of the queried privilege</span></span>
    ///</span> @param</span> user</span> The address of the queried user</span></span>
    ///</span> @return</span> Whether</span> a user has a certain privilege</span></span>
    function</span> hasPrivilege</span>(</span>uint256</span> tokenId</span>,</span> uint256</span> privilegeId</span>,</span> address</span> user</span>)</span> external</span> view</span> returns</span>(</span>bool</span>)</span>;</span></span>
}</span></span></code></pre>
Every contract implementing this standard SHOULD set a maximum privilege number before setting any privilege, the privilegeId</code> MUST NOT be greater than the maximum privilege number.</p>
The PrivilegeAssigned</code> event MUST be emitted when setPrivilege</code> is called.</p>
The PrivilegeTotalChanged</code> event MUST be emitted when the total privilege</code> of the collection is changed.</p>
The supportsInterface</code> method MUST return true</code> when called with 0x076e1bbb</code>.</p>
///</span> @title</span> Cloneable extension - Optional for EIP-721</span></span>
interface</span> IERC721Cloneable</span> {</span></span>
    ///</span> @notice</span> Emitted when set the `privilege ` of a NFT cloneable.</span></span>
    event</span> PrivilegeCloned</span>(</span>uint</span> tokenId</span>, </span>uint</span> privId</span>, </span>address</span> from</span>, </span>address</span> to</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> set a certain privilege cloneable</span></span>
    ///</span> @param</span> tokenId</span> The identifier of the queried NFT</span></span>
    ///</span> @param</span> privilegeId</span> The identifier of the queried privilege</span></span>
    ///</span> @param</span> referrer</span> The address of the referrer</span></span>
    ///</span> @return</span> Whether</span> the operation is successful or not</span></span>
    function</span> clonePrivilege</span>(</span>uint</span> tokenId</span>,</span> uint</span> privId</span>,</span> address</span> referrer</span>)</span> external</span> returns</span> (</span>bool</span>)</span>;</span></span>
}</span></span></code></pre>
The PrivilegeCloned</code> event MUST be emitted when clonePrivilege</code> is called.</p>
For Compliant contract, it is RECOMMENDED to use EIP-1271</a> to validate the signatures.</p>
Rationale</h2>
Shareable Privileges</h3>
The number of privilege holders is limited by the number of NFTs if privileges are non-shareable. A shareable privilege means the original privilege holder can copy the privilege and give it to others, not transferring his/her own privilege to them. This mechanism greatly enhances the spread of privileges as well as the adoption of NFTs.</p>
Expire Date Type</h3>
The expiry timestamp of a privilege is a timestamp and stored in uint256</code> typed variables.</p>
Beneficiary of Referrer</h3>
For example, a local pizza shop offers a 30% off Coupon and the owner of the shop encourages their consumers to share the coupon with friends, then the friends can get the coupon. Let's say Tom gets 30% off Coupon from the shop and he shares the coupon with Alice. Alice gets the coupon too and Alice's referrer is Tom. For some certain cases, Tom may get more rewards from the shop. This will help the merchants in spreading the promotion among consumers.</p>
Proposal: NFT Transfer</h3>
If the owner of the NFT transfers ownership to another user, there is no impact on "privileges". But errors may occur if the owner tries to withdraw the original EIP-721</a> token from the wrapped NFT through unwrap()</code> if any available privileges are still ongoing. We protect the rights of holders of the privileges to check the last expiration date of the privilege.</p>
function</span> unwrap</span>(</span>uint256</span> tokenId</span>,</span> address</span> to</span>)</span> external</span> {</span></span>
    require</span>(</span>getBlockTimestamp</span>(</span>)</span> ></span>=</span> privilegeBook</span>[</span>tokenId</span>]</span>.</span>lastExpiresAt</span>,</span> "privilege not yet expired"</span>)</span>;</span></span>
</span>
    require</span>(</span>ownerOf</span>(</span>tokenId</span>)</span> ==</span> msg.sender</span>,</span> "not owner"</span>)</span>;</span></span>
</span>
    _burn</span>(</span>tokenId</span>)</span>;</span></span>
</span>
    IERC721</span>(</span>nft</span>)</span>.</span>transferFrom</span>(</span>address</span>(</span>this</span>)</span>,</span> to</span>,</span> tokenId</span>)</span>;</span></span>
</span>
    emit</span> Unwrap</span>(</span>nft</span>,</span> tokenId</span>,</span> msg.sender</span>,</span> to</span>)</span>;</span></span>
}</span></span></code></pre>Backwards Compatibility</h2>
This EIP is compatible with any kind of NFTs that follow the EIP-721 standard. It only adds more functions and data structures without interfering with the original EIP-721</a> standard.</p>
Test Cases</h2>
Test cases are implemented with the reference implementation.</p>
Test Code</h3>
test.js</a></p>
Run in terminal:</p>
truffle</span> test</span> ./test/test.js</span></span></code></pre>
testCloneable.js</a></p>
Run in terminal:</p>
truffle</span> test</span> ./test/testCloneable.js</span></span></code></pre>Reference Implementation</h2>
//</span> SPDX-License-Identifier: CC0-1.0</span></span>
pragma</span> solidity</span> ^0.8.0</span>;</span> </span></span>
</span>
import</span> "@openzeppelin/contracts/token/ERC721/ERC721.sol"</span>;</span></span>
import</span> "@openzeppelin/contracts/utils/introspection/IERC165.sol"</span>;</span></span>
import</span> "./IERC5496.sol"</span>;</span></span>
</span>
contract</span> ERC5496</span> is</span> ERC721</span>, </span>IERC5496</span> {</span></span>
    struct</span> PrivilegeRecord</span> {</span></span>
        address</span> user</span>;</span></span>
        uint256</span> expiresAt</span>;</span></span>
    }</span></span>
    struct</span> PrivilegeStorage</span> {</span></span>
        uint</span> lastExpiresAt</span>;</span></span>
        //</span> privId => PrivilegeRecord</span></span>
        mapping</span>(</span>uint</span> =></span> PrivilegeRecord</span>)</span> privilegeEntry</span>;</span></span>
    }</span></span>
</span>
    uint</span> public</span> privilegeTotal</span>;</span></span>
    //</span> tokenId => PrivilegeStorage</span></span>
    mapping</span>(</span>uint</span> =></span> PrivilegeStorage</span>)</span> public</span> privilegeBook</span>;</span></span>
    mapping</span>(</span>address</span> =></span> mapping</span>(</span>address</span> =></span> bool</span>)</span>)</span> private</span> privilegeDelegator</span>;</span></span>
</span>
    constructor</span>(</span>string</span> memory</span> name_</span>,</span> string</span> memory</span> symbol_</span>)</span></span>
    ERC721</span>(</span>name_,symbol_)</span></span>
    {</span></span>
    </span></span>
    }</span></span>
</span>
    function</span> setPrivilege</span>(</span></span>
        uint</span> tokenId</span>,</span></span>
        uint</span> privId</span>,</span></span>
        address</span> user</span>,</span></span>
        uint64</span> expires</span></span>
    )</span> external</span> virtual</span> {</span></span>
        require</span>(</span>(</span>hasPrivilege</span>(</span>tokenId</span>,</span> privId</span>,</span> ownerOf</span>(</span>tokenId</span>)</span>)</span> &&</span> _isApprovedOrOwner</span>(</span>msg.sender</span>,</span> tokenId</span>)</span>)</span> ||</span> _isDelegatorOrHolder</span>(</span>msg.sender</span>,</span> tokenId</span>,</span> privId</span>)</span>,</span> "ERC721: transfer caller is not owner nor approved"</span>)</span>;</span></span>
        require</span>(</span>expires </span><</span> block</span>.</span>timestamp </span>+</span> 30</span> days</span>,</span> "expire time invalid"</span>)</span>;</span></span>
        require</span>(</span>privId </span><</span> privilegeTotal</span>,</span> "invalid privilege id"</span>)</span>;</span></span>
        privilegeBook</span>[</span>tokenId</span>]</span>.</span>privilegeEntry</span>[</span>privId</span>]</span>.</span>user </span>=</span> user</span>;</span></span>
        if</span> (</span>_isApprovedOrOwner</span>(</span>msg.sender</span>,</span> tokenId</span>)</span>)</span> {</span></span>
            privilegeBook</span>[</span>tokenId</span>]</span>.</span>privilegeEntry</span>[</span>privId</span>]</span>.</span>expiresAt </span>=</span> expires</span>;</span></span>
            if</span> (</span>privilegeBook</span>[</span>tokenId</span>]</span>.</span>lastExpiresAt </span><</span> expires</span>)</span> {</span></span>
                privilegeBook</span>[</span>tokenId</span>]</span>.</span>lastExpiresAt </span>=</span> expires</span>;</span></span>
            }</span></span>
        }</span></span>
        emit</span> PrivilegeAssigned</span>(</span>tokenId</span>,</span> privId</span>,</span> user</span>,</span> uint64</span>(</span>privilegeBook</span>[</span>tokenId</span>]</span>.</span>privilegeEntry</span>[</span>privId</span>]</span>.</span>expiresAt</span>)</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> hasPrivilege</span>(</span></span>
        uint256</span> tokenId</span>,</span></span>
        uint256</span> privId</span>,</span></span>
        address</span> user</span></span>
    )</span> public</span> virtual</span> view</span> returns</span>(</span>bool</span>)</span> {</span></span>
        if</span> (</span>privilegeBook</span>[</span>tokenId</span>]</span>.</span>privilegeEntry</span>[</span>privId</span>]</span>.</span>expiresAt </span>></span>=</span> block</span>.</span>timestamp</span>)</span>{</span></span>
            return</span> privilegeBook</span>[</span>tokenId</span>]</span>.</span>privilegeEntry</span>[</span>privId</span>]</span>.</span>user </span>==</span> user</span>;</span></span>
        }</span></span>
        return</span> ownerOf</span>(</span>tokenId</span>)</span> ==</span> user</span>;</span></span>
    }</span></span>
</span>
    function</span> privilegeExpires</span>(</span></span>
        uint256</span> tokenId</span>,</span></span>
        uint256</span> privId</span></span>
    )</span> public</span> virtual</span> view</span> returns</span>(</span>uint256</span>)</span>{</span></span>
        return</span> privilegeBook</span>[</span>tokenId</span>]</span>.</span>privilegeEntry</span>[</span>privId</span>]</span>.</span>expiresAt</span>;</span></span>
    }</span></span>
</span>
    function</span> _setPrivilegeTotal</span>(</span></span>
        uint</span> total</span></span>
    )</span> internal</span> {</span></span>
        emit</span> PrivilegeTotalChanged</span>(</span>total</span>,</span> privilegeTotal</span>)</span>;</span></span>
        privilegeTotal </span>=</span> total</span>;</span></span>
    }</span></span>
</span>
    function</span> getPrivilegeInfo</span>(</span>uint</span> tokenId</span>,</span> uint</span> privId</span>)</span> external</span> view</span> returns</span>(</span>address</span> user</span>,</span> uint256</span> expiresAt</span>)</span> {</span></span>
        return</span> (</span>privilegeBook</span>[</span>tokenId</span>]</span>.</span>privilegeEntry</span>[</span>privId</span>]</span>.</span>user</span>,</span> privilegeBook</span>[</span>tokenId</span>]</span>.</span>privilegeEntry</span>[</span>privId</span>]</span>.</span>expiresAt</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> setDelegator</span>(</span>address</span> delegator</span>,</span> bool</span> enabled</span>)</span> external</span> {</span></span>
        privilegeDelegator</span>[</span>msg.sender</span>]</span>[</span>delegator</span>]</span> =</span> enabled</span>;</span></span>
    }</span></span>
</span>
    function</span> _isDelegatorOrHolder</span>(</span>address</span> delegator</span>,</span> uint256</span> tokenId</span>,</span> uint</span> privId</span>)</span> internal</span> virtual</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span>
        address</span> holder </span>=</span> privilegeBook</span>[</span>tokenId</span>]</span>.</span>privilegeEntry</span>[</span>privId</span>]</span>.</span>user</span>;</span></span>
         return</span> (</span>delegator </span>==</span> holder </span>||</span> isApprovedForAll</span>(</span>holder</span>,</span> delegator</span>)</span> ||</span> privilegeDelegator</span>[</span>holder</span>]</span>[</span>delegator</span>]</span>)</span>;</span></span>
    }</span></span>
</span>
    function</span> supportsInterface</span>(</span>bytes4</span> interfaceId</span>)</span> public</span> override</span> virtual</span> view</span> returns</span> (</span>bool</span>)</span> {</span></span>
        return</span> interfaceId </span>==</span> type</span>(</span>IERC5496</span>)</span>.</span>interfaceId </span>||</span> super</span>.</span>supportsInterface</span>(</span>interfaceId</span>)</span>;</span></span>
    }</span></span>
}</span></span></code></pre>Security Considerations</h2>
Implementations must thoroughly consider who has the permission to set or clone privileges.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


ERC-1155 Allowance Extension
2022-07-11T00:00:00+00:00
Abstract</h2>
This ERC defines standard functions for granular approval of ERC-1155</a> tokens by both id</code> and amount</code>. This ERC extends ERC-1155</a>.</p>
Motivation</h2>
ERC-1155</a>'s popularity means that multi-token management transactions occur on a daily basis. Although it can be used as a more comprehensive alternative to ERC-721</a>, ERC-1155 is most commonly used as intended: creating multiple id</code>s, each with multiple tokens. While many projects interface with these semi-fungible tokens, by far the most common interactions are with NFT marketplaces.</p>
Due to the nature of the blockchain, programming errors or malicious operators can cause permanent loss of funds. It is therefore essential that transactions are as trustless as possible. ERC-1155 uses the setApprovalForAll</code> function, which approves ALL tokens with a specific id</code>. This system has obvious minimum required trust flaws. This ERC combines ideas from ERC-20</a> and ERC-721</a> in order to create a trust mechanism where an owner can allow a third party, such as a marketplace, to approve a limited (instead of unlimited) number of tokens of one id</code>.</p>
Specification</h2>
The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.</p>
Contracts using this ERC MUST implement the IERC5216</code> interface.</p>
Interface implementation</h3>
/**</span></span>
 * </span>@title</span> ERC-1155 Allowance Extension</span></span>
 * </span>Note</span>: the ERC-165 identifier for this interface is 0x1be07d74</span></span>
 */</span></span>
interface</span> IERC5216</span> is</span> IERC1155</span> {</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Emitted when `account` grants or revokes permission to `operator` to transfer their tokens, according to</span></span>
     * `id` and with an amount: `amount`.</span></span>
     */</span></span>
    event</span> Approval</span>(</span>address</span> indexed</span> account</span>, </span>address</span> indexed</span> operator</span>, </span>uint256</span> id</span>, </span>uint256</span> amount</span>)</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Grants permission to `operator` to transfer the caller's tokens, according to `id`, and an amount: `amount`.</span></span>
     * Emits an {Approval} event.</span></span>
     *</span></span>
     * Requirements:</span></span>
     * - `operator` cannot be the caller.</span></span>
     */</span></span>
    function</span> approve</span>(</span>address</span> operator</span>,</span> uint256</span> id</span>,</span> uint256</span> amount</span>)</span> external</span>;</span></span>
</span>
    /**</span></span>
     * </span>@notice</span> Returns the amount allocated to `operator` approved to transfer `account`'s tokens, according to `id`.</span></span>
     */</span></span>
    function</span> allowance</span>(</span>address</span> account</span>,</span> address</span> operator</span>,</span> uint256</span> id</span>)</span> external</span> view</span> returns</span> (</span>uint256</span>)</span>;</span></span>
}</span></span></code></pre>
The approve(address operator, uint256 id, uint256 amount)</code> function MUST be either public</code> or external</code>.</p>
The allowance(address account, address operator, uint256 id)</code> function MUST be either public</code> or external</code> and MUST be view</code>.</p>
The safeTrasferFrom</code> function (as defined by ERC-1155) MUST:</p>

Not revert if the user has approved msg.sender</code> with a sufficient amount</code></li>
Subtract the transferred amount of tokens from the approved amount if msg.sender</code> is not approved with setApprovalForAll</code></li>
</ul>
In addition, the safeBatchTransferFrom</code> MUST:</p>

Add an extra condition that checks if the allowance</code> of all ids</code> have the approved amounts</code> (See _checkApprovalForBatch</code> function reference implementation)</li>
</ul>
The Approval</code> event MUST be emitted when a certain number of tokens are approved.</p>
The supportsInterface</code> method MUST return true</code> when called with 0x1be07d74</code>.</p>
Rationale</h2>
The name "ERC-1155 Allowance Extension" was chosen because it is a succinct description of this ERC. Users can approve their tokens by id</code> and amount</code> to operator</code>s.</p>
By having a way to approve and revoke in a manner similar to ERC-20</a>, the trust level can be more directly managed by users:</p>

Using the approve</code> function, users can approve an operator to spend an amount</code> of tokens for each id</code>.</li>
Using the allowance</code> function, users can see the approval that an operator has for each id</code>.</li>
</ul>
The ERC-20</a> name patterns were used due to similarities with ERC-20</a> approvals.</p>
Backwards Compatibility</h2>
This standard is compatible with ERC-1155</a>.</p>
Reference Implementation</h2>
The reference implementation can be found here</a>.</p>
Security Considerations</h2>
Users of this ERC must thoroughly consider the amount of tokens they give permission to operators</code>, and should revoke unused authorizations.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Cross-Chain Execution
2022-06-14T00:00:00+00:00
Abstract</h2>
This specification defines a cross-chain execution interface for EVM-based blockchains. Implementations of this specification will allow contracts on one chain to call contracts on another by sending a cross-chain message.</p>
The specification defines two components: the "Message Dispatcher" and the "Message Executor". The Message Dispatcher lives on the calling side, and the executor lives on the receiving side. When a message is sent, a Message Dispatcher will move the message through a transport layer to a Message Executor, where they are executed. Implementations of this specification must implement both components.</p>
Motivation</h2>
Many Ethereum protocols need to coordinate state changes across multiple EVM-based blockchains. These chains often have native or third-party bridges that allow Ethereum contracts to execute code. However, bridges have different APIs so bridge integrations are custom. Each one affords different properties; with varying degrees of security, speed, and control. Defining a simple, common specification will increase code re-use and allow us to use common bridge implementations.</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>
This specification allows contracts on one chain to send messages to contracts on another chain. There are two key interfaces that needs to be implemented:</p>

MessageDispatcher</code></li>
MessageExecutor</code></li>
</ul>
The MessageDispatcher</code> lives on the origin chain and dispatches messages to the MessageExecutor</code> for execution. The MessageExecutor</code> lives on the destination chain and executes dispatched messages.</p>
MessageDispatcher</h3>
The MessageDispatcher</code> lives on the chain from which messages are sent. The Dispatcher's job is to broadcast messages through a transport layer to one or more MessageExecutor</code> contracts.</p>
A unique messageId</code> MUST be generated for each message or message batch. The message identifier MUST be unique across chains and dispatchers.  This can be achieved by hashing a tuple of chainId, dispatcherAddress, messageNonce</code> where messageNonce is a monotonically increasing integer per message.</p>
MessageDispatcher Methods</h4>
dispatchMessage</strong></p>
Will dispatch a message to be executed by the MessageExecutor</code> on the destination chain specified by toChainId</code>.</p>
MessageDispatcher</code>s MUST emit the MessageDispatched</code> event when a message is dispatched.</p>
MessageDispatcher</code>s MUST revert if toChainId</code> is not supported.</p>
MessageDispatcher</code>s MUST forward the message to a MessageExecutor</code> on the toChainId</code>.</p>
MessageDispatcher</code>s MUST use a unique messageId</code> for each message.</p>
MessageDispatcher</code>s MUST return the messageId</code> to allow the message sender to track the message.</p>
MessageDispatcher</code>s MAY require payment.</p>
interface</span> MessageDispatcher</span> {</span></span>
  function</span> dispatchMessage</span>(</span>uint256</span> toChainId</span>,</span> address</span> to</span>,</span> bytes</span> calldata</span> data</span>)</span> external</span> payable</span> returns</span> (</span>bytes32</span> messageId</span>)</span>;</span></span>
}</span></span></code></pre>-</span> n</span>ame</span>:</span> d</span>ispatchMessage</span></span>
  t</span>ype</span>:</span> f</span>unction</span></span>
  s</span>tateMutability</span>:</span> p</span>ayable</span></span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> t</span>oChainId</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> t</span>o</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
    -</span> n</span>ame</span>:</span> d</span>ata</span></span>
      t</span>ype</span>:</span> b</span>ytes</span></span>
  o</span>utputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> m</span>essageId</span></span>
      t</span>ype</span>:</span> b</span>ytes32</span></span></code></pre>MessageDispatcher Events</h4>
MessageDispatched</strong></p>
The MessageDispatched</code> event MUST be emitted by the MessageDispatcher</code> when an individual message is dispatched.</p>
interface</span> MessageDispatcher</span> {</span></span>
  event</span> MessageDispatched</span>(</span></span>
    bytes32</span> indexed</span> messageId</span>,</span></span>
    address</span> indexed</span> from</span>,</span></span>
    uint256</span> indexed</span> toChainId</span>,</span></span>
    address</span> to</span>,</span></span>
    bytes</span> data</span>,</span></span>
  )</span>;</span></span>
}</span></span></code></pre>-</span> n</span>ame</span>:</span> M</span>essageDispatched</span></span>
  t</span>ype</span>:</span> e</span>vent</span></span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> m</span>essageId</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> b</span>ytes32</span></span>
    -</span> n</span>ame</span>:</span> f</span>rom</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
    -</span> n</span>ame</span>:</span> t</span>oChainId</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> t</span>o</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span>
    -</span> n</span>ame</span>:</span> d</span>ata</span></span>
      t</span>ype</span>:</span> b</span>ytes</span></span></code></pre>MessageExecutor</h3>
The MessageExecutor</code> executes dispatched messages and message batches. Developers must implement a MessageExecutor</code> in order to execute messages on the receiving chain.</p>
The MessageExecutor</code> will execute a messageId only once, but may execute messageIds in any order. This specification makes no ordering guarantees, because messages and message batches may travel non-sequentially through the transport layer.</p>
Execution</h4>
MessageExecutor</code>s SHOULD verify all message data with the bridge transport layer.</p>
MessageExecutor</code>s MUST NOT successfully execute a message more than once.</p>
MessageExecutor</code>s MUST revert the transaction when a message fails to be executed allowing the message to be retried at a later time.</p>
Calldata</strong></p>
MessageExecutor</code>s MUST append the ABI-packed (messageId</code>, fromChainId</code>, from</code>) to the calldata for each message being executed. This allows the receiver of the message to verify the cross-chain sender and the chain that the message is coming from.</p>
to</span>.</span>call</span>(</span>abi</span>.</span>encodePacked</span>(</span>data</span>,</span> messageId</span>,</span> fromChainId</span>,</span> from</span>)</span>)</span>;</span></span></code></pre>-</span> n</span>ame</span>:</span> c</span>alldata</span></span>
  t</span>ype</span>:</span> b</span>ytes</span></span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> d</span>ata</span></span>
      t</span>ype</span>:</span> b</span>ytes</span></span>
    -</span> n</span>ame</span>:</span> m</span>essageId</span></span>
      t</span>ype</span>:</span> b</span>ytes32</span></span>
    -</span> n</span>ame</span>:</span> f</span>romChainId</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> f</span>rom</span></span>
      t</span>ype</span>:</span> a</span>ddress</span></span></code></pre>MessageExecutor Events</h4>
MessageIdExecuted</strong></p>
MessageIdExecuted</code> MUST be emitted once a message or message batch has been executed.</p>
interface</span> MessageExecutor</span> {</span></span>
  event</span> MessageIdExecuted</span>(</span></span>
    uint256</span> indexed</span> fromChainId</span>,</span></span>
    bytes32</span> indexed</span> messageId</span></span>
  )</span>;</span></span>
}</span></span></code></pre>-</span> n</span>ame</span>:</span> M</span>essageIdExecuted</span></span>
  t</span>ype</span>:</span> e</span>vent</span></span>
  i</span>nputs</span>:</span></span>
    -</span> n</span>ame</span>:</span> f</span>romChainId</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> u</span>int256</span></span>
    -</span> n</span>ame</span>:</span> m</span>essageId</span></span>
      i</span>ndexed</span>:</span> true</span></span>
      t</span>ype</span>:</span> b</span>ytes32</span></span></code></pre>MessageExecutor Errors</h4>
MessageAlreadyExecuted</strong></p>
MessageExecutor</code>s MUST revert if a messageId has already been executed and SHOULD emit a MessageIdAlreadyExecuted</code> custom error.</p>
interface</span> MessageExecutor</span> {</span></span>
  error</span> MessageIdAlreadyExecuted</span>(</span></span>
    bytes32</span> messageId</span></span>
  )</span>;</span></span>
}</span></span></code></pre>
MessageFailure</strong></p>
MessageExecutor</code>s MUST revert if an individual message fails and SHOULD emit a MessageFailure</code> custom error.</p>
interface</span> MessageExecutor</span> {</span></span>
  error</span> MessageFailure</span>(</span></span>
    bytes32</span> messageId</span>,</span></span>
    bytes</span> errorData</span></span>
  )</span>;</span></span>
}</span></span></code></pre>Rationale</h2>
The MessageDispatcher</code> can be coupled to one or more MessageExecutor</code>. It is up to bridges to decide how to couple the two. Users can easily bridge a message by calling dispatchMessage</code> without being aware of the MessageExecutor</code> address. Messages can also be traced by a client using the data logged by the MessageIdExecuted</code> event.</p>
Some bridges may require payment in the native currency, so the dispatchMessage</code> function is payable.</p>
Backwards Compatibility</h2>
This specification is compatible with existing governance systems as it offers simple cross-chain execution.</p>
Security Considerations</h2>
Bridge trust profiles are variable, so users must understand that bridge security depends on the implementation.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Soulbound Badge
2022-05-30T00:00:00+00:00
Abstract</h2>
A soulbound badge is a token that, when minted, is bound to another Non-Fungible Token (NFT), and cannot be transferred/moved after that.</p>
Specification</h2>
interface</span> IERC5114</span> {</span></span>
	//</span> fired anytime a new instance of this badge is minted</span></span>
	//</span> this event **MUST NOT** be fired twice for the same `badgeId`</span></span>
	event</span> Mint</span>(</span>uint256</span> indexed</span> badgeId</span>, </span>address</span> indexed</span> nftAddress</span>, </span>uint256</span> indexed</span> nftTokenId</span>)</span>;</span></span>
</span>
	//</span> returns the NFT that this badge is bound to.</span></span>
	//</span> this function **MUST** throw if the badge hasn't been minted yet</span></span>
	//</span> this function **MUST** always return the same result every time it is called after it has been minted</span></span>
	//</span> this function **MUST** return the same value as found in the original `Mint` event for the badge</span></span>
	function</span> ownerOf</span>(</span>uint256</span> badgeId</span>)</span> external</span> view</span> returns</span> (</span>address</span> nftAddress</span>,</span> uint256</span> nftTokenId</span>)</span>;</span></span>
</span>
	//</span> returns a URI with details about this badge collection</span></span>
	//</span> the metadata returned by this is merged with the metadata return by `badgeUri(uint256)`</span></span>
	//</span> the collectionUri **MUST** be immutable (e.g., ipfs:// and not http://)</span></span>
	//</span> the collectionUri **MUST** be content addressable (e.g., ipfs:// and not http://)</span></span>
	//</span> data from `badgeUri` takes precedence over data returned by this method</span></span>
	//</span> any external links referenced by the content at `collectionUri` also **MUST** follow all of the above rules</span></span>
	function</span> collectionUri</span>(</span>)</span> external</span> pure</span> returns</span> (</span>string</span> collectionUri</span>)</span>;</span></span>
</span>
	//</span> returns a censorship resistant URI with details about this badge instance</span></span>
	//</span> the collectionUri **MUST** be immutable (e.g., ipfs:// and not http://)</span></span>
	//</span> the collectionUri **MUST** be content addressable (e.g., ipfs:// and not http://)</span></span>
	//</span> data from this takes precedence over data returned by `collectionUri`</span></span>
	//</span> any external links referenced by the content at `badgeUri` also **MUST** follow all of the above rules</span></span>
	function</span> badgeUri</span>(</span>uint256</span> badgeId</span>)</span> external</span> view</span> returns</span> (</span>string</span> badgeUri</span>)</span>;</span></span>
</span>
	//</span> returns a string that indicates the format of the `badgeUri` and `collectionUri` results (e.g., 'EIP-ABCD' or 'soulbound-schema-version-4')</span></span>
	function</span> metadataFormat</span>(</span>)</span> external</span> pure</span> returns</span> (</span>string</span> format</span>)</span>;</span></span>
}</span></span></code></pre>
Implementers of this standard SHOULD</strong> also depend on a standard for interface detection so callers can easily find out if a given contract implements this interface.</p>
Rationale</h2>
Immutability</h3>
By requiring that badges can never move, we both guarantee non-separability and non-mergeability among collections of soulbound badges that are bound to a single NFT while simultaneously allowing users to aggressively cache results.</p>
Content Addressable URIs Required</h3>
Soulbound badges are meant to be permanent badges/indicators attached to a persona.
This means that not only can the user not transfer ownership, but the minter also cannot withdraw/transfer/change ownership as well.
This includes mutating or removing any remote content as a means of censoring or manipulating specific users.</p>
No Specification for badgeUri</code> Data Format</h3>
The format of the data pointed to by collectionUri()</code> and badgeUri(uint256)</code>, and how to merge them, is intentionally left out of this standard in favor of separate standards that can be iterated on in the future.
The immutability constraints are the only thing defined by this to ensure that the spirit of this badge is maintained, regardless of the specifics of the data format.
The metadataFormat</code> function can be used to inform a caller what type/format/version of data they should expect at the URIs, so the caller can parse the data directly without first having to deduce its format via inspection.</p>
Backwards Compatibility</h2>
This is a new token type and is not meant to be backward compatible with any existing tokens other than existing viable souls (any asset that can be identified by [address,id]</code>).</p>
Security Considerations</h2>
Users of badges that claim to implement this EIP must be diligent in verifying they actually do.
A badge author can create a badge that, upon initial probing of the API surface, may appear to follow the rules when in reality it doesn't.
For example, the contract could allow transfers via some mechanism and simply not utilize them initially.</p>
It should also be made clear that soulbound badges are not bound to a human, they are bound to a persona.
A persona is any actor (which could be a group of humans) that collects multiple soulbound badges over time to build up a collection of badges.
This persona may transfer to another human, or to another group of humans, and anyone interacting with a persona should not assume that there is a single permanent human behind that persona.</p>
It is possible for a soulbound badge to be bound to another soulbound badge.
In theory, if all badges in the chain are created at the same time they could form a loop.
Software that tries to walk such a chain should take care to have an exit strategy if a loop is detected.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


ERC-721 Nonce Extension
2022-04-10T00:00:00+00:00
Abstract</h2>
This standard is an extension of ERC-721</a>. It proposes adding a nonce</code> function to ERC-721 tokens.</p>
Motivation</h2>
Some orders of NFT marketplaces have been attacked and the NFTs sold at a lower price than the current market floor price. This can happen when users transfer an NFT to another wallet and, later, back to the original wallet. This reactivates the order, which may list the token at a much lower price than the owner would have intended.</p>
This EIP proposes adding a nonce</code> property to ERC-721 tokens, and the nonce</code> will be changed when a token is transferred. If a nonce</code> is added to an order, the order can be checked to avoid attacks.</p>
Specification</h2>
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.</p>
</span>
///</span> @dev</span> the ERC-165 identifier for this interface is 0xce03fdab.</span></span>
interface</span> IERC5008</span> /*</span> is IERC165 </span>*/</span> {</span></span>
    ///</span> @notice</span> Emitted when the `nonce` of an NFT is </span>changed</span></span>
    event</span> NonceChanged</span>(</span>uint256</span> tokenId</span>, </span>uint256</span> nonce</span>)</span>;</span></span>
</span>
    ///</span> @notice</span> Get the nonce of an NFT</span></span>
    ///</span> Throws if `tokenId` is not a valid NFT</span></span>
    ///</span> @param</span> tokenId</span> The id of the NFT</span></span>
    ///</span> @return</span> The</span> nonce of the NFT</span></span>
    function</span> nonce</span>(</span>uint256</span> tokenId</span>)</span> external</span> view</span> returns</span>(</span>uint256</span>)</span>;</span></span>
}</span></span></code></pre>
The nonce(uint256 tokenId)</code> function MUST be implemented as view</code>.</p>
The supportsInterface</code> method MUST return true</code> when called with 0xce03fdab</code>.</p>
Rationale</h2>
At first transferCount</code> was considered as function name, but there may some case to change the nonce</code> besides transfer, such as important properties changed, then we changed transferCount</code> to nonce</code>.</p>
Backwards Compatibility</h2>
This standard is compatible with ERC-721.</p>
Test Cases</h2>
Test cases are included in test.js</a>.</p>
Run:</p>
cd</span> ../assets/eip-5008</span></span>
npm</span> install</span></span>
npm</span> run</span> test</span></span></code></pre>Reference Implementation</h2>
See ERC5008.sol</code></a>.</p>
Security Considerations</h2>
No security issues found.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


EVM trace specification
2020-12-07T00:00:00+00:00
Abstract</h2>
Introduce a new JSON standard for EVM traces during execution of state tests.</p>
Motivation</h2>
The Ethereum Virtual Machine executes all smart contract code on ethereum.
In order to debug smart contracts and state tests better, a common format was introduced to log every execution step of the EVM.
This format was implemented by Go-Ethereum, Parity-Ethereum, Nethermind and Besu.
Since the common format was not well-defined, the implementations differed slightly, making it hard to develop adequate tooling which reduces the usefulness of tracing significantly.</p>
This EIP has multiple goals:</p>

Move the specification to a more visible place to encourage new clients to implement it</li>
Strictly define corner cases that were not addressed in the previous version</li>
Allow for updates to the specification in case new fields are introduced during execution</li>
Provide sample output</li>
</ul>
Implementing this EIP in all major clients allows us to create meaningful differential fuzzers that fuzz EVM implementations for the mainnet and all upcoming hardforks.
It also helps to find differences in execution quickly in the case of a chain split.</p>
This EIP will enable users to create better differential fuzzing infrastructure to compare the EVM implementations of all major Ethereum clients against each other.
This could help to find bugs that are currently present in the client implementations.</p>
Specification</h2>
Clients should be able to execute simple transactions as well as code and return traces. In the following, we will call this client CUT (client under test) and use go-ethereum's
evm</code> binary for code examples.</p>
Datatypes</h3>
Type</th> Explanation</th> Example</th></tr></thead>

Number</td> Plain json number</td> "pc":0</td></tr>
Hex-Number</td> Hex-encoded number</td> "gas":"0x2540be400"</td></tr>
String</td> Plain string</td> "opName":"PUSH1"</td></tr>
Hex-String</td> Hex-encoded string</td> </td></tr>
Array of x</td> Array of x encoded values</td> </td></tr>
Key-Value</td> Key-Value structure with key and values encoded as hex strings</td> </td></tr>
Boolean</td> Json bool can either be true or false</td> "pass": true</td></tr>
</tbody></table>
Output</h3>
The CUT MUST output a json</code> object for EACH operation.</p>
Required Fields</h4>
Name</th> Type</th> Explanation</th></tr></thead>

pc</code></td> Number</td> Program Counter</td></tr>
op</code></td> Number</td> OpCode</td></tr>
gas</code></td> Hex-Number</td> Gas left before executing this operation</td></tr>
gasCost</code></td> Hex-Number</td> Gas cost of this operation</td></tr>
memSize</code></td> Number</td> Size of memory array</td></tr>
stack</code></td> Array of Hex-Numbers</td> Array of all values on the stack</td></tr>
depth</code></td> Number</td> Depth of the call stack</td></tr>
returnData</code></td> Hex-String</td> Data returned by function call</td></tr>
refund</code></td> Hex-Number</td> Amount of global</strong> gas refunded</td></tr>
</tbody></table>
Optional Fields</h4>
Name</th> Type</th> Explanation</th></tr></thead>

opName</code></td> String</td> Name of the operation</td></tr>
error</code></td> Hex-String</td> Description of an error (should contain revert reason if supported)</td></tr>
memory</code></td> Array of Hex-Strings</td> Array of all allocated values</td></tr>
storage</code></td> Key-Value</td> Array of all stored values</td></tr>
</tbody></table>
Example:</em></p>
{"pc":0,"op":96,"gas":"0x2540be400","gasCost":"0x3","memory":"0x","memSize":0,"stack":[],"depth":1,"error":null,"opName":"PUSH1"}</span></span></code></pre>

The stack</code>, memory</code> and memSize</code> are the values before</em> execution of the op.</li>
All array attributes (stack</code>, memory</code>) MUST be initialized to empty arrays ("stack":[]</code>) NOT to null.</li>
If the CUT will not be outputting values for memory</code> or storage</code> then the memory</code> and storage</code> fields are omitted.
This can happen either because the CUT does not support tracing these fields or it has been configured not to trace it.</li>
The memSize</code> field MUST be present regardless of memory</code> support.</li>
Clients SHOULD implement a way to disable recording the storage as the stateroot includes all storage updates.</li>
Clients SHOULD output the fields in the same order as listed in this EIP.</li>
</ul>
The CUT MUST NOT output a line for the STOP</code> operation if an error occurred:</p>
Example:</em></p>
{"pc":2,"op":0,"gas":"0x2540be3fd","gasCost":"0x0","memory":"0x","memSize":0,"stack":["0x40"],"depth":1,"error":null,"opName":"STOP"}</span></span></code></pre>Summary and Error Handling</h3>
At the end of execution, the CUT MUST print summary info; this info SHOULD have the following fields.
The summary should be a single jsonl</code> object.</p>
Required Fields</h4>
Name</th> Type</th> Explanation</th></tr></thead>

stateRoot</code></td> Hex-String</td> Root of the state trie after executing the transaction</td></tr>
output</code></td> </td> Return values of the function</td></tr>
gasUsed</code></td> Hex-Number</td> All gas used by the transaction</td></tr>
pass</code></td> Boolean</td> Bool whether transaction was executed successfully</td></tr>
</tbody></table>
Optional Fields</h4>
Name</th> Type</th> Explanation</th></tr></thead>

time</code></td> Number</td> Time in nanoseconds needed to execute the transaction</td></tr>
fork</code></td> String</td> Name of the fork rules used for execution</td></tr>
</tbody></table>
Example</em>:</p>
{"stateRoot":"0xd4c577737f5d20207d338c360c42d3af78de54812720e3339f7b27293ef195b7","output":"","gasUsed":"0x3","pass":"true","time":141485}</span></span></code></pre>Rationale</h2>
This EIP is largely based on the previous non-official documentation for EVM tracing.
It tries to cover as many corner cases as possible to enable true client compatibility.
The datatypes and if a field is optional is chosen to be as compatible with current implementations as possible.</p>
Backwards Compatibility</h2>
This EIP is fully backward compatible with ethereum as it only introduces a better tracing infrastructure that is optional for clients to implement.</p>
Clients</h3>
This EIP is fully backward compatible with go-ethereum. OpenEthereum, Besu and Nethermind clients would have to change their JSON output of
openethereum-evm</code> evmtool</code> and
nethtest</code> slightly do adhere to the new and stricter specs. New clients would need to implement this change if they want to be part of the differential fuzzing group.</p>
Test Cases</h2>
$</span>{</span>BESU_HOME</span>}</span>/bin/evmtool --code 0x604080536040604055604060006040600060025afa6040f3 </span>{</span>"</span>pc</span>"</span>:0,</span>"</span>op</span>"</span>:96,</span>"</span>gas</span>"</span>:</span>"</span>0x2540be400</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0x3</span>"</span>,</span>"</span>memSize</span>"</span>:0,</span>"</span>stack</span>"</span>:</span>[</span>]</span>,</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>PUSH1</span>"</span>}</span></span>
{</span>"</span>pc</span>"</span>:2,</span>"</span>op</span>"</span>:128,</span>"</span>gas</span>"</span>:</span>"</span>0x2540be3fd</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0x3</span>"</span>,</span>"</span>memSize</span>"</span>:0,</span>"</span>stack</span>"</span>:</span>[</span>"</span>0x40</span>"</span>],</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>DUP1</span>"</span>}</span></span>
{</span>"</span>pc</span>"</span>:3,</span>"</span>op</span>"</span>:83,</span>"</span>gas</span>"</span>:</span>"</span>0x2540be3fa</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0xc</span>"</span>,</span>"</span>memSize</span>"</span>:0,</span>"</span>stack</span>"</span>:</span>[</span>"</span>0x40</span>"</span>,</span>"</span>0x40</span>"</span>],</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>MSTORE8</span>"</span>}</span></span>
{</span>"</span>pc</span>"</span>:4,</span>"</span>op</span>"</span>:96,</span>"</span>gas</span>"</span>:</span>"</span>0x2540be3ee</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0x3</span>"</span>,</span>"</span>memory</span>"</span>:</span>"</span>0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span>"</span>,</span>"</span>memSize</span>"</span>:96,</span>"</span>stack</span>"</span>:</span>[</span>]</span>,</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>PUSH1</span>"</span>}</span></span>
{</span>"</span>pc</span>"</span>:6,</span>"</span>op</span>"</span>:96,</span>"</span>gas</span>"</span>:</span>"</span>0x2540be3eb</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0x3</span>"</span>,</span>"</span>memory</span>"</span>:</span>"</span>0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span>"</span>,</span>"</span>memSize</span>"</span>:96,</span>"</span>stack</span>"</span>:</span>[</span>"</span>0x40</span>"</span>],</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>PUSH1</span>"</span>}</span></span>
{</span>"</span>pc</span>"</span>:8,</span>"</span>op</span>"</span>:85,</span>"</span>gas</span>"</span>:</span>"</span>0x2540be3e8</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0x4e20</span>"</span>,</span>"</span>memory</span>"</span>:</span>"</span>0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span>"</span>,</span>"</span>memSize</span>"</span>:96,</span>"</span>stack</span>"</span>:</span>[</span>"</span>0x40</span>"</span>,</span>"</span>0x40</span>"</span>],</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>SSTORE</span>"</span>}</span></span>
{</span>"</span>pc</span>"</span>:9,</span>"</span>op</span>"</span>:96,</span>"</span>gas</span>"</span>:</span>"</span>0x2540b95c8</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0x3</span>"</span>,</span>"</span>memory</span>"</span>:</span>"</span>0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span>"</span>,</span>"</span>memSize</span>"</span>:96,</span>"</span>stack</span>"</span>:</span>[</span>]</span>,</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>PUSH1</span>"</span>}</span></span>
{</span>"</span>pc</span>"</span>:11,</span>"</span>op</span>"</span>:96,</span>"</span>gas</span>"</span>:</span>"</span>0x2540b95c5</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0x3</span>"</span>,</span>"</span>memory</span>"</span>:</span>"</span>0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span>"</span>,</span>"</span>memSize</span>"</span>:96,</span>"</span>stack</span>"</span>:</span>[</span>"</span>0x40</span>"</span>],</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>PUSH1</span>"</span>}</span></span>
{</span>"</span>pc</span>"</span>:13,</span>"</span>op</span>"</span>:96,</span>"</span>gas</span>"</span>:</span>"</span>0x2540b95c2</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0x3</span>"</span>,</span>"</span>memory</span>"</span>:</span>"</span>0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span>"</span>,</span>"</span>memSize</span>"</span>:96,</span>"</span>stack</span>"</span>:</span>[</span>"</span>0x40</span>"</span>,</span>"</span>0x0</span>"</span>],</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>PUSH1</span>"</span>}</span></span>
{</span>"</span>pc</span>"</span>:15,</span>"</span>op</span>"</span>:96,</span>"</span>gas</span>"</span>:</span>"</span>0x2540b95bf</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0x3</span>"</span>,</span>"</span>memory</span>"</span>:</span>"</span>0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span>"</span>,</span>"</span>memSize</span>"</span>:96,</span>"</span>stack</span>"</span>:</span>[</span>"</span>0x40</span>"</span>,</span>"</span>0x0</span>"</span>,</span>"</span>0x40</span>"</span>],</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>PUSH1</span>"</span>}</span></span>
{</span>"</span>pc</span>"</span>:17,</span>"</span>op</span>"</span>:96,</span>"</span>gas</span>"</span>:</span>"</span>0x2540b95bc</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0x3</span>"</span>,</span>"</span>memory</span>"</span>:</span>"</span>0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span>"</span>,</span>"</span>memSize</span>"</span>:96,</span>"</span>stack</span>"</span>:</span>[</span>"</span>0x40</span>"</span>,</span>"</span>0x0</span>"</span>,</span>"</span>0x40</span>"</span>,</span>"</span>0x0</span>"</span>],</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>PUSH1</span>"</span>}</span></span>
{</span>"</span>pc</span>"</span>:19,</span>"</span>op</span>"</span>:90,</span>"</span>gas</span>"</span>:</span>"</span>0x2540b95b9</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0x2</span>"</span>,</span>"</span>memory</span>"</span>:</span>"</span>0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span>"</span>,</span>"</span>memSize</span>"</span>:96,</span>"</span>stack</span>"</span>:</span>[</span>"</span>0x40</span>"</span>,</span>"</span>0x0</span>"</span>,</span>"</span>0x40</span>"</span>,</span>"</span>0x0</span>"</span>,</span>"</span>0x2</span>"</span>],</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>GAS</span>"</span>}</span></span>
{</span>"</span>pc</span>"</span>:20,</span>"</span>op</span>"</span>:250,</span>"</span>gas</span>"</span>:</span>"</span>0x2540b95b7</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0x24abb676c</span>"</span>,</span>"</span>memory</span>"</span>:</span>"</span>0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span>"</span>,</span>"</span>memSize</span>"</span>:96,</span>"</span>stack</span>"</span>:</span>[</span>"</span>0x40</span>"</span>,</span>"</span>0x0</span>"</span>,</span>"</span>0x40</span>"</span>,</span>"</span>0x0</span>"</span>,</span>"</span>0x2</span>"</span>,</span>"</span>0x2540b95b7</span>"</span>],</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>STATICCALL</span>"</span>}</span></span>
{</span>"</span>pc</span>"</span>:21,</span>"</span>op</span>"</span>:96,</span>"</span>gas</span>"</span>:</span>"</span>0x2540b92a7</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0x3</span>"</span>,</span>"</span>memory</span>"</span>:</span>"</span>0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b00000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span>"</span>,</span>"</span>memSize</span>"</span>:96,</span>"</span>stack</span>"</span>:</span>[</span>"</span>0x1</span>"</span>],</span>"</span>returnData</span>"</span>:</span>"</span>0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b</span>"</span>,</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>PUSH1</span>"</span>}</span></span>
{</span>"</span>pc</span>"</span>:23,</span>"</span>op</span>"</span>:243,</span>"</span>gas</span>"</span>:</span>"</span>0x2540b92a4</span>"</span>,</span>"</span>gasCost</span>"</span>:</span>"</span>0x0</span>"</span>,</span>"</span>memory</span>"</span>:</span>"</span>0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b00000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span>"</span>,</span>"</span>memSize</span>"</span>:96,</span>"</span>stack</span>"</span>:</span>[</span>"</span>0x1</span>"</span>,</span>"</span>0x40</span>"</span>],</span>"</span>returnData</span>"</span>:</span>"</span>0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b</span>"</span>,</span>"</span>depth</span>"</span>:1,</span>"</span>refund</span>"</span>:0,</span>"</span>opName</span>"</span>:</span>"</span>RETURN</span>"</span>}</span></span>
{</span>"</span>stateRoot</span>"</span>:</span>"</span>0x8fa0dcc7f1d2383c89e5737c2843632db881c0946e80b71fe7175365e6538797</span>"</span>,</span>"</span>output</span>"</span>:</span>"</span>0x40</span>"</span>,</span>"</span>gasUsed</span>"</span>:</span>"</span>0x515c</span>"</span>,</span>"</span>pass</span>"</span>:true,</span>"</span>fork</span>"</span>:</span>"</span>Istanbul</span>"</span>}</span></span></code></pre>Security Considerations</h2>
Tracing is expensive.</p>
Exposing an endpoint for creating traces publicly could open up a denial of service vector.</p>
Clients should consider putting trace endpoints behind a separate flag from other endpoints.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Slashing Protection Interchange Format
2020-10-27T00:00:00+00:00
Abstract</h2>
A standard format for transferring a key's signing history allows validators to easily switch between clients without the risk of signing conflicting messages. While a common keystore format provides part of the solution, it does not contain any information about a key's signing history. For a validator moving their keys from client A to client B, this could lead to scenarios in which client B inadvertently signs a message that conflicts with an earlier message signed with client A. The interchange format described here provides a solution to this problem.</p>
Motivation</h2>
The proof of stake (PoS) protocol penalises validators for voting in ways that could result in two different versions of the chain being finalised. These types of penalties are called slashings.</p>
For a validator following the protocol correctly, there is, in principle, no risk of being slashed. However, changing clients (from client A to client B, say) can result in a slashing risk if client B is unaware of the blocks and attestations that were signed with client A.</p>
This can occur if client A and client B do not agree on what the present time is. For example, say client A's time is accidentally set to a day in the future (225 epochs), and a validator switches from client A to client B without giving B a record of the blocks and attestations signed with A. The validator in question now runs the risk of attesting to two different blocks in the same epoch (a slashable offence) for the next 225 epochs (since they've already voted on these epochs with client A, and now stand to vote on them again with client B). Such time-skew bugs have been observed in the wild.</p>
Another situation in which slashing protection is critical is in the case of re-orgs. During a re-org it is possible for a validator to be assigned new attestation duties for an epoch in which it has already signed an attestation. In this case it is essential that the record of the previous attestation is available, even if the validator just moved from one client to another in the space of a single epoch.</p>
Specification</h2>
JSON Schema</h3>
A valid interchange file is one that adheres to the following JSON schema, and is interpreted according to the Conditions</a>.</p>
{</span></span>
  "</span>title</span>"</span>:</span> "</span>Signing history</span>"</span>,</span></span>
  "</span>description</span>"</span>:</span> "</span>This schema provides a record of the blocks and attestations signed by a set of validators</span>"</span>,</span></span>
  "</span>type</span>"</span>:</span> "</span>object</span>"</span>,</span></span>
  "</span>properties</span>"</span>:</span> {</span></span>
    "</span>metadata</span>"</span>:</span> {</span></span>
      "</span>type</span>"</span>:</span> "</span>object</span>"</span>,</span></span>
      "</span>properties</span>"</span>:</span> {</span></span>
        "</span>interchange_format_version</span>"</span>:</span> {</span></span>
          "</span>type</span>"</span>:</span> "</span>string</span>"</span>,</span></span>
          "</span>description</span>"</span>:</span> "</span>The version of the interchange format that this document adheres to</span>"</span></span>
        }</span>,</span></span>
        "</span>genesis_validators_root</span>"</span>:</span> {</span></span>
          "</span>type</span>"</span>:</span> "</span>string</span>"</span>,</span></span>
          "</span>description</span>"</span>:</span> "</span>Calculated at Genesis time; serves to uniquely identify the chain</span>"</span></span>
        }</span></span>
      }</span>,</span></span>
      "</span>required</span>"</span>:</span> [</span></span>
        "</span>interchange_format_version</span>"</span>,</span></span>
        "</span>genesis_validators_root</span>"</span></span>
      ]</span></span>
    }</span>,</span></span>
    "</span>data</span>"</span>:</span> {</span></span>
      "</span>type</span>"</span>:</span> "</span>array</span>"</span>,</span></span>
      "</span>items</span>"</span>:</span> [</span></span>
        {</span></span>
          "</span>type</span>"</span>:</span> "</span>object</span>"</span>,</span></span>
          "</span>properties</span>"</span>:</span> {</span></span>
            "</span>pubkey</span>"</span>:</span> {</span></span>
              "</span>type</span>"</span>:</span> "</span>string</span>"</span>,</span></span>
              "</span>description</span>"</span>:</span> "</span>The BLS public key of the validator (encoded as a 0x-prefixed hex string)</span>"</span></span>
            }</span>,</span></span>
            "</span>signed_blocks</span>"</span>:</span> {</span></span>
              "</span>type</span>"</span>:</span> "</span>array</span>"</span>,</span></span>
              "</span>items</span>"</span>:</span> [</span></span>
                {</span></span>
                  "</span>type</span>"</span>:</span> "</span>object</span>"</span>,</span></span>
                  "</span>properties</span>"</span>:</span> {</span></span>
                    "</span>slot</span>"</span>:</span> {</span></span>
                      "</span>type</span>"</span>:</span> "</span>string</span>"</span>,</span></span>
                      "</span>description</span>"</span>:</span> "</span>The slot number of the block that was signed</span>"</span></span>
                    }</span>,</span></span>
                    "</span>signing_root</span>"</span>:</span> {</span></span>
                      "</span>type</span>"</span>:</span> "</span>string</span>"</span>,</span></span>
                      "</span>description</span>"</span>:</span> "</span>The output of compute_signing_root(block, domain)</span>"</span></span>
                    }</span></span>
                  }</span>,</span></span>
                  "</span>required</span>"</span>:</span> [</span></span>
                    "</span>slot</span>"</span></span>
                  ]</span></span>
                }</span></span>
              ]</span></span>
            }</span>,</span></span>
            "</span>signed_attestations</span>"</span>:</span> {</span></span>
              "</span>type</span>"</span>:</span> "</span>array</span>"</span>,</span></span>
              "</span>items</span>"</span>:</span> [</span></span>
                {</span></span>
                  "</span>type</span>"</span>:</span> "</span>object</span>"</span>,</span></span>
                  "</span>properties</span>"</span>:</span> {</span></span>
                    "</span>source_epoch</span>"</span>:</span> {</span></span>
                      "</span>type</span>"</span>:</span> "</span>string</span>"</span>,</span></span>
                      "</span>description</span>"</span>:</span> "</span>The attestation.data.source.epoch of the signed attestation</span>"</span></span>
                    }</span>,</span></span>
                    "</span>target_epoch</span>"</span>:</span> {</span></span>
                      "</span>type</span>"</span>:</span> "</span>string</span>"</span>,</span></span>
                      "</span>description</span>"</span>:</span> "</span>The attestation.data.target.epoch of the signed attestation</span>"</span></span>
                    }</span>,</span></span>
                    "</span>signing_root</span>"</span>:</span> {</span></span>
                      "</span>type</span>"</span>:</span> "</span>string</span>"</span>,</span></span>
                      "</span>description</span>"</span>:</span> "</span>The output of compute_signing_root(attestation, domain)</span>"</span></span>
                    }</span></span>
                  }</span>,</span></span>
                  "</span>required</span>"</span>:</span> [</span></span>
                    "</span>source_epoch</span>"</span>,</span></span>
                    "</span>target_epoch</span>"</span></span>
                  ]</span></span>
                }</span></span>
              ]</span></span>
            }</span></span>
          }</span>,</span></span>
          "</span>required</span>"</span>:</span> [</span></span>
            "</span>pubkey</span>"</span>,</span></span>
            "</span>signed_blocks</span>"</span>,</span></span>
            "</span>signed_attestations</span>"</span></span>
          ]</span></span>
        }</span></span>
      ]</span></span>
    }</span></span>
  }</span>,</span></span>
  "</span>required</span>"</span>:</span> [</span></span>
    "</span>metadata</span>"</span>,</span></span>
    "</span>data</span>"</span></span>
  ]</span></span>
}</span></span></code></pre>Example JSON Instance</h3>
{</span></span>
  "</span>metadata</span>"</span>:</span> {</span></span>
    "</span>interchange_format_version</span>"</span>:</span> "</span>5</span>"</span>,</span></span>
    "</span>genesis_validators_root</span>"</span>:</span> "</span>0x04700007fabc8282644aed6d1c7c9e21d38a03a0c4ba193f3afe428824b3a673</span>"</span></span>
  }</span>,</span></span>
  "</span>data</span>"</span>:</span> [</span></span>
    {</span></span>
      "</span>pubkey</span>"</span>:</span> "</span>0xb845089a1457f811bfc000588fbb4e713669be8ce060ea6be3c6ece09afc3794106c91ca73acda5e5457122d58723bed</span>"</span>,</span></span>
      "</span>signed_blocks</span>"</span>:</span> [</span></span>
        {</span></span>
          "</span>slot</span>"</span>:</span> "</span>81952</span>"</span>,</span></span>
          "</span>signing_root</span>"</span>:</span> "</span>0x4ff6f743a43f3b4f95350831aeaf0a122a1a392922c45d804280284a69eb850b</span>"</span></span>
        }</span>,</span></span>
        {</span></span>
          "</span>slot</span>"</span>:</span> "</span>81951</span>"</span></span>
        }</span></span>
      ]</span>,</span></span>
      "</span>signed_attestations</span>"</span>:</span> [</span></span>
        {</span></span>
          "</span>source_epoch</span>"</span>:</span> "</span>2290</span>"</span>,</span></span>
          "</span>target_epoch</span>"</span>:</span> "</span>3007</span>"</span>,</span></span>
          "</span>signing_root</span>"</span>:</span> "</span>0x587d6a4f59a58fe24f406e0502413e77fe1babddee641fda30034ed37ecc884d</span>"</span></span>
        }</span>,</span></span>
        {</span></span>
          "</span>source_epoch</span>"</span>:</span> "</span>2290</span>"</span>,</span></span>
          "</span>target_epoch</span>"</span>:</span> "</span>3008</span>"</span></span>
        }</span></span>
      ]</span></span>
    }</span></span>
  ]</span></span>
}</span></span></code></pre>Conditions</h3>
After importing an interchange file with data field data</code>, a signer must respect the following conditions:</p>


Refuse to sign any block that is slashable with respect to the blocks contained in data.signed_blocks</code>. For details of what constitutes a slashable block, see process_proposer_slashing</code> (from consensus-specs</code>). If the signing_root</code> is absent from a block, a signer must assume that any new block with the same slot</code> is slashable with respect to the imported block.</p>
</li>

Refuse to sign any block with slot <= min(b.slot for b in data.signed_blocks if b.pubkey == proposer_pubkey)</code>, except if it is a repeat signing as determined by the signing_root</code>.</p>
</li>

Refuse to sign any attestation that is slashable with respect to the attestations contained in data.signed_attestations</code>. For details of what constitutes a slashable attestation, see is_slashable_attestation_data</code>.</p>
</li>

Refuse to sign any attestation with source epoch less than the minimum source epoch present in that signer's attestations (as seen in data.signed_attestations</code>). In pseudocode:</p>
</li>
</ol>
source</span>.</span>epoch</span> <</span></span>
    min</span>(</span>att</span>.</span>source_epoch</span></span>
        for</span> att</span> in</span> data</span>.</span>signed_attestations</span></span>
        if</span> att</span>.</span>pubkey</span> ==</span> attester_pubkey</span>)</span></span></code></pre>
{:start="5"}
5. Refuse to sign any attestation with target epoch less than or equal to the minimum target epoch present in that signer's attestations (as seen in data.signed_attestations</code>), except if it is a repeat signing as determined by the signing_root</code>. In pseudocode:</p>
target_epoch</span> <=</span></span>
    min</span>(</span>att</span>.</span>target_epoch</span></span>
        for</span> att</span> in</span> data</span>.</span>signed_attestations</span></span>
        if</span> att</span>.</span>pubkey</span> ==</span> attester_pubkey</span>)</span></span></code></pre>Additional Information</h3>


The interchange_format_version</code> version is set to 5.</p>
</li>

A signed block or attestation's signing_root</code> refers to the message data (hash tree root) that gets signed with a BLS signature. It allows validators to re-sign and re-broadcast blocks or attestations if asked.</p>
</li>

The signed_blocks</code> signing_root</code>s are calculated using compute_signing_root(block, domain)</code>: where block</code> is the block (of type BeaconBlock</code> or BeaconBlockHeader</code>) that was signed, and domain</code> is equal to compute_domain(DOMAIN_BEACON_PROPOSER, fork, metadata.genesis_validators_root)</code>.</p>
</li>

The signed_attestations</code> signing_root</code>s are calculated using compute_signing_root(attestation, domain)</code>: where attestation</code> is the attestation (of type AttestationData</code>) that was signed, and domain</code> is equal to compute_domain(DOMAIN_BEACON_ATTESTER, fork, metadata.genesis_validators_root)</code>.</p>
</li>
</ul>
Rationale</h2>
Supporting Different Strategies</h3>
The interchange format is designed to be flexible enough to support the full variety of slashing protection strategies that clients may implement, which may be categorised into two main types:</p>

Complete</strong>: a database containing every message signed by each validator.</li>
Minimal</strong>: a database containing only the latest messages signed by each validator.</li>
</ol>
The advantage of the minimal strategy is its simplicity and succinctness. Using only the latest messages for each validator, safe slashing protection can be achieved by refusing to sign messages for slots or epochs prior.</p>
On the other hand, the complete strategy can provide safe slashing protection while also avoiding false positives (meaning that it only prevents a validator from signing if doing so would guarantee a slashing).</p>
The two strategies are unified in the interchange format through the inclusion of conditions</a> (2), (4) and (5). This allows the interchange to transfer detailed or succinct information, as desired.</p>
Integer Representation</h3>
Most fields in the JSON schema are strings. For fields in which it is possible to encode the value as either a string or an integer, strings were chosen. This choice was made in order to avoid issues with different languages supporting different ranges of integers (specifically JavaScript, where the number</code> type is a 64-bit float). If a validator is yet to sign a block or attestation, the relevant list is simply left empty.</p>
Versioning</h3>
The interchange_format_version</code> is set to 5 because the specification went through several breaking changes during its design, incorporating feedback from implementers.</p>
Backwards Compatibility</h2>
This specification is not backwards-compatible with previous draft versions that used version numbers less than 5.</p>
Security Considerations</h2>
In order to minimise risk and complexity, the format has been designed to map cleanly onto the internal database formats used by implementers. Nevertheless, there are a few pitfalls worth illuminating.</p>
Advice for Complete Databases</h3>
For implementers who use a complete record of signed messages to implement their slashing protection database, we make the following recommendations:</p>

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

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

To avoid exporting an outdated interchange file -- an action which creates a slashing risk -- your implementation should only allow the slashing protection database to be exported when the validator client or signer is stopped</em> -- in other words, when the client or signer is no longer adding new messages to the database.</li>
Similarly, your implementation should only allow an interchange file to be imported when the validator client is stopped.</li>
</ul>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>


Atomic Swap-based American Call Option Contract Standard
2019-08-17T00:00:00+00:00
Simple Summary</h2>
A standard for token contracts providing Atomic Swap-based American Call Option functionalities.</p>
Abstract</h2>
This standard provides functionality to make Atomic Swap-based American Call Option payment. The Atomic Swap protocol based on Hashed Time-Locked Contract (HTLC) 1</a></sup> has optionality 2</a></sup>, and such optionality can be utilised to construct American Call Options without trusted third party. This standard defines the common way of implementing this protocol. In particular, this EIP defines technical terms, provides interfaces, and gives reference implementations of this protocol.</p>
Motivation</h2>
Atomic Swap allows users to atomically exchange their tokens without trusted third parties while the HTLC is commonly used for the implementation. However, the HTLC-based Atomic Swap has optionality. More specifically, the swap initiator can choose to proceed or abort the swap for several hours, which gives him time for speculating according to the exchange rate. A discussion2</a></sup> shows that the HTLC-based Atomic Swap is equivalent to an American Call Option in finance. On the other hand,thanks to such optionality, the HTLC-based Atomic Swap can be utilised to construct American Call Options without trusted third party. A paper3</a></sup> proposes a secure Atomic-Swap-based American Call Option protocol on smart contracts. This protocol not only eliminates the arbitrage opportunity but also prevents any party from locking the other party's money maliciously. This EIP aims at providing the standard of implementing this protocol in existing token standards.</p>
Specification</h2>
The Atomic Swap-based American Call Option smart contract should follow the syntax and semantics of Ethereum smart contracts.</p>
Definitions</h3>

initiator</code>: the party who publishes the advertisement of the swap.</li>
participant</code>: the party who agrees on the advertisement and participates in the swap with initiator</code>.</li>
asset</code>: the amount of token(s) to be exchanged.</li>
premium</code>: the amount of token(s) that initiator</code> pays to participant</code> as the premium.</li>
redeem</code>: the action to claim the token from the other party.</li>
refund</code>: the action to claim the token from the party herself/himself, because of timelock expiration.</li>
secrect</code>: a random string chosen by initiator</code> as the preimage of a hash.</li>
secrectHash</code>: a string equals to the hash of secrect</code>, used for constructing HTLCs.</li>
timelock</code>: a timestamp representing the timelimit, before when the asset can be redeemed, and otherwise can only be refunded.</li>
</ul>
Storage Variables</h3>
swap</h4>
This mapping stores the metadata of the swap contracts, including the parties and tokens involved. Each contract uses different secretHash</code>, and is distinguished by secretHash</code>.</p>
mapping</span>(</span>bytes32</span> =></span> Swap</span>)</span> public</span> swap</span>;</span></span></code></pre>initiatorAsset</h4>
This mapping stores the detail of the asset initiators want to sell, including the amount, the timelock and the state. It is associated with the swap contract with the same secretHash</code>.</p>
mapping</span>(</span>bytes32</span> =></span> InitiatorAsset</span>)</span> public</span> initiatorAsset</span>;</span></span></code></pre>participantAsset</h4>
This mapping stores the details of the asset participants want to sell, including the amount, the timelock and the state. It is associated with the swap contract with the same secretHash</code>.</p>
mapping</span>(</span>bytes32</span> =></span> ParticipantAsset</span>)</span> public</span> participantAsset</span>;</span></span></code></pre>premiumAsset</h4>
This mapping stores the details of the premium initiators attach in the swap contract, including the amount, the timelock and the state. It is associated with the swap contract with the same secretHash</code>.</p>
mapping</span>(</span>bytes32</span> =></span> Premium</span>)</span> public</span> premium</span>;</span></span></code></pre>Methods</h3>
setup</h4>
This function sets up the swap contract, including the both parties involved, the tokens to exchanged, and so on.</p>
function</span> setup</span>(</span>bytes32</span> secretHash</span>,</span> address</span> payable</span> initiator</span>,</span> address</span> tokenA</span>,</span> address</span> tokenB</span>,</span> uint256</span> initiatorAssetAmount</span>,</span> address</span> payable</span> participant</span>,</span> uint256</span> participantAssetAmount</span>,</span> uint256</span> premiumAmount</span>)</span> public</span> payable</span></span></code></pre>initiate</h4>
The initiator invokes this function to fill and lock the token she/he wants to sell and join the contract.</p>
function</span> initiate</span>(</span>bytes32</span> secretHash</span>,</span> uint256</span> assetRefundTime</span>)</span> public</span> payable</span></span></code></pre>fillPremium</h4>
The initiator invokes this function to fill and lock the premium.</p>
function</span> fillPremium</span>(</span>bytes32</span> secretHash</span>,</span> uint256</span> premiumRefundTime</span>)</span> public</span> payable</span></span></code></pre>participate</h4>
The participant invokes this function to fill and lock the token she/he wants to sell and join the contract.</p>
function</span> participate</span>(</span>bytes32</span> secretHash</span>,</span> uint256</span> assetRefundTime</span>)</span> public</span> payable</span></span></code></pre>redeemAsset</h4>
One of the parties invokes this function to get the token from the other party, by providing the preimage of the hash lock secret</code>.</p>
function</span> redeemAsset</span>(</span>bytes32</span> secret</span>,</span> bytes32</span> secretHash</span>)</span> public</span></span></code></pre>refundAsset</h4>
One of the parties invokes this function to get the token back after the timelock expires.</p>
function</span> refundAsset</span>(</span>bytes32</span> secretHash</span>)</span> public</span></span></code></pre>redeemPremium</h4>
The participant invokes this function to get the premium. This can be invoked only if the participant has already invoked participate</code> and the participant's token is redeemed or refunded.</p>
function</span> redeemPremium</span>(</span>bytes32</span> secretHash</span>)</span> public</span></span></code></pre>refundPremium</h4>
The initiator invokes this function to get the premium back after the timelock expires.</p>
function</span> refundPremium</span>(</span>bytes32</span> secretHash</span>)</span> public</span></span></code></pre>Events</h3>
SetUp</h4>
This event indicates that one party has set up the contract using the function setup()</code>.</p>
event</span> SetUp</span>(</span>bytes32</span> secretHash</span>, </span>address</span> initiator</span>, </span>address</span> participant</span>, </span>address</span> tokenA</span>, </span>address</span> tokenB</span>, </span>uint256</span> initiatorAssetAmount</span>, </span>uint256</span> participantAssetAmount</span>, </span>uint256</span> premiumAmount</span>)</span>;</span></span></code></pre>Initiated</h4>
This event indicates that initiator</code> has filled and locked the token to be exchanged using the function initiate()</code>.</p>
event</span> Initiated</span>(</span>uint256</span> initiateTimestamp</span>, </span>bytes32</span> secretHash</span>, </span>address</span> initiator</span>, </span>address</span> participant</span>, </span>address</span> initiatorAssetToken</span>, </span>uint256</span> initiatorAssetAmount</span>, </span>uint256</span> initiatorAssetRefundTimestamp</span>)</span>;</span></span></code></pre>Participated</h4>
This event indicates that participant</code> has filled and locked the token to be exchanged using the function participate()</code>.</p>
event</span> Participated</span>(</span>uint256</span> participateTimestamp</span>, </span>bytes32</span> secretHash</span>, </span>address</span> initiator</span>, </span>address</span> participant</span>, </span>address</span> participantAssetToken</span>, </span>uint256</span> participantAssetAmount</span>, </span>uint256</span> participantAssetRefundTimestamp</span>)</span>;</span></span></code></pre>PremiumFilled</h4>
This event indicates that initiator</code> has filled and locked premium</code> using the function fillPremium()</code>.</p>
event</span> PremiumFilled</span>(</span>uint256</span> fillPremiumTimestamp</span>, </span>bytes32</span> secretHash</span>, </span>address</span> initiator</span>, </span>address</span> participant</span>, </span>address</span> premiumToken</span>, </span>uint256</span> premiumAmount</span>, </span>uint256</span> premiumRefundTimestamp</span>)</span>;</span></span></code></pre>InitiatorAssetRedeemed/ParticipantAssetRedeemed</h4>
These two events indicate that asset</code> has been redeemed by the other party before the timelock by providing secret</code>.</p>
event</span> InitiatorAssetRedeemed</span>(</span>uint256</span> redeemTimestamp</span>, </span>bytes32</span> secretHash</span>, </span>bytes32</span> secret</span>, </span>address</span> redeemer</span>, </span>address</span> assetToken</span>, </span>uint256</span> amount</span>)</span>;</span></span></code></pre>event</span> ParticipantAssetRedeemed</span>(</span>uint256</span> redeemTimestamp</span>, </span>bytes32</span> secretHash</span>, </span>bytes32</span> secret</span>, </span>address</span> redeemer</span>, </span>address</span> assetToken</span>, </span>uint256</span> amount</span>)</span>;</span></span></code></pre>InitiatorAssetRefunded/ParticipantAssetRefunded</h4>
These two events indicate that asset</code> has been refunded by the original owner after the timelock expires.</p>
event</span> InitiatorAssetRefunded</span>(</span>uint256</span> refundTimestamp</span>, </span>bytes32</span> secretHash</span>, </span>address</span> refunder</span>, </span>address</span> assetToken</span>, </span>uint256</span> amount</span>)</span>;</span></span></code></pre>event</span> ParticipantAssetRefunded</span>(</span>uint256</span> refundTimestamp</span>, </span>bytes32</span> secretHash</span>, </span>address</span> refunder</span>, </span>address</span> assetToken</span>, </span>uint256</span> amount</span>)</span>;</span></span></code></pre>PremiumRedeemed</h4>
This event indicates that premium</code> has been redeemed by participant</code>. This implies that asset</code> is either redeemed by initiator</code> if it can provide the preimage of secrectHash</code> before  asset</code> timelock expires; or refunded by participant</code> if asset</code> timelock expires.</p>
event</span> PremiumRedeemed</span>(</span>uint256</span> redeemTimestamp</span>,</span>bytes32</span> secretHash</span>,</span>address</span> redeemer</span>,</span>address</span> token</span>,</span>uint256</span> amount</span>)</span>;</span></span></code></pre>PremiumRefunded</h4>
This event indicates that premium</code> has been refunded back to initiator</code>, because of participant</code> doesn't participate at all, by the time of premium</code> timelock expires.</p>
event</span> PremiumRefunded</span>(</span>uint256</span> refundTimestamp</span>, </span>bytes32</span> secretHash</span>, </span>address</span> refunder</span>, </span>address</span> token</span>, </span>uint256</span> amount</span>)</span>;</span></span></code></pre>Rationale</h2>

To achieve the atomicity, HTLC is used.</li>
The participant should decide whether to participate after the initiator locks the token and sets up the timelock.</li>
The initiator should decide whether to proceed the swap (redeem the tokens from the participant and reveal the preimage of the hash lock), after the participant locks the tokens and sets up the time locks.</li>
Premium is redeemable for the participant only if the participant participates in the swap and redeems the initiator's token before premium's timelock expires.</li>
Premium is refundable for the initiator only if the initiator initiates but the participant does not participate in the swap at all.</li>
</ul>
Security Considerations</h2>

The initiateTimestamp</code> should cover the whole swap process.</li>
The participant should never participate before the premium has been deposited.</li>
</ul>
Backwards Compatibility</h2>
This proposal is fully backward compatible. Functionalities of existing standards will not be affected by this proposal, as it only provides additional features to them.</p>
Implementation</h2>
Please visit here</a> to find our example implementation.</p>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>
References</h2>



Hash Time Locked Contracts</a> ↩</a></p>
</li>

An Argument For Single-Asset Lightning Network</a> ↩</a> ↩2</a></p>
</li>

On the optionality and fairness of Atomic Swaps</a> ↩</a></p>
</li>
</ol>
</section>


Add chain id to mixed-case checksum address encoding
2018-03-18T00:00:00+00:00
Simple Summary</h2>
This EIP extends EIP-55</a> by optionally adding a chain id defined by EIP-155</a> to the checksum calculation.</p>
Abstract</h2>
The EIP-55</a> was created to prevent users from losing funds by sending them to invalid addresses. This EIP extends EIP-55</a> to protect users from losing funds by sending them to addresses that are valid but that where obtained from a client of another network.For example, if this EIP is implemented, a wallet can alert the user that is trying to send funds to an Ethereum Testnet address from an Ethereum Mainnet wallet.</p>
Motivation</h2>
The motivation of this proposal is to provide a mechanism to allow software to distinguish addresses from different Ethereum based networks. This proposal is necessary because Ethereum addresses are hashes of public keys and do not include any metadata. By extending the EIP-55</a> checksum algorithm it is possible to achieve this objective.</p>
Specification</h2>
Convert the address using the same algorithm defined by EIP-55</a> but if a registered chain id is provided, add it to the input of the hash function. If the chain id passed to the function belongs to a network that opted for using this checksum variant, prefix the address with the chain id and the 0x</code> separator before calculating the hash. Then convert the address to hexadecimal, but if the ith digit is a letter (ie. it's one of abcdef</code>) print it in uppercase if the 4*ith bit of the calculated hash is 1 otherwise print it in lowercase.</p>
Rationale</h2>
Benefits:</p>

By means of a minimal code change on existing libraries, users are protected from losing funds by mixing addresses of different Ethereum based networks.</li>
</ul>
Implementation</h2>
#</span>!/usr/bin/python3</span></span>
from</span> sha3</span> import</span> keccak_256</span></span>
import</span> random</span></span>
"""</span></span>
   addr (str): Hexadecimal address, 40 characters long with 2 characters prefix</span></span>
   chainid (int): chain id from EIP-155 </span>"""</span></span>
def</span> eth_checksum_encode</span>(</span>addr</span>,</span> chainid</span>=</span>1</span>)</span>:</span></span>
    adopted_eip1191</span> =</span> [</span>30</span>,</span> 31</span>]</span></span>
    hash_input</span> =</span> str</span>(</span>chainid</span>)</span> +</span> addr</span>.</span>lower</span>(</span>)</span> if</span> chainid</span> in</span> adopted_eip1191</span> else</span> addr</span>[</span>2</span>:</span>]</span>.</span>lower</span>(</span>)</span></span>
    hash_output</span> =</span> keccak_256</span>(</span>hash_input</span>.</span>encode</span>(</span>'</span>utf8</span>'</span>)</span>)</span>.</span>hexdigest</span>(</span>)</span></span>
    aggregate</span> =</span> zip</span>(</span>addr</span>[</span>2</span>:</span>]</span>.</span>lower</span>(</span>)</span>,</span>hash_output</span>)</span></span>
    out</span> =</span> addr</span>[</span>:</span>2</span>]</span> +</span> '</span>'</span>.</span>join</span>(</span>[</span>c</span>.</span>upper</span>(</span>)</span> if</span> int</span>(</span>a</span>,</span>16</span>)</span> >=</span> 8</span> else</span> c</span> for</span> c</span>,</span>a</span> in</span> aggregate</span>]</span>)</span></span>
    return</span> out</span></span></code></pre>Test Cases</h2>
eth_mainnet</span> =</span> [</span></span>
"</span>0x27b1fdb04752bbc536007a920d24acb045561c26</span>"</span>,</span></span>
"</span>0x3599689E6292b81B2d85451025146515070129Bb</span>"</span>,</span></span>
"</span>0x42712D45473476b98452f434e72461577D686318</span>"</span>,</span></span>
"</span>0x52908400098527886E0F7030069857D2E4169EE7</span>"</span>,</span></span>
"</span>0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed</span>"</span>,</span></span>
"</span>0x6549f4939460DE12611948b3f82b88C3C8975323</span>"</span>,</span></span>
"</span>0x66f9664f97F2b50F62D13eA064982f936dE76657</span>"</span>,</span></span>
"</span>0x8617E340B3D01FA5F11F306F4090FD50E238070D</span>"</span>,</span></span>
"</span>0x88021160C5C792225E4E5452585947470010289D</span>"</span>,</span></span>
"</span>0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb</span>"</span>,</span></span>
"</span>0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB</span>"</span>,</span></span>
"</span>0xde709f2102306220921060314715629080e2fb77</span>"</span>,</span></span>
"</span>0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359</span>"</span>,</span></span>
]</span></span>
rsk_mainnet</span> =</span> [</span></span>
"</span>0x27b1FdB04752BBc536007A920D24ACB045561c26</span>"</span>,</span></span>
"</span>0x3599689E6292B81B2D85451025146515070129Bb</span>"</span>,</span></span>
"</span>0x42712D45473476B98452f434E72461577d686318</span>"</span>,</span></span>
"</span>0x52908400098527886E0F7030069857D2E4169ee7</span>"</span>,</span></span>
"</span>0x5aaEB6053f3e94c9b9a09f33669435E7ef1bEAeD</span>"</span>,</span></span>
"</span>0x6549F4939460DE12611948B3F82B88C3C8975323</span>"</span>,</span></span>
"</span>0x66F9664f97f2B50F62d13EA064982F936de76657</span>"</span>,</span></span>
"</span>0x8617E340b3D01Fa5f11f306f4090fd50E238070D</span>"</span>,</span></span>
"</span>0x88021160c5C792225E4E5452585947470010289d</span>"</span>,</span></span>
"</span>0xD1220A0Cf47c7B9BE7a2e6ba89F429762E7B9adB</span>"</span>,</span></span>
"</span>0xDBF03B407c01E7CD3cBea99509D93F8Dddc8C6FB</span>"</span>,</span></span>
"</span>0xDe709F2102306220921060314715629080e2FB77</span>"</span>,</span></span>
"</span>0xFb6916095cA1Df60bb79ce92cE3EA74c37c5d359</span>"</span>,</span></span>
]</span></span>
rsk_testnet</span> =</span> [</span></span>
"</span>0x27B1FdB04752BbC536007a920D24acB045561C26</span>"</span>,</span></span>
"</span>0x3599689e6292b81b2D85451025146515070129Bb</span>"</span>,</span></span>
"</span>0x42712D45473476B98452F434E72461577D686318</span>"</span>,</span></span>
"</span>0x52908400098527886E0F7030069857D2e4169EE7</span>"</span>,</span></span>
"</span>0x5aAeb6053F3e94c9b9A09F33669435E7EF1BEaEd</span>"</span>,</span></span>
"</span>0x6549f4939460dE12611948b3f82b88C3c8975323</span>"</span>,</span></span>
"</span>0x66f9664F97F2b50f62d13eA064982F936DE76657</span>"</span>,</span></span>
"</span>0x8617e340b3D01fa5F11f306F4090Fd50e238070d</span>"</span>,</span></span>
"</span>0x88021160c5C792225E4E5452585947470010289d</span>"</span>,</span></span>
"</span>0xd1220a0CF47c7B9Be7A2E6Ba89f429762E7b9adB</span>"</span>,</span></span>
"</span>0xdbF03B407C01E7cd3cbEa99509D93f8dDDc8C6fB</span>"</span>,</span></span>
"</span>0xDE709F2102306220921060314715629080e2Fb77</span>"</span>,</span></span>
"</span>0xFb6916095CA1dF60bb79CE92ce3Ea74C37c5D359</span>"</span>,</span></span>
]</span></span>
test_cases</span> =</span> {</span>30</span> :</span> rsk_mainnet</span>,</span> 31</span> :</span> rsk_testnet</span>,</span> 1</span> :</span> eth_mainnet</span>}</span></span>
</span>
for</span> chainid</span>,</span> cases</span> in</span> test_cases</span>.</span>items</span>(</span>)</span>:</span></span>
    for</span> addr</span> in</span> cases</span>:</span></span>
        assert</span> (</span> addr</span> ==</span> eth_checksum_encode</span>(</span>addr</span>,</span>chainid</span>)</span> )</span></span></code></pre>Usage</h2>
Usage  Table</h3>
Network</th> Chain id</th> Supports this EIP</th></tr></thead>

RSK Mainnet</td> 30</td> Yes</td></tr>
RSK Testnet</td> 31</td> Yes</td></tr>
</tbody></table>
Implementation Table</h3>
Project</th> EIP Usage</th> Implementation</th></tr></thead>

MyCrypto</td> Yes</td> JavaScript</a></td></tr>
MyEtherWallet</td> Yes</td> JavaScript</a></td></tr>
Ledger</td> Yes</td> C</a></td></tr>
Trezor</td> Yes</td> Python</a> and C</a></td></tr>
Web3.js</td> Yes</td> JavaScript</a></td></tr>
EthereumJS-util</td> Yes</td> JavaScript</a></td></tr>
ENS address-encoder</td> Yes</td> TypeScript</a></td></tr>
</tbody></table>
Copyright</h2>
Copyright and related rights waived via CC0</a>.</p>